Files
deepseek-harness/packages/sdk/protocol
Tianyi Cui 8fd7ff69e3 fix(sdk): reject unrepresented session activity failures
A summary can fail while appending turn/start or turn/end and still leave
the root idle with a stable Session sequence. The SDK wait operation then
returned {}, letting the external provider treat the preceding completed
terminal as the result of the entire task. A listener installed only for
the wait would also miss failures between prompt admission and the wait
request.

Retain one latest live failure on each existing SDK Session record, scoped
to the exact owned Agent. Record the Session's next log offset when the
failure occurs. A turn/end from the exact owned Session clears it only
when that terminal was committed at or after that offset. This preserves
failures raised during terminal publication, keeps ordinary represented
turn errors in the durable outcome, and permits later successful activity
to recover. At stable root/descendant completion, session/wait rejects any
remaining failure. Raw session.status and HarnessSession.run behavior are
unchanged; no generic failure history or new notification is introduced.

Add seven owner-local cases for later start/end failures before and during
wait, subsequent successful prompts, represented errors, and publication
ordering including an undefined thrown value. Six failure cases returned
success before the fix. Strengthen listener teardown coverage to assert
all actual subscriptions are disposed after a disposer fails.

Extend the existing recorded subagent-continuable SDK scenario to exercise
session/wait. It still asserts that run() returns DONE at parent turn 1,
then requires child completion and parent turn 2/idle plus its final
summary to be delivered before the wait response. Bypassing the wait made
that ordering assertion fail. No recorded Session or golden output was
invented or refreshed. Update the protocol/server bilingual READMEs and
regenerate the event-consumer matrix for the new error listener.

Validation:
- pnpm exec vitest run packages/sdk/server/tests/wait.spec.ts before the fix:
  6 failed, 1 passed (the represented-error case)
- pnpm exec vitest run packages/sdk/server/tests/server.spec.ts packages/sdk/server/tests/wait.spec.ts (40 passed)
- pnpm run test:e2e packages/subagent/subagent-dsh-sdk/tests/nested-delegation.e2e.ts packages/subagent/subagent-dsh-sdk/tests/loader-composition.e2e.ts (8 passed)
- DSH_EXAMPLE_MODE=lib pnpm run test:e2e packages/subagent/subagent-dsh-sdk/tests/nested-delegation.e2e.ts packages/subagent/subagent-dsh-sdk/tests/loader-composition.e2e.ts (8 passed)
- pnpm run test:snapshot snapshots/sdk/sdk.snapshot.ts -t 'replays subagent-continuable through dsh --profile sdk' (1 passed, 24 unselected)
- pnpm run doc-sync: Host compile/bundle, doc-typecheck and 40 other gates
  passed; the generated event graph was stale, then regenerated and passed
  pnpm run verify-doc-graphs (all 7 graph docs current)
- pnpm run lint:contracts-ready and focused lint of all changed SDK code
- named translation pairing checks and git diff --check

Independent SDK rereview and 7/7 focused tests found no remaining issue.
The parent task owns unchanged Python advanced/recovery validation on the
combined branch; this commit changes no Python or high-level SDK results.
2026-10-06 01:03:30 +08:00
..
2026-10-03 10:46:11 +08:00

description, kind
description kind
The SDK wire protocol for client and server implementers: the newline-delimited JSON-RPC transport and the named request, result, and notification types spoken between a Harness runtime and its SDK clients. package-library

@deepseek-ai/dsh-sdk-protocol

English | 中文

Summary

dsh-sdk-protocol lets a DeepSeek Harness runtime and its SDK clients exchange JSON-RPC 2.0 messages over newline-delimited byte streams: one transport class plus the named request, result, and notification types both wire ends speak. The serving side is the dsh-sdk-jsonrpc-server plugin; the clients are the TypeScript dsh-sdk-client and the Python SDK, which mirrors these shapes without importing them. Use this package when you implement or debug a wire end: framing rules, method names, payload types, and error semantics all live here. It is a pure library — no plugin, no configuration, no registrations.

Table of Contents


Use this package

Use this package when you build or debug an SDK wire end — the serving plugin, a client library, or custom tooling that speaks the SDK protocol. It gives you one transport for JSON-RPC 2.0 over caller-owned byte streams and the typed shapes for every SDK method and notification.

Framing and transport

Wire one JSON-RPC 2.0 message per \n-terminated line over byte streams you own. A frame with both id and method is a request, id alone is a response, and method alone is a notification; malformed lines are ignored. Requests with no registered handler answer -32601, handler failures answer -32603, and error responses reject the pending request with JsonRpcResponseError, which preserves the wire code and optional data. start() attaches stream listeners and close() detaches them and rejects pending requests without destroying the streams.

