SDK runtime: dsh-mcp-client missing from the runtime closure + no plugins-ready barrier before session/new

[kunwarshivam]

Note: after posting I found prior reports covering each piece — #1240 / #2115 (runtime closure missing dsh-mcp-client), #1239 (boot race), #1241 (no stderr diagnostics, which is why the race is silent). Please upvote those; this thread stands as an end-to-end corroboration of the three interacting in one verified setup.

Two related findings from embedding the harness via the Python SDK (deepseek-harness-sdk, node-mode runtime) with a custom Cordis composition. Sharing here since external PRs are closed; both have small fixes.

1. The SDK runtime closure omits @deepseek-ai/dsh-mcp-client

python/sdk-runtime/package.json defines the plugin set available to custom compositions, but dsh-mcp-client is not in it — so a composition that mounts an external MCP server (arguably the most common reason to write a custom composition) fails to load on the shipped runtime, and embedders must rebuild from source. The fix is the one-line mechanism the sdk-runtime README itself documents:

"@deepseek-ai/dsh-mcp-client": "workspace:^",

added to the dependencies block. verify-runtime-closure passes with it (closed graph, 110 workspace packages), and I've exercised the result end to end: dsh-llm-pi-ai (custom provider route) + dsh-mcp-client (stdio server exposing ~96 tools) + dsh-tool-fs, driven via the Python SDK, with tools discovered, registered, and called by the model.

2. session/new can outrun MCP tool sync, silently

Calling harness.run() immediately after construction creates the session before the MCP client finishes listTools() + registration. The agent then runs its entire session without any MCP tools (the request/header session event shows only fs/todo tools). Sleeping ~5s between client.start() and the first run() reliably makes the tools appear. The mcp-client README's "registers before the composition starts its first turn" holds for the plugin fiber, but nothing makes the JSON-RPC server's session/new wait on it.

Compounding factor: the failure is silent — the jsonrpc composition mounts no logger (stdout is protocol-pure by design), so the registration-failure ctx.logger.error paths emit nothing observable. An embedder sees a healthy-looking session that simply lacks tools.

Suggestions: (a) delay session/new (or the first session/prompt) until initial plugin activation settles, or expose a readiness signal in the initialize handshake; (b) ship a minimal stderr logger in the default/jsonrpc compositions.

Repro details: macOS arm64, Node 25, runtime in node mode, master as of 2026-08-13. Happy to provide the full composition and a repro script.

[zoahdev]

Shipped finding 1.

• Branch: zoahdev/deepseek-harness@fix/sdk-runtime-mcp-client-closure (cherry-pick-ready against 47f943859b)
• python/sdk-runtime/package.json: @deepseek-ai/dsh-mcp-client: workspace:^ added (with the lockfile). verify-runtime-closure passes: 110 workspace packages form a closed graph.

Finding 2 (session/new outrunning listTools() + registration) is the harder one — it needs a readiness barrier between plugin activation and the first session/new, which is a real semantics change (and the silent-failure logger gap is a separate composition-default question). I'd scope that as a maintainer-aligned design rather than ship a unilateral wait. If you can share the repro composition, I can at least pin the exact activation→readiness signal to wait on.

[kunwarshivam]

Thanks, good to have a second independent verification. Your branch matches what I tested exactly: same one-line addition, same closed-graph result (110 packages), and on my side also exercised end to end (pi-ai custom provider + mcp-client stdio server with ~96 tools + tool-fs, driven via the Python SDK in node mode, tools called by the model). So the closure fix is doubly confirmed and as low-risk as changes get, hopefully #1240 collects the votes it needs.

Agreed on issue 2 being a real semantics change that needs the team's design call. For whenever they look at it: of the options floated in #1239, gating initialize (or the first session/new) on initial plugin activation seems strictly better than a status-query mechanism, since it can't be forgotten by a client. The failure being silent (#1241) is what elevates it from papercut to trap, a readiness barrier plus a default stderr logger would each have caught it independently. Happy to contribute a repro script if the team picks this up.

[weijiafu14]

Finding 2 (the boot race) is the one I can add something real to — we solved exactly that problem, and the fix is not a sleep.

Use the awaited waterfalls as the barrier

DSH has two waterfalls that the agent loop awaits before the first model call: system-prompt/assemble and tools/pre-execute. A listener on system-prompt/assemble can hold the turn until your late registrations are done, which turns "sleep 5s and hope" into an actual barrier.

That is the shape we use: mounting is driven from agent/created (emitted on every publish path, before the loop starts), and first-turn correctness is closed by gating system-prompt/assemble on that mount completing.

But there is a trap that cost us a debugging round, and it will bite you too:

assembly.tools is snapshotted before the assemble waterfall runs.

So gating alone is not sufficient — a tool registered while your gate is holding is in ToolRuntime but not in the assembly.tools the model is about to see. You have to gate and re-fill the snapshot from the host's own tools.schemas(agent) inside the same listener. Gate without refill and you get precisely your symptom — request/header shows only the tools that existed before your registration.

That detail is why "it works if I sleep" is misleading: the sleep isn't fixing ordering, it's making the registration land before the snapshot is taken.

Two things worth adding to your report:

• A plugins-ready barrier in core would be better than every embedder rediscovering this. But if it lands, it needs to define whether it fires before or after the assembly.tools snapshot — otherwise it will be a barrier that still lets the first turn run tool-blind.
• Your point in stdout-is-protocol compositions have no diagnostics channel: `logger-console` writes to stdout only — request a stderr exporter #1241 (no stderr diagnostics) is the reason this class is expensive: the race is silent, and a first turn with a truncated tool list looks like a model failure rather than a boot ordering bug.

Finding 1 — I have nothing useful

The obvious suggestion would be "use a different MCP package instead". I don't think that works for your setup: the SDK runtime closure is a fixed workspace package set, so a third-party MCP package would not be in it either, for the same reason dsh-mcp-client isn't. Your one-line workspace:^ fix is the right one, and rebuilding from source is the only path until it lands. I'd rather say that than send you down a detour.

We do not modify the SDK runtime or dsh-mcp-client.

Disclosure: I maintain pi2dsh; the waterfall-gating pattern above is what we do internally and is pinned by our contract tests — you don't need our package to use it, it's the host's own seams.