mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00

Files

Tianyi Cui 34aabc4183 test(sdk): snapshot suite over the SDK path; docs for the SDK stack

- examples/jsonrpc-agent gains its first snapshot suite (sdk.snapshot.ts):
  the real dsh-jsonrpc-agent runtime driven through the real dsh-sdk-client,
  keyless llm-replay behind a new cordis.snapshot.yml overlay; three recorded
  scenarios (text turn, bash tool, spawn subagent) pin the notification
  stream, the SDK turn result, and the persisted parent+child session logs.
- Bilingual READMEs for dsh-sdk-protocol / dsh-sdk-client / dsh-subagent-sdk;
  sdk/ and subagent/ group tables extended; dsh-jsonrpc README points at the
  extracted protocol package; Agent Note (en+zh) owns the decision.
- The proposed make-jsonrpc-directional note is updated for the transport's
  new home and its second (client) consumer.
- Model Experience sentence allowlist entries for the two client-side
  packages; module graph + config catalog regenerated; i18n pairings
  recorded. doc-sync passes 24/24.

2026-07-27 04:37:23 +08:00

3.3 KiB

Raw Blame History

@deepseek-ai/dsh-sdk-protocol

English | 中文

The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The server side is the dsh-jsonrpc plugin; clients are dsh-sdk-client (TypeScript) and the Python SDK (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.

Transport

JsonRpcLineTransport frames JSON-RPC 2.0 over caller-owned byte streams, one compact JSON frame per \n-terminated line. Frames with id and method are requests, id alone is a response, method alone is a notification; malformed JSON lines are ignored. start() attaches stream listeners, close() detaches them and rejects pending requests without destroying the streams. Missing request handlers answer -32601; handler rejections answer -32603 with the error message. An error response rejects the pending request() with JsonRpcResponseError, which preserves the wire code and optional data. JsonRpcTransportPeer is the outbound surface (request/notify) the server class is typed against.

Wire types

types.ts names every payload of the protocol served by HarnessSdkServer:

Direction	Method	Types
client→server	`initialize`	`InitializeParams` → `InitializeResult`
client→server	`session/prompt`	`SessionPromptParams` → `SessionPromptResult` (answered only after turn settlement)
client→server	`shutdown`	no params → `{}`
server→client	`session.event`	`SessionEventNotification` (every session in the runtime, unfiltered)
server→client	`session.finished`	`SessionFinishedNotification` (one per accepted prompt)
server→client	`subagent.started`	`SubagentStartedNotification`
server→client	`subagent.finished`	`SubagentFinishedNotification` (in-process runs only)

HarnessSdkRequestMap and HarnessSdkNotificationMap index these by method name. The notification payload types depend on SessionEvent (dsh-session), ContentBlock (dsh-llm), and SubagentStopReason (dsh-subagent) — the protocol streams full session-log envelopes, so the session vocabulary is part of the wire contract. serverInfo.name stays the wire-stable deepseek-harness-sdk-runtime.

Model Experience

None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving dsh-jsonrpc entry.

KV Cache effect

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

Known Limitations and Deferred Work

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 dsh-jsonrpc README.
Server→client requests are dead capability — the transport supports them, but the server never sends one; the Python SDK's responder surface exists for future approval flows.

3.3 KiB Raw Blame History