SDK wire: session/cancel and session/close

[AlexisDevos]

The gap

An external orchestrator driving the SDK runtime over JSON-RPC has no way to stop a turn or release one session. The READMEs name this themselves:

• packages/sdk/protocol/README.md — "No cancel or session-close methods — a client abandons a turn by closing the runtime process"
• packages/sdk/server/README.md — "The wire has no per-session close or prompt-cancel method — SDK-created agents remain live until process shutdown"

Closing the process is a blunt fallback: with many sessions on one runtime, abandoning one turn kills the others too. Any host embedding the runtime as one agent backend among several needs per-session control.

What I implemented

Two request methods, following the existing session/prompt shape:

Method	Params	Result
session/cancel	{ sessionId }	{ cancelled: boolean } — whether a live session existed and received the cancellation
session/close	{ sessionId }	{ closed: boolean } — whether a live session was disposed

Design notes, mostly about being conservative:

• session/cancel applies agent.cancel({ kind: 'user' }) — the same cancellation the ACP bridge already uses, so behavior is consistent between the two front ends. It assigns no prompt-level outcome; the cancelled activity settles through its own session.event stream, matching how session/prompt already refuses to attribute results.
• An unknown id is a no-op (false), not an error.
• session/close awaits an in-flight session creation before closing, so a pending creation cannot leak past the close. It drops the record before disposing, so a concurrent prompt cannot find a closing record.
• Durable session data stays on disk. A closed id is terminal for the wire: reusing it hits the persistence collision in session-persistence-jsonl, so callers mint a fresh id. Documented as a residual limitation rather than papered over.
• A record whose agent was disposed outside the server rejects rather than being driven, mirroring the existing liveness check in prompt.

Scope is 353 insertions across 11 files — protocol types, server methods, HarnessClient.cancelSession()/closeSession(), HarnessSession.cancel()/close(), tests, and README updates. The SDK suite passes at 107/107 with lint and typecheck clean.

Why I'm posting rather than opening a PR

CONTRIBUTING.md says external PRs aren't accepted right now, and PRs are disabled on the repo, so this is an offer rather than a request. Branch, if it's useful: master...AlexisDevos:deepseek-harness:feat/sdk-session-cancel-close

Take it, rewrite it, or ignore it. I'm posting mainly because the limitation is one your own docs flag, and I needed it for a host integration — if the shape is wrong for where you're taking the protocol, I'd rather know that than have you carry a design you didn't choose.

Known gap on my side: the README.zh.md twins are not updated, so verify-translation-pairing reports all three sdk READMEs out of sync. I didn't attempt the translation.

[argszero]

Verified against rc.7 (99f6f02fec) — this is a clean, well-scoped gap and the implementation is conservative in exactly the right places. Adding the verification layer:

1. The gap is real and self-documented. Both READMEs name it verbatim: packages/sdk/protocol/README.md:38 ("No cancel or session-close methods — a client abandons a turn by closing the runtime process") and packages/sdk/server/README.md:45 ("The wire has no per-session close or prompt-cancel method"). The server's handleRequest switch (packages/sdk/server/src/server.ts:193-205) confirms: initialize / session/prompt / shutdown only, unknown → throw. The blunt close-the-process fallback is real: shutdown() is process-global, so a multi-session runtime can't abandon one turn without killing the rest.

2. The implementation fits the existing shapes.

• session/cancel → agent.cancel({ kind: 'user' }) matches the ACP bridge's cancellation (packages/core/agent-loop/src/agent.ts:134 — cancel(cause: AgentCancelCause, options)), so behavior is consistent between front ends. Good choice.
• The session/prompt shape reuse (params { sessionId } → { cancelled: boolean }) matches the protocol's existing minimalism (packages/sdk/protocol/src/types.ts:103).
• The getOrCreateSession/sessionCreations machinery (server.ts:198-215) is the right seam for the await-in-flight-creation behavior you describe.

3. Design points that look right:

• Unknown id → no-op (false), not error — consistent with the wire's refusal to attribute prompt outcomes.
• session/close awaiting in-flight creation and dropping the record before dispose — prevents both leak and concurrent-prompt race.
• Durable data stays on disk; closed id is terminal (hits the persistence collision). Documenting the residual rather than papering over it is the right call — it keeps the wire semantics honest.

