OpenHands / OpenHands/software-agent-sdk

[Feature]: Add explicit conversation archive metadata and control-plane APIs

Open
#4,994 1 comment 0 reactions 1 assignee View on GitHub

@neubig is already working on this.

Since Sep 14, 2026.

enhancement ready-for-dev
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 | null state persisted by the outer server.
  • POST /api/conversations/{id}/archive archives without starting a missing runtime.
  • POST /api/conversations/{id}/unarchive restores 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_at is independent from runtime status, including missing-runtime cases.
  • OpenAPI and clients/typescript are 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.