Tianyi Cui
3368ddc0ab
Replace the TypeScript SDK's public arbitrary command/argv launch surface with the same-version dsh CLI, a named profile, ordered per-launch patches, optional process cwd, and explicit Harness home selection. Installed consumers use the built CLI; clean source checkouts use the package's src/bin.ts through an absolute tsx/esm loader and a source-only patch that omits build-generated Typert loading. Materialize explicit or inherited environments at spawn time, keep profile-internal patches below caller patches, and resolve every caller-relative path before the child starts. The SDK subagent provider validates its optional CLI and patch files at plugin load and requires an isolated absolute child home. Treat JSON-RPC initialize as the Loader-owned readiness point: Loader settlement joins entry imports, fiber lifecycle work, and synchronous effect registration, so the server needs no scheduler tick. A delayed profile entry registers a private adapter before initialize resolves, proving caller-supplied plugin routes are visible without fallback. Update sdk-app ownership, server diagnostics, TypeScript SDK examples, nested-loader coverage, and session-upload replay layering together. The following commit contains only the regenerated SDK transcripts, keeping this API and lifecycle change directly reviewable.
@deepseek-ai/dsh-sdk-jsonrpc-server
English | 中文
The jsonrpc plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. HarnessSdkJsonRpcServer owns the protocol methods and notifications; the transport and the named wire types live in dsh-sdk-protocol, shared with the client SDKs. The TypeScript client receives this server through dsh --profile sdk; the private Python runtime carrier temporarily supplies a direct-config application around it.
Wiring
inject: ['agents']. The server gets or creates one agent per sessionId. It forwards subagent completions only when the service-snapshotted lifecycle local flag is true; provider names, child ids, and durable lineage never establish locality. A registered adapter wins, an unowned deepseek-official route mounts dsh-llm-deepseek, and any other unowned provider fails initialization. Other capabilities come from the surrounding cordis.yml.
Config
maxTokensAsSuccess defaults to false and affects only the deployment-mapped status on subagent.finished; root-session prompts have no prompt-level status. JsonRpcConfig.input, output, and exit are runtime-only transport hooks; production uses process stdio and process.exit.
stdout is the protocol
Stdout carries only JSON-RPC frames. The deployment must not compose a stdout logger; diagnostics belong on stderr.
Shutdown and exit semantics
The plugin answers shutdown, flushes the response, disposes the root context so SDK-owned agents, subscriptions, and persistence reach quiescence, then exits with code 0. EOF and signal exits belong to the app bin, which also disposes the root context. Unloading only this plugin stops serving without exiting the process.
Wire notes
initialize is the runtime-readiness boundary: when the server is mounted by a Loader composition, it waits for the current plugin tree to settle before replying, so async sibling capabilities such as initial MCP tool discovery are visible to the first prompt. Hand-built contexts without Loader remain immediately usable. initialize.serverInfo.name is the wire-stable deepseek-harness-sdk-runtime. An optional positive initialize.maxTokens becomes the request output cap of each SDK-created agent and its in-process descendants; invalid values reject initialization, while omission sends no SDK cap and allows the selected adapter or provider route default to apply. session/prompt queues one identified user message and immediately returns { messageId }. The server streams every durable fact as session.event and every whole-agent lifecycle transition as session.status; it does not assign an assistant message or turn/end to that prompt. Independent requests may enqueue more work on the same session. Persistence roots and persona come from cordis.yml.
Model Experience
SDK user message
What the model sees
For each accepted session/prompt, the conversation model receives the caller-supplied contentBlocks verbatim as one user message in that SDK session. This package adds no system-prompt prose or tool schema; those come from the plugins in the surrounding cordis.yml.
Token effect
Data-dependent user-message tokens enter retained session history and are resent on later turns until another package compacts them. The JSON-RPC frames, session notifications, and server bookkeeping add zero model-context tokens.
KV Cache effect
Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
Known Limitations and Deferred Work
- The wire has no per-session close or prompt-cancel method — SDK-created agents remain live until process shutdown.
- There is no per-prompt result —
MessageIdidentifies inbox admission only; clients that own an automation interval must define and observe that interval themselves. - stdout purity is deployment-enforced — a surrounding config can still load a stdout logger and corrupt the JSON-RPC channel; this plugin does not inspect or veto sibling loggers.
- Automatic adapter mounting is DeepSeek-specific —
initializecan reuse any pre-registered model adapter, but its only fallback mountsdsh-llm-deepseek.