OpenHands / OpenHands/software-agent-sdk
[Feature]: Add explicit conversation archive metadata and control-plane APIs
@neubig is already working on this.
Since Sep 14, 2026.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 539
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 137
Description
Is there an existing feature request for this?
- I have searched existing issues and feature requests, and this is not a duplicate.
Problem or Use Case
Conversation archive state is currently inferred downstream from runtime absence, notably legacy Cloud sandbox_status === "MISSING". That conflates a user-controlled retention state with an infrastructure condition. A runtime can disappear unexpectedly without the conversation being archived, and an archived conversation must remain archived even when no inner runtime exists.
Desired Behavior
Make archive state explicit and owned by the outer Agent Server. Conversation metadata should include nullable archived_at. The API should support archive, unarchive, and archived/unarchived filtering without provisioning an inner runtime. Archiving an active conversation should stop its owned runtime, while unarchiving should restore catalog visibility without automatically starting execution.
Base this work on the canonical lifecycle contract so archive and runtime state remain orthogonal.
Acceptance Criteria
- Conversation metadata contains additive
archived_at: datetime | nullstate persisted by the outer server. -
POST /api/conversations/{id}/archivearchives without starting a missing runtime. -
POST /api/conversations/{id}/unarchiverestores visibility without automatically provisioning or running. - Conversation search supports explicit archived/unarchived filtering.
- Archiving an active conversation safely stops/reaps only its owned runtime.
- Archived conversations are excluded from automatic runtime reconciliation and recovery.
- Tests prove
archived_atis independent from runtime status, including missing-runtime cases. - OpenAPI and
clients/typescriptare regenerated or updated in the same PR. - Public API documentation explains archive, unarchive, and deletion semantics.
Alternatives Considered
Treating every missing runtime as archived is simpler but incorrect: it hides recoverable failures and makes archive behavior deployment-specific.
Priority / Severity
High - Significant impact on productivity
Estimated Scope
Medium - New feature with moderate complexity
Feature Area
- Agent Server
Technical Implementation Ideas (Optional)
Persist archive metadata in the outer conversation catalog introduced by the runtime foundation. Keep archive handlers entirely outer-server-owned.
Additional Context
Dependency: the runtime lifecycle/recovery issue and #3403.
This issue was created by an AI agent (OpenHands) on behalf of the user.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.