feat(sdk): TypeScript SDK client + shared wire protocol + SDK subagent backend

- @deepseek-ai/dsh-sdk-protocol: extract the line transport from dsh-jsonrpc and name the request/result/notification wire types both ends share; error responses preserve wire code/data via JsonRpcResponseError. - @deepseek-ai/dsh-sdk-client: TypeScript twin of the Python SDK — spawns the dsh-jsonrpc-agent runtime as a subprocess, drives stdio JSON-RPC turns (DeepSeekHarness high-level API + HarnessClient protocol client), scopes notifications to session trees client-side, and reaps the child through the shared subprocess dispose ladder. - @deepseek-ai/dsh-subagent-sdk: out-of-process subagent backend driving a child harness runtime through the TS SDK; shares cwd resolution with subagent-acp via new dsh-subagent-subprocess cwd helpers. - Keyless unit suites drive real subprocesses (scripted fake runtime peer); 100% per-file coverage on all touched packages.
2026-07-27 03:21:06 +08:00
parent 46e70be34a
commit 4ad37344a8
33 changed files with 2738 additions and 122 deletions
--- a/packages/sdk/sdk-protocol/src/index.ts
+++ b/packages/sdk/sdk-protocol/src/index.ts
@@ -0,0 +1,12 @@
+/**
+ * Shared wire protocol for the DeepSeek Harness SDK runtime: the
+ * newline-delimited JSON-RPC stdio transport plus the named request, result,
+ * and notification types both wire ends speak. The runtime server plugin
+ * (`@deepseek-ai/dsh-jsonrpc`) serves this protocol; SDK clients
+ * (`@deepseek-ai/dsh-sdk-client`, the Python SDK) drive it.
+ *
+ * @module @deepseek-ai/dsh-sdk-protocol
+ */
+
+export * from './transport.ts'
+export * from './types.ts'
--- a/packages/sdk/sdk-protocol/src/invariant.ts
+++ b/packages/sdk/sdk-protocol/src/invariant.ts
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-sdk-protocol`.
+ * @module @deepseek-ai/dsh-sdk-protocol/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-sdk-protocol'
+
+/** Cordis companion plugin name. */
+export const name = 'sdk-protocol-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: a pure wire library (transport class + type
+ * declarations) with no event stream or mutable data relation of its own;
+ * both wire ends own their protocol behavior.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
--- a/packages/sdk/sdk-protocol/src/transport.ts
+++ b/packages/sdk/sdk-protocol/src/transport.ts
@@ -0,0 +1,242 @@
+/**
+ * Newline-delimited JSON-RPC 2.0 over byte streams. Frames with `id` and
+ * `method` are requests, `id` alone is a response, and `method` alone is a
+ * notification. Malformed lines are ignored; handler failures become error frames.
+ *
+ * @module @deepseek-ai/dsh-sdk-protocol/transport
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { Readable, Writable } from 'node:stream'
+import { StringDecoder } from 'node:string_decoder'
+
+type JsonRpcId = string | number
+type RequestHandler = (method: string, params: Record<string, unknown>) => Promise<unknown>
+type NotificationHandler = (method: string, params: Record<string, unknown>) => void
+
+/** A JSON-RPC error response, preserving the wire `code` and optional `data`. */
+export class JsonRpcResponseError extends Error {
+  /**
+   * @param code - the wire error code, or `undefined` when the peer sent none.
+   * @param message - the wire error message.
+   * @param data - the optional structured error payload, verbatim.
+   */
+  constructor(readonly code: number | undefined, message: string, readonly data?: unknown) {
+    super(message)
+    this.name = 'JsonRpcResponseError'
+  }
+}
+
+/**
+ * Outbound request and notification surface used by the runtime server and
+ * SDK clients.
+ */
+export interface JsonRpcTransportPeer {
+  /**
+   * Send a request and await its response.
+   * @param method - the JSON-RPC method name.
+   * @param params - the request parameters object.
+   * @returns the result; rejects with {@link JsonRpcResponseError} on an error
+   * response, and with a plain `Error` on a write failure or closure.
+   */
+  request(method: string, params: object): Promise<unknown>
+  /**
+   * Send a notification; omitted params produce no `params` member.
+   * @param method - the JSON-RPC method name.
+   * @param params - the optional notification parameters object.
+   */
+  notify(method: string, params?: object): void
+}
+
+interface PendingRequest {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+}
+
+/**
+ * Line-delimited endpoint over caller-owned streams. {@link start} attaches
+ * listeners; {@link close} detaches them and rejects pending requests without
+ * destroying the streams. Missing request handlers return `-32601`; handler
+ * failures return `-32603`. Notifications without a handler are dropped.
+ */
+export class JsonRpcLineTransport implements JsonRpcTransportPeer {
+  private buffer = ''
+  private readonly decoder = new StringDecoder('utf8')
+  private started = false
+  private requestHandler: RequestHandler | undefined
+  private notificationHandler: NotificationHandler | undefined
+  private readonly pending = new Map<JsonRpcId, PendingRequest>()
+
+  constructor(
+    private readonly input: Readable,
+    private readonly output: Writable,
+  ) {}
+
+  /** Attach the input listeners and begin reading frames. Idempotent. */
+  start(): void {
+    if (this.started) return
+    this.started = true
+    this.input.on('data', this.onData)
+    this.input.on('error', this.onInputError)
+    this.input.on('end', this.onInputEnd)
+  }
+
+  /**
+   * Detach listeners and reject pending requests. Safe before {@link start}.
+   */
+  close(): void {
+    this.input.off('data', this.onData)
+    this.input.off('error', this.onInputError)
+    this.input.off('end', this.onInputEnd)
+    this.failPending(new Error('JSON-RPC transport closed'))
+  }
+
+  /**
+   * Install the request handler, replacing any prior handler.
+   * @param handler - resolves to the response `result`; a rejection becomes a
+   * `-32603` error response carrying the message.
+   */
+  onRequest(handler: RequestHandler): void {
+    this.requestHandler = handler
+  }
+
+  /**
+   * Install the notification handler, replacing any prior handler.
+   * @param handler - invoked per notification with the method and normalized
+   * params object.
+   */
+  onNotification(handler: NotificationHandler): void {
+    this.notificationHandler = handler
+  }
+
+  request(method: string, params: object): Promise<unknown> {
+    const id = `req_${randomUUID().replaceAll('-', '')}`
+    const message = { jsonrpc: '2.0', id, method, params }
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      try {
+        this.write(message)
+      } catch (error) {
+        this.pending.delete(id)
+        reject(error instanceof Error ? error : new Error(String(error)))
+      }
+    })
+  }
+
+  notify(method: string, params?: object): void {
+    this.write(params === undefined ? { jsonrpc: '2.0', method } : { jsonrpc: '2.0', method, params })
+  }
+
+  /**
+   * Wait for prior frame write callbacks. The empty barrier emits no bytes.
+   * @returns a promise that settles with the output write callback.
+   */
+  flush(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.output.write('', (error) => {
+        if (error) reject(error)
+        else resolve()
+      })
+    })
+  }
+
+  private readonly onData = (chunk: Buffer | string): void => {
+    this.buffer += typeof chunk === 'string' ? chunk : this.decoder.write(chunk)
+    this.drainLines()
+  }
+
+  private drainLines(): void {
+    for (;;) {
+      const newline = this.buffer.indexOf('\n')
+      if (newline < 0) break
+      const line = this.buffer.slice(0, newline).trim()
+      this.buffer = this.buffer.slice(newline + 1)
+      if (!line) continue
+      void this.handleLine(line)
+    }
+  }
+
+  private readonly onInputError = (error: Error): void => {
+    this.failPending(error)
+  }
+
+  private readonly onInputEnd = (): void => {
+    this.buffer += this.decoder.end()
+    this.drainLines()
+    this.failPending(new Error('JSON-RPC input closed'))
+  }
+
+  private async handleLine(line: string): Promise<void> {
+    let message: unknown
+    try {
+      message = JSON.parse(line)
+    } catch {
+      // Only JSON syntax errors reach this catch; malformed peer lines are ignored.
+      return
+    }
+    if (!message || typeof message !== 'object') return
+    const frame = message as Record<string, unknown>
+    const id = frame.id
+    const method = frame.method
+    if ((typeof id === 'string' || typeof id === 'number') && typeof method === 'string') {
+      await this.handleIncomingRequest(id, method, objectParams(frame.params))
+      return
+    }
+    if (typeof id === 'string' || typeof id === 'number') {
+      this.handleIncomingResponse(id, frame)
+      return
+    }
+    if (typeof method === 'string') {
+      this.notificationHandler?.(method, objectParams(frame.params))
+    }
+  }
+
+  private async handleIncomingRequest(id: JsonRpcId, method: string, params: Record<string, unknown>): Promise<void> {
+    const handler = this.requestHandler
+    if (!handler) {
+      this.writeError(id, -32601, `method not found: ${method}`)
+      return
+    }
+    try {
+      const result = await handler(method, params)
+      this.write({ jsonrpc: '2.0', id, result })
+    } catch (error) {
+      this.writeError(id, -32603, error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  private handleIncomingResponse(id: JsonRpcId, frame: Record<string, unknown>): void {
+    const pending = this.pending.get(id)
+    if (!pending) return
+    this.pending.delete(id)
+    if (frame.error && typeof frame.error === 'object') {
+      const error = frame.error as Record<string, unknown>
+      pending.reject(new JsonRpcResponseError(
+        typeof error.code === 'number' ? error.code : undefined,
+        typeof error.message === 'string' ? error.message : 'JSON-RPC error',
+        error.data,
+      ))
+      return
+    }
+    pending.resolve(frame.result)
+  }
+
+  private writeError(id: JsonRpcId, code: number, message: string): void {
+    this.write({ jsonrpc: '2.0', id, error: { code, message } })
+  }
+
+  private write(message: Record<string, unknown>): void {
+    this.output.write(`${JSON.stringify(message)}\n`)
+  }
+
+  private failPending(error: Error): void {
+    const pending = [...this.pending.values()]
+    this.pending.clear()
+    for (const waiter of pending) waiter.reject(error)
+  }
+}
+
+/** Normalize JSON-RPC `params` to a plain object (arrays and scalars collapse to `{}`). */
+function objectParams(params: unknown): Record<string, unknown> {
+  return params && typeof params === 'object' && !Array.isArray(params) ? params as Record<string, unknown> : {}
+}
--- a/packages/sdk/sdk-protocol/src/types.ts
+++ b/packages/sdk/sdk-protocol/src/types.ts
@@ -0,0 +1,105 @@
+/**
+ * Named wire types for the DeepSeek Harness SDK runtime protocol: the three
+ * request/result pairs and the four server-to-client notification payloads
+ * exchanged over the newline-delimited JSON-RPC stdio transport. The server
+ * plugin (`@deepseek-ai/dsh-jsonrpc`) and SDK clients share these shapes;
+ * `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`.
+ *
+ * @module @deepseek-ai/dsh-sdk-protocol/types
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SubagentStopReason } from '@deepseek-ai/dsh-subagent'
+
+/** Parameters for the process-wide SDK handshake. */
+export interface InitializeParams {
+  /** Working directory recorded on every SDK-created session's header. */
+  cwd: string
+  /** Provider route every SDK-created agent runs on. */
+  provider: string
+  /** Model name every SDK-created agent runs on (the server may mount a fallback adapter; see `HarnessSdkServer.initialize`). */
+  model: string
+}
+
+/** Wire-stable server identity returned by initialization. */
+export interface InitializeResult {
+  /** Wire-stable server identity (`deepseek-harness-sdk-runtime`) and version. */
+  serverInfo: { name: string; version: string }
+}
+
+/** One user turn on one SDK session. */
+export interface SessionPromptParams {
+  /** The SDK-side session id; an unknown id lazily creates the agent+session pair. */
+  sessionId: string
+  /** The prompt content blocks, sent verbatim as the user message. */
+  contentBlocks: ContentBlock[]
+}
+
+/** Prompt acceptance after turn settlement; outcome rides on `session.finished`. */
+export interface SessionPromptResult {
+  /** Always `true`; the turn outcome is the paired `session.finished` notification. */
+  accepted: true
+}
+
+/** Deployment-mapped SDK outcome: `ok` for an accepted result, `error` otherwise. */
+export type SdkRunStatus = 'ok' | 'error'
+
+/** `session.event` payload: one session-log event, streamed as it is recorded. */
+export interface SessionEventNotification {
+  /** Session the event belongs to (every session in the runtime, not only SDK-created ones). */
+  sessionId: string
+  /** The full session-log event envelope. */
+  event: SessionEvent
+}
+
+/** `session.finished` payload: one per accepted prompt, after turn settlement. */
+export interface SessionFinishedNotification {
+  /** The settled session. */
+  sessionId: string
+  /** Deployment-mapped turn outcome (see `maxTokensAsSuccess` on the server). */
+  status: SdkRunStatus
+  /** Why the last message-triggered turn ended; absent when no turn ran. */
+  reason: TurnEndReason | undefined
+}
+
+/** `subagent.started` payload: an in-runtime child session was created. */
+export interface SubagentStartedNotification {
+  /** The delegating session. */
+  parentSessionId: string
+  /** The new child session. */
+  childSessionId: string
+}
+
+/** `subagent.finished` payload: an in-process subagent run ended (remote runs are not reported). */
+export interface SubagentFinishedNotification {
+  /** Subagent provider name that ran the child. */
+  provider: string
+  /** The child agent's id (equals {@link childSessionId} for local runs). */
+  agentId: string
+  /** The delegating session. */
+  parentSessionId: string
+  /** The child session. */
+  childSessionId: string
+  /** Deployment-mapped run outcome. */
+  status: SdkRunStatus
+  /** The provider-reported stop reason. */
+  stopReason: SubagentStopReason
+  /** The child's final assistant message, when it produced one. */
+  lastAssistantMessage?: ContentBlock[]
+}
+
+/** Server-to-client notifications by JSON-RPC method name. */
+export interface HarnessSdkNotificationMap {
+  'session.event': SessionEventNotification
+  'session.finished': SessionFinishedNotification
+  'subagent.started': SubagentStartedNotification
+  'subagent.finished': SubagentFinishedNotification
+}
+
+/** Client-to-server request methods with their param and result shapes. */
+export interface HarnessSdkRequestMap {
+  'initialize': { params: InitializeParams; result: InitializeResult }
+  'session/prompt': { params: SessionPromptParams; result: SessionPromptResult }
+  'shutdown': { params: undefined; result: Record<string, never> }
+}