4. One thing worth double-checking (not blocking): the session/close → "reuse hits persistence collision" behavior means a crashed client (not a clean close) leaves the session id reusable, while a clean close makes it terminal — so callers can't rely on "close then re-create same id" as a reset primitive. That's defensible (it's the same collision the durable layer enforces everywhere), but worth stating explicitly in the README so integrators don't build a reconnect-on-same-id loop that works until a clean close happens.

5. On the zh.md gap — that's exactly the right thing to leave to the maintainers: the translation-pairing gate is their tooling, and a community PR shouldn't risk a wrong translation. The 107/107 + lint + typecheck is the right bar.

This is the second SDK-family contribution I've seen this week (the other being the SDK wire observability thread) — the wire is clearly where external hosts are pushing. When PRs re-open, this is ready to land as-is or near-as-is. If the maintainers want a review of the diff against the exact session/prompt handler structure, happy to do a line-by-line.

[AlexisDevos]

Thanks for digging into the actual handlers — the agent.ts:134 pointer is right, and matching the ACP bridge's cancellation was indeed the deciding factor.

On point 4, though: I went to document that asymmetry and could not reproduce it. I think the conclusion is inverted.

Terminality comes from the log existing on disk, not from the close. SessionPersistence.createCore rejects on two conditions (packages/session/session-persistence/src/index.ts):

if (this.states.has(meta.id) || this.preparations.has(meta.id))
  throw new Error(`session "${meta.id}" already exists in this backend`)
if (await this.backend.loadStored(meta.id) !== undefined)
  throw new Error(`session "${meta.id}" already has a persisted log on disk; load/resume it instead of creating`)

The disk check fires on any id whose log has been materialized, and materialization is the session's first persisted write — not something session/close triggers. A client that crashes mid-session leaves exactly the same log on disk, so its id is just as unusable for a fresh create. The in-memory half points the same way: a client crash doesn't clear the server's states, so the first branch rejects too.

So there's no clean-close-vs-crash split to warn integrators about. The honest statement is the simpler one already in the README: an id is terminal once its session has persisted anything, however it ended. A reconnect-on-same-id loop is broken from the first turn, not only after a clean close — which I'd argue is the friendlier failure, since it can't survive testing long enough to reach production.

Happy to be shown wrong if you're reading a different path — but I'd rather not add a README note that describes a distinction the persistence layer doesn't make.

[melory]

Adding a Voice Agent runtime consumer perspective: this proposal addresses a concrete integration boundary that I am currently researching.

I am designing a Python-based Voice Agent runtime in which a framework such as LiveKit Agents or Pipecat owns the real-time voice data plane:

• SIP/WebRTC and audio transport
• VAD and end-of-turn detection
• ASR and TTS
• playback buffering
• barge-in detection and immediate playback interruption

DeepSeek Harness would run as a separate cognitive/tool sidecar, accessed through the Python SDK and the stdio JSON-RPC runtime. It would own the semantic conversation, model execution, tool policy, tool event log, and potentially longer-running agent workflows.

A likely deployment model is one long-lived DSH runtime per Python worker, with multiple concurrent calls mapped to different DSH sessionId values. In that model, process-level shutdown is not a viable substitute for per-session cancellation.

A typical barge-in sequence would look like this:

1. The voice runtime commits a final ASR utterance and sends it through session/prompt.
2. DSH begins emitting assistant text deltas and may start tool activity.
3. The voice runtime streams those deltas into TTS and starts playing the response.
4. The caller interrupts while the DSH activity is still running.
5. The voice runtime immediately stops local TTS and clears the playback buffer.
6. The host must then stop the corresponding DSH activity without affecting any other call sharing the runtime.

Without session/cancel, the host can suppress late text deltas locally, but that does not actually stop the underlying model generation, tool execution, or session-log mutations. Closing the entire runtime process would also terminate unrelated sessions and turn a routine user interruption into a process-recovery problem.

For this reason, the proposed session-scoped shape looks appropriate to me:

• session/cancel { sessionId }
• session/close { sessionId }

I would, however, like the protocol contract to distinguish cancellation acceptance from cancellation settlement.

For example, { cancelled: true } can reasonably mean that the cancellation signal was accepted by a live Agent. It should not necessarily mean that every already-started tool, child process, plugin promise, or external side effect has reached quiescence. This distinction is also relevant to the tool-cancellation discussion in #3400:

#3400

For an interactive host, the important lifecycle is closer to:

cancel accepted
    -> activity stopping
    -> turn terminated
    -> session idle/quiescent

The existing session.event stream may already be sufficient for the terminal part, provided the expected event sequence is documented. Otherwise, a separate status/idle acknowledgement might be useful. The host needs a reliable point after which it can safely send the next utterance or release the session.

There is also a late-event fencing requirement. After cancellation, text deltas or tool events from the old activity may still be in transit. A host needs either:

• a stable turn/activity/generation identifier on streamed events; or
• a clearly ordered terminal event after which no more events from that activity will be emitted.

This is particularly important for voice playback, because an old text delta must never be synthesized after the caller has started a new turn.

For session/close, I think the following semantics would be useful and unsurprising:

• release the live in-memory Agent and its event subscriptions;
• reject or deterministically order concurrent prompts;
• define what happens if the session is active—cancel-and-wait, or reject as busy;
• preserve durable session data;
• do not treat close as delete or reset;
• make repeated close requests safe and idempotent where possible.

That would let a voice worker release per-call resources when a call ends while preserving the option to inspect or resume the semantic session separately.

My current source baseline is rc.7 (99f6f02fec), and I have not tested the proposed implementation branch yet. This comment is therefore consumer-design feedback rather than patch validation. From the integration side, though, the gap is real: per-session cancel and close are prerequisites for safely sharing one SDK runtime across multiple interactive sessions.

A few questions for the maintainers:

1. Is the SDK runtime intended to support long-lived, multi-session embedding of this kind?
2. Should session/cancel mean “signal accepted,” with final settlement observed through session.event?
3. Is there an intended activity or turn identifier that external hosts should use to fence late events?
4. Should session/close implicitly cancel an active turn, or require the caller to cancel and wait first?
5. Would a whenIdle-like protocol primitive be appropriate, or should clients derive idleness entirely from the event stream?

Overall, I support the proposed session/cancel and session/close direction. The main additional requirement from a Voice Agent host is a precise distinction between accepting cancellation and proving that the cancelled activity has settled.