Skip to content

feat: support custom session_id via ACP _meta field in new_session()#755

Open
michaelsinghk wants to merge 1 commit into
OpenHands:mainfrom
michaelsinghk:feature/acp-meta-session-id
Open

feat: support custom session_id via ACP _meta field in new_session()#755
michaelsinghk wants to merge 1 commit into
OpenHands:mainfrom
michaelsinghk:feature/acp-meta-session-id

Conversation

@michaelsinghk
Copy link
Copy Markdown

Summary

Allows ACP clients to pass a deterministic session_id through the standard ACP _meta extensibility field in session/new requests. When _meta contains a session_id key, the agent uses it instead of generating a random UUID.

Motivation

ACP clients (like Virtual Team orchestrators or CI pipelines) need deterministic session IDs to:

  • Persist and resume conversations across process restarts
  • Map agent conversations to external task IDs
  • Keep the ACP process alive while switching between multiple role-specific conversations

Currently, session/new always generates a random UUID, giving the client no control over the session identity.

Change

File: openhands_cli/acp_impl/agent/base_agent.pynew_session() method

# Before:
else:
    session_id = str(uuid.uuid4())

# After:
else:
    _meta = _kwargs.get("_meta") or {}
    custom_session_id = _meta.get("session_id")
    session_id = str(custom_session_id) if custom_session_id else str(uuid.uuid4())

7 lines inserted, 1 deleted. Purely additive — all existing behavior is preserved when _meta is absent. The _meta field is already part of the ACP protocol spec and collected by the NewSessionRequest schema.

Usage

ACP clients can now send:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/workspace",
    "_meta": {
      "session_id": "my-task-id-001"
    }
  }
}

Testing

  • Existing behavior unchanged when _meta is absent (random UUID continues)
  • Manual test confirmed: custom session_id passed via _meta is used as the conversation ID
  • Conversation persistence dir created at ~/.openhands/conversations/{custom_id}.hex/ as expected

Allows ACP clients to pass a deterministic session_id through the
standard ACP _meta extensibility field in session/new requests.

When _meta contains a 'session_id' key, the agent uses it instead of
generating a random UUID. This enables:
- Clients controlling conversation identity for persistence/resume
- Deterministic mapping between client tasks and agent conversations
- Simplified reconnection to existing conversations

The _meta field is part of the ACP protocol specification and is
already collected by the NewSessionRequest schema as field_meta.
All existing behavior is preserved when _meta is absent.

Change is purely additive — 5 lines inserted in new_session().
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant