Skip to content

Upgrade @agentclientprotocol/sdk from 0.14.1 to 0.21.0 to unlock 3 session lifecycle methods (resumeSession / closeSession / unstable_forkSession) #4227

@wenshao

Description

@wenshao

What would you like to be added?

Upgrade the ACP SDK from ^0.14.1 to 0.21.0 (or latest 0.21.1) in:

  • packages/cli/package.json (dependency @agentclientprotocol/sdk)
  • packages/vscode-ide-companion/package.json (same dependency)

After the upgrade, implement 3 new session lifecycle methods in packages/cli/src/acp-integration/acpAgent.ts:

Method Purpose
resumeSession(params: ResumeSessionRequest) Resume conversation from a specific message
closeSession(params: CloseSessionRequest) Explicitly close + clean up session resources
unstable_forkSession(params: ForkSessionRequest) Fork from a historical point into a new branch

The Qwen acpAgent.ts currently exposes 10 ACP methods (initialize / authenticate / newSession / loadSession / unstable_listSessions / setSessionMode / unstable_setSessionModel / setSessionConfigOption / prompt / cancel). The 3 listed above are present in the newer SDK but unimplemented.

Why is this needed?

1. IDE-side session UX is currently incomplete

listSessions + resumeSession + closeSession form the foundation primitives for any IDE-side "session manager" UI. The intended user flow:

  1. User opens Zed (or other ACP-aware IDE) on another project
  2. IDE calls listSessions → presents resumable session list
  3. User picks one → IDE calls resumeSession
  4. When done → IDE calls closeSession to free daemon resources

Without resumeSession / closeSession, Qwen Code's IDE experience is stuck at "every interaction must start a new session" — there is no way to gracefully resume or close sessions from the IDE side.

2. Comparison with OpenCode

OpenCode pins the same library at version 0.21.0 and implements all 13 methods (see packages/opencode/src/acp/agent.ts at lines L633 unstable_listSessions, L678 unstable_forkSession, L732 resumeSession, L766 closeSession). The 3-method gap is purely because Qwen's dependency is pinned 13 minor versions behind.

3. Version gap is significant

Between 0.14.1 and 0.21.0, the ACP spec released 13 intermediate versions (0.15.0 / 0.16.0 / 0.16.1 / 0.17.0 / 0.17.1 / 0.18.0 / 0.18.1 / 0.18.2 / 0.19.0 / 0.19.1 / 0.19.2 / 0.20.0 / 0.21.0). Beyond the 3 new methods, the upgrade likely brings type fixes, protocol improvements, and better alignment with the Zed ACP progress report.

4. Fork primitive complements the existing /branch slash command

Qwen Code's CLI already has a /branch command for session forking. Implementing unstable_forkSession would expose this capability to ACP-aware IDEs as well, keeping CLI and IDE feature parity.

Additional context

Suggested PR scope (incremental, low risk)

Phase 1: Library upgrade only (1 PR, ~0.5d)

  • Bump @agentclientprotocol/sdk to 0.21.0 in both package.json files
  • Add any type imports / fixes needed for existing 10 methods to compile cleanly
  • No new methods yet — validate that current functionality is unchanged

Phase 2: Method implementation (1 PR each, ~1d each)

  • closeSession — simplest, resource cleanup pattern
  • resumeSession — reuses existing session storage / load infrastructure
  • unstable_forkSession — connect to the existing /branch mechanism

Related code locations

  • Current ACP agent: packages/cli/src/acp-integration/acpAgent.ts
  • Daemon-side ACP bridge: packages/cli/src/serve/httpAcpBridge.ts (PR#3889 Stage 1, merged 2026-05-13). Note: the new methods will benefit not only IDE-direct stdio users but also remote clients going through the daemon.
  • VSCode companion ACP client: packages/vscode-ide-companion/src/services/acpConnection.ts

Capability negotiation considerations

Both Qwen and OpenCode currently negotiate protocolVersion: 1. The new methods appear under the unstable_ prefix in the SDK (unstable_forkSession, unstable_setSessionModel, etc.), so a careful capability handshake should inform clients which subset is implemented — recommend exposing this via initialize response capabilities.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions