SDK JSON-RPC wire: server→client user-interaction requests (userQuestions / approval)

[jiaoqsh]

Context

We embed the SDK runtime (dsh-sdk-jsonrpc-server, launched via packaged-bin) as a subprocess of a non-Node host application, one runtime per session. With dsh-plan-mode + dsh-user-questions + dsh-tool-ask-user composed, the plan loop is excellent in-process — but the human-interaction seam cannot reach an embedding host across the wire:

• ctx.userQuestions expects its single active provider to be registered in-process ("UI packages provide the single active provider").
• The SDK wire defines no server→client request at all (verified at 0.1.1-rc.2): client→server initialize / session/prompt / shutdown, server→client only the session/created / session/event / agent/status / subagent/end notifications.

So exit_plan_mode's plan review and ask_user_question have no path to the human sitting on the other side of the wire, and exit_plan_mode can only fail with NO_PROVIDER.

What an embedder has to do today

We compose a small plugin whose only job is to be the provider and forward ask() to the embedding host over a loopback HTTP long-poll:

// composed into the runtime closure by the embedder
export const name = 'embedder-user-questions'
export const inject = []

export function apply(ctx, config) {
  ctx.inject(['userQuestions'], (qCtx) => {
    qCtx.userQuestions.registerProvider({
      async ask(request) {
        const { ask_id } = await postJson(`${config.endpoint}/ask`, {
          questions: request.questions,
        })
        for (;;) {
          throwIfAborted(request.signal)
          const state = await getJson(
            `${config.endpoint}/ask/${ask_id}?wait=25`, request.signal)
          if (state.status === 'pending') continue
          if (state.status === 'answered') return state.answer
          throw new Error(state.message)
        }
      },
    })
  })
}

This works end to end — the review parks host-side, the answer releases the tool call, an approved exit_plan_mode continues the same turn — but it re-implements a seam the harness already owns, and every embedder will re-invent the same plumbing (per-spawn credentials, long-poll ceilings, abort propagation, disposal semantics).

Proposal

Define a server→client JSON-RPC request on the SDK wire that makes the connected client the provider:

// server → client request
{"jsonrpc": "2.0", "id": 7, "method": "userQuestions/ask", "params": {
  "sessionId": "…",
  "questions": [{
    "id": "plan-review",
    "header": "Plan review",
    "question": "Approve this plan and leave plan mode?",
    "detail": "# …plan markdown…",
    "options": [{"label": "Approve"}, {"label": "Keep planning"}],
    "intent": {"kind": "plan-review", "approve": "Approve"}
  }]
}}

// client → server response (exactly AskUserQuestionAnswer)
{"jsonrpc": "2.0", "id": 7, "result": {
  "answers": [{"id": "plan-review", "selected": ["Approve"]}]
}}

Semantics that seem to fall out naturally:

• Capability declaration at initialize — a client that does not declare it keeps today's NO_PROVIDER behavior, so nothing changes for existing clients.
• One-active-provider invariant preserved — the wire client is the single provider for that runtime.
• Abort — request.signal firing server-side cancels the in-flight id with a notification, mirroring ASK_ABORTED.
• Answer vocabulary unchanged — the response is exactly AskUserQuestionAnswer, so intent / label semantics (including plan-review's approve-by-label) carry over without translation.

Adjacent

The same request shape would carry ctx.approval asks. dsh-host-apiproxy already models questions and approvals as answerable server→client requests (stable rpcId, replay on reconnect) on the Web mux — adding the same pair to the SDK wire would give embedders parity with what the Web host already enjoys.

Happy to adapt to whatever shape fits the protocol's direction — the ask is only: some way for the wire client to answer user questions.

[weijiafu14]

Your reading of the wire matches mine, and I can offer independent corroboration from a different DSH wire plus two contrasts that I think make this a much easier ask than it currently looks.

1. Someone else hand-rolled the same long-poll, for the same reason, on the browser wire.

I maintain an out-of-tree plugin with a browser half. It needs to push state to its own client-side UI, and DSH's typed Remote system is a first-party generated contract that an out-of-tree plugin should not impersonate — so we register our own route on ctx.webServer and the client half polls it. Our own source says so in as many words:

One prefix, one GET, one payload: the client half polls it for the session it is showing and gets every surface at once.

with setInterval(pull, 4000) in one panel and 2000 in another. That is not a design we chose; it is what is left when the channel only carries one direction. Two unrelated integrators arriving at the same loopback long-poll, on two different wires, is reasonable evidence that the gap is structural rather than specific to your embedding.

2. The capability is not missing from DSH — it is missing from the wire. That is a smaller ask.

MCP elicitation already works end to end: an MCP server asks the human a structured question mid-run, and it lands on DSH's own question surface. We have that verified on a real DSH loop with an example, and the reason it works is exactly the constraint you hit — it never crosses a process boundary; the provider is in-process and ctx.userQuestions is right there.

So the request is not "give DSH human-interaction seams". It is "the SDK JSON-RPC wire is missing a request type that the in-process path already has." I would lead with that framing, because it turns an open-ended feature into a wire-shape addition with an existing in-process semantic to mirror.

3. DSH already ships one transport with the server→client request direction — and its bug report tells you what to design for.

The ACP bridge has request_permission as a genuine server→client request. #4693 reports that an unanswered request_permission hangs the turn. That is worth reading before this is specified, because it is the failure mode that arrives with the feature: once the server can block on a client answer, "the client never answers" becomes a state the protocol has to define — timeout, cancel propagation, and what the agent loop does when the human walks away. Your workaround already gestures at this with wait=25 and an abort signal; a wire-level version needs it in the spec, not in each embedder.

Related from a third angle: #4697 asks for subagents to be able to ask the user questions. Same missing capability, different surface.

One thing I would ask explicitly in the proposal. You note that ctx.userQuestions "expects its single active provider". If a wire request is added, does it replace the provider slot for an embedded runtime, or does the embedder still register an in-process provider that forwards? The single-provider constraint means an embedder and a composed UI package are already in conflict today, and the answer determines whether an embedder can compose dsh-plan-mode alongside anything that wants the same slot.

Interest disclosure: I maintain a third-party compatibility plugin, which is where the polling evidence and the elicitation verification come from. The SDK JSON-RPC server is DSH's own component — we do not touch it and could not add this; the workaround shape you described is the same one we were left with, not a solution I am offering.

[denial123789]

The rc.2 protocol docs confirm this is above the framing layer: JsonRpcLineTransport already distinguishes bidirectional requests, responses, and notifications, while the SDK protocol explicitly calls server→client requests a “dead capability.” So the safest addition can reuse framing, but it needs more than one request type.

A few contract points I would make normative:

1. Questions and approvals stay separate. Question labels/custom text carry information; approval outcomes carry one-shot effect authority plus paired approval/asked / approval/decided audit semantics. A generic Yes/No answer must never authorize an effect.
2. Negotiate before provider registration. The client installs handlers, advertises versioned capabilities in initialize, and the server registers the wire-backed provider only for that owned connection. An existing in-process provider should produce a typed ownership conflict, not last-registration-wins.
3. Correlate five identities. Connection generation, directional JSON-RPC id, exact live root Session, question/approval id, and tool call id. Client and server request-id namespaces may use the same scalar concurrently; internal pending maps must remain directional.
4. Every wait is terminal. Valid answer, caller abort, server deadline, EOF, shutdown, and disposal settle exactly once. Late/duplicate answers cannot resume a settled tool, and timeout never auto-approves.
5. Keep the read loop non-blocking. A slow UI handler must not stop parsing cancellation, notifications, or other responses.

For current stdio ownership, transport loss should cancel pending asks during runtime disposal. Web mux replay is a useful design reference, but copying reconnect replay requires a separate process-survival and generation-transfer contract.

I wrote the full wire shapes, ownership model, cancellation state machine, loopback-workaround hardening, and 20 conformance gates here: https://sandbaseai.github.io/deepseek-harness-handbook/sdk-human-interaction-wire.html

Disclosure: I maintain the independent community handbook linked above.

[qiankunli]

We hit the approval half of this gap in a real downstream integration from Baton.

Environment

• @deepseek-ai/dsh-sdk-client@0.1.5-rc.2
• SDK profile launched as a subprocess by an embedding host
• permission preset: workspace-write (sandbox=workspace-write, approval=ask)
• current upstream master: c291e7961a515f6d7af9304e7fd1d257929aef26

The current master documentation still says that client-to-server notifications and server-to-client requests are unimplemented and reserved for future approval flows:

• packages/sdk/client/README.md
• packages/sdk/protocol/README.md

Reproduction

1. Start the SDK runtime with a workspace root.

2. Ask the agent to edit a checkout reached through a workspace symlink whose resolved path is outside that root.

3. The first edit correctly fails under workspace-write:

   Error: [sandbox: file access denied under workspace-write mode]
   

4. The agent retries the exact operation with sandbox_permissions: "danger-full-access" and a justification.

5. The runtime fails closed because the embedding host cannot answer the request:

   Error: sandbox escalation to "danger-full-access" requires approval, but no approval channel is available
   

DSH core is behaving consistently here: ctx.approval has no answerer, produces unavailable, and the tool does not execute. The missing part is that the SDK embedding host never receives an approval request, so it cannot display the question to its user and return the decision. In our case the agent had to stop and emit an applyable patch instead of completing the authorized edit.

Downstream integration boundary

Baton already has one host-owned permission interaction lifecycle for other harness adapters: open a durable permission interaction, wait for the user's decision, then return the harness-native decision. We do not need DSH to adopt Baton types. We need the SDK wire and TypeScript client to expose DSH's existing ApprovalRequest / ApprovalOutcome semantics so an embedding host can adapt them.

For the approval path, a useful acceptance contract would be:

1. The client advertises a versioned approval capability during initialization; the server only installs the wire-backed answerer when negotiated.
2. The server sends a typed request carrying the owning session, approval request id, tool call id, and tool name. The already-streamed tool call remains the source of arguments/details.
3. The client can answer with the closed one-shot outcome vocabulary; only allowed-once grants the exact action.
4. Caller abort, deadline, EOF, shutdown, and runtime disposal settle the wait exactly once and fail closed. Late or duplicate responses cannot resume a settled tool call.
5. The TypeScript client exposes a handler API for these requests rather than requiring embedders to replace the transport or compose a loopback side channel.

This would let Baton map DSH approval into its existing permission UI while preserving DSH's ownership, audit events, and fail-closed behavior.

[jiaoqsh]

Status check against master at 0.1.7-rc.2 (477b4f4): the wire is unchanged. Server→client requests are still a dead capability. Three related changes are worth folding into this discussion, and one of them points the other way.

1. A proposed simplification would remove the Python client's reverse direction.

2026-09-19-python-sdk-directional-client proposes deleting next_request, respond, respond_error, notify, and IncomingRequest, because no runtime producer exists. That is accurate today. But the missing producer is the gap this thread asks to close, not evidence that the direction is unwanted. Could the note be held, or narrowed to keep the request-responder half, until this discussion is decided? Otherwise Python embedders face a public-API removal followed by a re-addition for approvals. The proposed guard against frames that carry both id and method seems right either way.

2. Auto review makes the approval half more pressing.

The experimental Auto review lets the model allow low-risk calls, but a denied call still asks the user. Even the automated path therefore ends at a human approval. In an SDK-embedded runtime that human sits across the wire, so the fallback fails closed, as in @qiankunli's no approval channel is available repro above.

3. The timed-question design suggests a smaller first step for questions.

2026-09-19-timed-user-question-two-settlements is still proposed. Its implementation merged on 09-24 and was reverted the same day. In that design, a timed ask_user_question returns pending after its timeout, and a later answer goes through UserQuestionService.answer(agent, callId, answer), which steers a durable user message. If it lands, an embedder already sees the question: the tool/call arrives on session.event. The only missing piece would be a client→server method that forwards to answer(). That needs no server→client request and no provider-slot negotiation.

That route does not work for approvals. As @denial123789 noted, an approval outcome carries one-shot effect authority and cannot arrive as a late user message.

Suggested phasing:

1. Keep the reverse-direction plumbing in both clients until this is decided.
2. Approvals: a negotiated server→client request mapping ApprovalRequest → ApprovalOutcome. It settles exactly once, fails closed on EOF, abort, or deadline, and ignores late responses.
3. Questions: the same mechanism, or, if timed questions land, a client→server answer method over the late-answer path.

We embed the SDK runtime (one runtime per session) and can test a branch against our host.