The SDK methods

Both wire ends share one method set: four client-to-server requests and four server-to-client notifications.

Direction Method Payload types
client→server initialize InitializeParams → InitializeResult
client→server session/prompt SessionPromptParams → SessionPromptResult (durable enqueue receipt)
client→server session/wait SessionWaitParams → {}
client→server shutdown no params → {}
server→client session.event SessionEventNotification (every session in the runtime, unfiltered)
server→client session.status SessionStatusNotification (whole-agent running/idle transition)
server→client subagent.started SubagentStartedNotification
server→client subagent.finished SubagentFinishedNotification (in-process runs only)

HarnessSdkRequestMap and HarnessSdkNotificationMap index these shapes by method name; the package root exports them together with the transport.

session/wait accepts { sessionId } for an existing SDK-owned session and returns {} after the root stays idle with no managed descendants. Unknown ids and live Agent failures without a newer committed terminal are rejected. Notifications committed during the wait precede its response on the same transport; raw session.status transitions retain their whole-agent meaning.

Payload semantics

SessionPromptResult.messageId identifies the queued user message; it does not identify a later assistant message, turn ending, or prompt result. SdkPromptContentBlock accepts ordinary durable content plus SdkEncodedImageBlock { type: "image", data, mimeType }; the server converts encoded images to durable references before enqueue. InitializeParams.reasoningEffort is an optional non-empty adapter-owned identifier for the selected provider/model route; omission preserves that model's default. InitializeParams.maxTokens is an optional positive safe integer that caps each conversation-model output for SDK-created agents and their in-process descendants; omission lets the selected adapter's exact-model default apply. The server resolves the exact route during initialization and rejects session/prompt until that handshake succeeds, so a missing adapter, unavailable model, or unsupported effort cannot fall back to constructor defaults. SubagentFinishedNotification.lastAssistantMessage carries the child's last non-empty assistant message, or its accumulated assistant text when no such message exists; the field is absent when the child produced neither. serverInfo.name stays the wire-stable deepseek-harness-sdk-runtime. Notification payloads depend on SessionEvent (dsh-session), ContentBlock (dsh-llm), and SubagentStopReason (dsh-subagent), so the session vocabulary is part of the wire contract.


Understand the implementation

Implementation internals — click to expand

This section explains the design behind the wire library; the observable behavior is fully covered in Use this package.

Design concept

The package is built on one separation: a single newline-delimited transport class shared by both wire ends, and named types that index the protocol methods. The package root is the only import surface — source modules are not exported as deep imports. It is a pure library with no plugin, config, or registration; the serving plugin and the clients own all behavior around it.

Source map

File Role
src/transport.ts JsonRpcLineTransport: line framing, request/response/notification dispatch, error mapping, pending-request bookkeeping
src/types.ts Named request/result and notification payload types, indexed by method
src/index.ts Consumer interface: the transport and the named wire types

Frame dispatch

Incoming lines are parsed one at a time: a frame with id and method is answered through the request handler (or -32601), a frame with id alone resolves the matching pending request (an error frame rejects it with JsonRpcResponseError), and a frame with method alone is handed to the notification handler. start() attaches the input listeners; close() detaches them and fails every pending request without destroying the streams.


Further Exploration

Read these pages when the wire contract is not enough. They move from the serving plugin to the clients and the runnable application.


Model Experience

None, as this is a client-facing wire library; the runtime plugins behind the serving entry own all model-facing behavior.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

These limits define what the protocol does not cover or promise. They are current package constraints, not a comparison with other wire formats or a task backlog.

  • No protocol-version negotiation — the handshake carries only serverInfo.version (0.0.1, unvalidated by clients); pre-release stance, no compatibility promise.
  • No cancel or session-close methods — a client abandons a turn by closing the runtime process; see the JSON-RPC serving plugin.
  • Server→client requests are a dead capability — the transport supports them, but the server never sends one; the Python SDK's responder surface exists for future approval flows.

Dev Note

Working context for maintainers — click to expand

This Dev Note is working context for maintainers and is explicitly non-authoritative — shipped behavior and limits live in the sections above and in the code. This protocol's shapes are mirrored (not imported) by the Python SDK, so changing a method, payload, or the wire-stable serverInfo.name here requires updating the Python counterpart and the TypeScript client in the same change. No other unresolved design questions are recorded.