refactor(sdk): remove unreleased project toolchain

packages/sdk/client/src/api.ts

@@ -0,0 +1,246 @@
+/**
+ * High-level run API over {@link HarnessClient}: `DeepSeekHarness` owns one
+ * runtime subprocess across many sessions; `HarnessSession.run` sends a
+ * prompt and settles when the whole agent next becomes idle.
+ * Mirrors the Python SDK's `DeepSeekHarness`/`Session` pair.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/api
+ */
+
+import { randomUUID } from 'node:crypto'
+import { resolve } from 'node:path'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { HarnessClient, isRecord, SdkProtocolError } from './client.ts'
+import type { ContentBlock, DeepSeekHarnessOptions, HarnessClientOptions, HarnessNotification, RunResult } from './types.ts'
+
+/**
+ * Reusable SDK for running DeepSeek Harness agent turns in a runtime
+ * subprocess. The subprocess starts lazily on first use and stays owned by
+ * this instance until {@link close}; always close (or `await using`) so the
+ * child is reaped.
+ */
+export class DeepSeekHarness implements AsyncDisposable {
+  private clientInstance: HarnessClient
+  private readonly launch: HarnessClientOptions
+  private readonly cwd: string
+  private readonly provider: string
+  private readonly model: string
+  private readonly maxTokens: number | undefined
+  private initialized: Promise<void> | undefined
+  private closed = false
+
+  /** @param options - runtime launch spec plus the session route (cwd/provider/model). */
+  constructor(options: DeepSeekHarnessOptions) {
+    this.launch = options.launch
+    this.clientInstance = new HarnessClient(options.launch)
+    // Absolute before the handshake: the child spawns relative to THIS
+    // process's cwd, but the wire cwd is resolved again inside the child — a
+    // relative value would double-resolve (e.g. `worker` → `worker/worker`).
+    this.cwd = resolve(options.cwd ?? options.launch.cwd ?? process.cwd())
+    this.provider = options.provider ?? 'deepseek-official'
+    this.model = options.model ?? 'deepseek-v4-flash'
+    this.maxTokens = options.maxTokens
+  }
+
+  /**
+   * The underlying JSON-RPC client (exposed for low-level access). A failed
+   * handshake reaps its runtime and swaps in a fresh instance, so do not
+   * cache this across a failed {@link start}.
+   * @returns the client currently owning the runtime subprocess.
+   */
+  get client(): HarnessClient {
+    return this.clientInstance
+  }
+
+  /**
+   * Start the subprocess and perform the `initialize` handshake once. On
+   * failure the runtime is reaped and a fresh client replaces it
+   * (`HarnessClient.close` is permanent), so a later call retries with a new
+   * subprocess — unless {@link close} already ended this harness.
+   * @returns settlement of the (memoized) handshake.
+   */
+  start(): Promise<void> {
+    this.initialized ??= (async () => {
+      try {
+        this.clientInstance.start()
+        await this.clientInstance.initialize({
+          cwd: this.cwd,
+          provider: this.provider,
+          model: this.model,
+          ...this.maxTokens === undefined ? {} : { maxTokens: this.maxTokens },
+        })
+      } catch (error) {
+        this.initialized = undefined
+        await this.clientInstance.close()
+        if (!this.closed) this.clientInstance = new HarnessClient(this.launch)
+        throw error
+      }
+    })()
+    return this.initialized
+  }
+
+  /**
+   * Open a session handle (no wire traffic; the runtime creates the session
+   * on its first prompt).
+   * @param sessionId - explicit id to reuse; omitted mints a fresh one.
+   * @returns the session handle.
+   */
+  session(sessionId?: string): HarnessSession {
+    return new HarnessSession(this, sessionId ?? `session-${randomUUID().replaceAll('-', '')}`)
+  }
+
+  /**
+   * Run one prompt on a fresh (or named) session.
+   * @param input - prompt text, or content blocks sent verbatim.
+   * @param options - optional session id and per-notification observer.
+   * @returns the owned activity interval.
+   */
+  run(input: string | ContentBlock[], options?: RunOptions): Promise<RunResult> {
+    return this.session(options?.sessionId).run(input, options)
+  }
+
+  /**
+   * Shut down and reap the runtime subprocess. Idempotent and terminal —
+   * a closed harness no longer retries a failed handshake.
+   * @returns settlement of the complete teardown.
+   */
+  close(): Promise<void> {
+    this.closed = true
+    return this.clientInstance.close()
+  }
+
+  /**
+   * `await using` support: {@link close}.
+   * @returns settlement of the teardown.
+   */
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close()
+  }
+}
+
+/** Per-run options: target session and streaming observer. */
+export interface RunOptions {
+  /** Session id to run on; omitted mints a fresh session per call. */
+  sessionId?: string
+  /** Observer invoked with every notification for this session tree, in wire order. */
+  onNotification?: (notification: HarnessNotification) => void
+}
+
+/**
+ * One SDK session: a stable id plus owned activity intervals.
+ */
+export class HarnessSession {
+  /**
+   * @param harness - the owning harness (supplies the client and handshake).
+   * @param id - the wire session id this handle runs on.
+   */
+  constructor(readonly harness: DeepSeekHarness, readonly id: string) {}
+
+  /**
+   * Queue one prompt, then observe the whole session through its next idle.
+   * @param input - prompt text, or content blocks sent verbatim.
+   * @param options - optional per-notification observer.
+   * @returns the owned activity interval; rejects on transport loss, timeout,
+   * or a protocol error.
+   */
+  async run(input: string | ContentBlock[], options?: Pick<RunOptions, 'onNotification'>): Promise<RunResult> {
+    await this.harness.start()
+    const client = this.harness.client
+    const contentBlocks = normalizeInput(input)
+    const events: SessionEvent[] = []
+    const notifications: HarnessNotification[] = []
+
+    const subscription = client.subscribeSessionTree(this.id)
+    const collect = (notification: HarnessNotification): void => {
+      if (notification.method === 'session.event' && notification.params.sessionId === this.id) {
+        // Wire boundary: the envelope feeds the typed RunResult, so a
+        // malformed runtime surfaces as a protocol error, not as type-invalid
+        // data (or a TypeError out of finalResponse).
+        const event = validatedSessionEvent(notification.params.event)
+        notifications.push(notification)
+        options?.onNotification?.(notification)
+        events.push(event)
+        return
+      }
+      notifications.push(notification)
+      options?.onNotification?.(notification)
+    }
+    try {
+      const messageId = await client.prompt(this.id, contentBlocks)
+      let received = false
+      while (true) {
+        const notification = await subscription.next()
+        if (!received) {
+          if (notification.method !== 'session.event'
+            || notification.params.sessionId !== this.id
+            || !isInboxReceipt(notification.params.event, messageId)) continue
+          received = true
+        }
+        collect(notification)
+        if (notification.method === 'session.status'
+          && notification.params.sessionId === this.id
+          && notification.params.status === 'idle') break
+      }
+    } finally {
+      subscription.close()
+    }
+
+    return {
+      sessionId: this.id,
+      finalResponse: finalResponse(events),
+      events,
+      notifications,
+    }
+  }
+}
+
+/**
+ * Normalize run input: a string becomes one text block; blocks pass verbatim.
+ * @param input - prompt text or content blocks.
+ * @returns the content blocks to send.
+ */
+export function normalizeInput(input: string | ContentBlock[]): ContentBlock[] {
+  return typeof input === 'string' ? [{ type: 'text', text: input }] : input
+}
+
+/** Validate the fields in a wire `session.event` envelope before returning the typed result. */
+function validatedSessionEvent(value: unknown): SessionEvent {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    throw new SdkProtocolError(`session.event carried no event envelope: ${JSON.stringify(value)}`)
+  }
+  // The one variant this module reads into (finalResponse) must carry
+  // kind-tagged content blocks; other variants pass through under their
+  // envelope shape.
+  if (value.type === 'assistant/message') {
+    const message = isRecord(value.data) ? value.data.message : undefined
+    const content = isRecord(message) ? message.content : undefined
+    if (!Array.isArray(content) || !content.every(block => isRecord(block) && typeof block.type === 'string')) {
+      throw new SdkProtocolError(`assistant/message event carried malformed content: ${JSON.stringify(value)}`)
+    }
+  }
+  return value as unknown as SessionEvent
+}
+
+/** Whether a raw session event is the durable enqueue receipt for `messageId`. */
+function isInboxReceipt(value: unknown, messageId: string): boolean {
+  if (!isRecord(value) || value.type !== 'agent/inbox/spliced' || !isRecord(value.data)) return false
+  const inserted = value.data.inserted
+  return Array.isArray(inserted) && inserted.some(message => isRecord(message) && message.id === messageId)
+}
+
+/**
+ * Extract the concatenated text of the last assistant message.
+ * @param events - the activity interval's `session.event` payloads in wire order.
+ * @returns the final response text, or `''` when no assistant message exists.
+ */
+export function finalResponse(events: SessionEvent[]): string {
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index]
+    if (event?.type !== 'assistant/message') continue
+    return event.data.message.content
+      .filter((block): block is ContentBlock & { type: 'text' } => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+  }
+  return ''
+}

packages/sdk/client/src/client.ts

@@ -0,0 +1,473 @@
+/**
+ * Low-level JSON-RPC client for a DeepSeek Harness SDK runtime subprocess.
+ * {@link HarnessClient} owns the child process: it spawns the runtime, speaks
+ * the `@deepseek-ai/dsh-sdk-protocol` wire over the child's stdio, fans
+ * server notifications out to subscriptions, and tears the child down to
+ * quiescence through a private EOF → SIGTERM → SIGKILL ladder. The design
+ * twin is the Python SDK's `HarnessClient` (`python/sdk`); both drive the
+ * same runtime protocol. This client runs OUTSIDE any harness context, so it
+ * spawns directly rather than through the `dsh-subprocess` service — the
+ * seam's documented exception for SDK-managed transports.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/client
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process'
+import {
+  JsonRpcLineTransport,
+  JsonRpcResponseError,
+  type InitializeParams,
+  type InitializeResult,
+  type SessionPromptParams,
+} from '@deepseek-ai/dsh-sdk-protocol'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { disposeRuntimeProcess } from './dispose.ts'
+import type { HarnessClientOptions, HarnessNotification, NotificationFilter } from './types.ts'
+
+/** Retained stderr lines used to diagnose an unexpected runtime death. */
+const STDERR_TAIL_LIMIT = 400
+
+/** Grace for the runtime's stdio streams to settle after its exit edge. */
+const STREAM_SETTLE_MS = 100
+
+/**
+ * The runtime subprocess is gone or unusable: it exited, its stdio closed, or
+ * it was never launchable. The message carries the exit code and a stderr
+ * tail when available.
+ */
+export class TransportClosedError extends Error {
+  /** @param message - the failure description, including any stderr tail. */
+  constructor(message: string) {
+    super(message)
+    this.name = 'TransportClosedError'
+  }
+}
+
+/** A request exceeded {@link HarnessClientOptions.requestTimeoutMs}. */
+export class RequestTimeoutError extends Error {
+  /** @param message - which method timed out. */
+  constructor(message: string) {
+    super(message)
+    this.name = 'RequestTimeoutError'
+  }
+}
+
+/**
+ * The runtime answered outside its documented protocol (for example a
+ * `session/prompt` response without `accepted: true`).
+ */
+export class SdkProtocolError extends Error {
+  /** @param message - the protocol violation description. */
+  constructor(message: string) {
+    super(message)
+    this.name = 'SdkProtocolError'
+  }
+}
+
+interface SubscriptionState {
+  readonly queue: HarnessNotification[]
+  readonly waiters: { resolve: (item: HarnessNotification) => void; reject: (error: Error) => void }[]
+  readonly filter: NotificationFilter | undefined
+  failure: Error | undefined
+}
+
+/** One client-side notification stream returned by {@link HarnessClient.subscribe}. */
+export interface NotificationSubscription extends AsyncIterable<HarnessNotification> {
+  /**
+   * Await the next matching notification.
+   * @returns the notification; after the runtime died, drains what was
+   * already delivered and then rejects; after {@link close}, rejects
+   * immediately (the queue is dropped).
+   */
+  next(): Promise<HarnessNotification>
+
+  /**
+   * Drain one already-delivered notification without waiting.
+   * @returns the next queued notification, or `undefined` when none is queued.
+   */
+  tryNext(): HarnessNotification | undefined
+
+  /** Detach from the client; queued items drop and pending waiters reject. */
+  close(): void
+}
+
+/** Internal producer side of a public notification subscription. */
+class NotificationSubscriptionImpl implements NotificationSubscription {
+  constructor(
+    private readonly state: SubscriptionState,
+    private readonly unsubscribe: () => void,
+  ) {}
+
+  /**
+   * Await the next matching notification.
+   * @returns the notification; after the runtime died, drains what was
+   * already delivered and then rejects; after {@link close}, rejects
+   * immediately (the queue is dropped).
+   */
+  next(): Promise<HarnessNotification> {
+    const queued = this.state.queue.shift()
+    if (queued !== undefined) return Promise.resolve(queued)
+    if (this.state.failure !== undefined) return Promise.reject(this.state.failure)
+    return new Promise((resolve, reject) => {
+      this.state.waiters.push({ resolve, reject })
+    })
+  }
+
+  /**
+   * Drain one already-delivered notification without waiting.
+   * @returns the next queued notification, or `undefined` when none is queued.
+   */
+  tryNext(): HarnessNotification | undefined {
+    return this.state.queue.shift()
+  }
+
+  /** Detach from the client; queued items drop and pending waiters reject. */
+  close(): void {
+    this.unsubscribe()
+    // The drop is part of this method's contract; a runtime-death fail() keeps
+    // the queue so already-delivered notifications remain drainable.
+    this.state.queue.length = 0
+    this.fail(new TransportClosedError('notification subscription closed'))
+  }
+
+  /**
+   * Reject pending and future waits (delivery stops; the first failure wins).
+   * Already-queued notifications remain drainable via {@link next}/{@link tryNext}.
+   * @param error - the terminal failure delivered to waiters.
+   */
+  fail(error: Error): void {
+    this.state.failure ??= error
+    for (const waiter of this.state.waiters.splice(0)) waiter.reject(this.state.failure)
+  }
+
+  /**
+   * Deliver one notification to a waiter or the queue when the filter
+   * matches. A throwing filter fails only THIS subscription (detached, the
+   * throw becomes its terminal error) — it never disturbs sibling
+   * subscriptions or the transport's read loop, mirroring the Python client.
+   * @param notification - the wire notification to deliver.
+   */
+  push(notification: HarnessNotification): void {
+    let matches: boolean
+    try {
+      matches = this.state.filter === undefined || this.state.filter(notification)
+    } catch (error) {
+      this.unsubscribe()
+      this.fail(error instanceof Error ? error : new Error(String(error)))
+      return
+    }
+    if (!matches) return
+    const waiter = this.state.waiters.shift()
+    if (waiter !== undefined) waiter.resolve(notification)
+    else this.state.queue.push(notification)
+  }
+
+  /**
+   * Iterate notifications until the subscription or runtime closes (the
+   * terminating rejection propagates).
+   * @returns an async iterator over {@link next} results.
+   */
+  async * [Symbol.asyncIterator](): AsyncIterator<HarnessNotification> {
+    for (;;) yield await this.next()
+  }
+}
+
+/**
+ * JSON-RPC client for the DeepSeek Harness SDK runtime over subprocess stdio.
+ *
+ * The subprocess starts lazily on {@link start} and is owned by this instance
+ * until {@link close}, which requests protocol `shutdown` and then walks the
+ * shared EOF → SIGTERM → SIGKILL dispose ladder to quiescence. There is no
+ * wire-level cancel: a timed-out request stays running server-side until the
+ * runtime is closed.
+ */
+export class HarnessClient {
+  private child: ChildProcess | undefined
+  private transport: JsonRpcLineTransport | undefined
+  private readonly stderrTail: string[] = []
+  private readonly subscriptions = new Map<string, NotificationSubscriptionImpl>()
+  private readonly sessionParents = new Map<string, string>()
+  private subscriptionSerial = 0
+  private exitCode: number | null | undefined
+  private spawnError: Error | undefined
+  private streamsSettled: Promise<void> = Promise.resolve()
+  private closeTask: Promise<void> | undefined
+
+  /** @param options - launch spec, complete child environment, and timeouts. */
+  constructor(readonly options: HarnessClientOptions) {}
+
+  /**
+   * Spawn the runtime subprocess and start reading frames. Idempotent while
+   * the process is live; rejects reuse after {@link close}.
+   */
+  start(): void {
+    if (this.closeTask !== undefined) throw new TransportClosedError('DeepSeek Harness runtime client is closed')
+    if (this.child !== undefined) return
+    const child = spawn(this.options.command, this.options.args ?? [], {
+      cwd: this.options.cwd,
+      env: this.options.env ?? process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    this.child = child
+    child.once('error', (error) => {
+      this.spawnError = error
+      // A spawn failure destroys the pipes without an input 'end' edge, so the
+      // transport's pending requests must be failed here.
+      this.transport?.close()
+      this.failSubscriptions(this.closedError('DeepSeek Harness runtime failed to start'))
+    })
+    // Writes racing the runtime's death EPIPE on stdin; the exit edge below is
+    // the real signal, so the stream-level error only needs to be non-fatal.
+    // The timing of that race is not deterministically reproducible.
+    /* v8 ignore next */
+    child.stdin.on('error', () => {})
+    let stderrBuffer = ''
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk: string) => {
+      stderrBuffer += chunk
+      const newline = stderrBuffer.lastIndexOf('\n')
+      if (newline >= 0) {
+        this.appendStderr(stderrBuffer.slice(0, newline).split('\n'))
+        stderrBuffer = stderrBuffer.slice(newline + 1)
+      }
+    })
+    let signalStreamsSettled!: () => void
+    this.streamsSettled = new Promise((resolve) => { signalStreamsSettled = resolve })
+    const settled = { stderr: false, exited: false }
+    const maybeSettle = (): void => {
+      if (settled.stderr && settled.exited) signalStreamsSettled()
+    }
+    child.stderr.once('close', () => {
+      if (stderrBuffer.length > 0) this.appendStderr([stderrBuffer])
+      settled.stderr = true
+      maybeSettle()
+    })
+    child.once('exit', (code) => {
+      this.exitCode = code
+      settled.exited = true
+      maybeSettle()
+      this.failSubscriptions(this.closedError('DeepSeek Harness runtime exited'))
+    })
+    child.once('close', () => {
+      // All stdio has settled: stdout 'end' already drained every tail frame,
+      // so closing now cannot drop responses — it only fails requests that
+      // will never be answered.
+      this.transport?.close()
+    })
+    const transport = new JsonRpcLineTransport(child.stdout, child.stdin)
+    transport.onNotification((method, params) => { this.dispatchNotification({ method, params }) })
+    transport.start()
+    this.transport = transport
+  }
+
+  /**
+   * Perform the process-wide handshake.
+   * @param params - workspace cwd plus the provider/model route.
+   * @returns the runtime's wire identity.
+   */
+  async initialize(params: InitializeParams): Promise<InitializeResult> {
+    const result = await this.request('initialize', { ...params })
+    if (!isRecord(result) || !isRecord(result.serverInfo)
+      || typeof result.serverInfo.name !== 'string' || typeof result.serverInfo.version !== 'string') {
+      throw new SdkProtocolError(`initialize returned no server identity: ${JSON.stringify(result)}`)
+    }
+    return { serverInfo: { name: result.serverInfo.name, version: result.serverInfo.version } }
+  }
+
+  /**
+   * Queue one prompt and return its durable inbox identity.
+   * @param sessionId - target session; an unknown id creates it.
+   * @param contentBlocks - the user message, sent verbatim.
+   * @returns the queued message id.
+   */
+  async prompt(sessionId: string, contentBlocks: ContentBlock[]): Promise<string> {
+    const params: SessionPromptParams = { sessionId, contentBlocks }
+    const result = await this.request('session/prompt', { ...params })
+    if (!isRecord(result) || typeof result.messageId !== 'string') {
+      throw new SdkProtocolError(`session/prompt returned no message id: ${JSON.stringify(result)}`)
+    }
+    return result.messageId
+  }
+
+  /**
+   * Send one JSON-RPC request and await its result.
+   * @param method - the wire method name.
+   * @param params - the params object; omitted params send `{}`.
+   * @param timeoutMs - per-call override of {@link HarnessClientOptions.requestTimeoutMs}.
+   * @returns the raw result; rejects with {@link JsonRpcResponseError} on a
+   * protocol error response, {@link RequestTimeoutError} on timeout, and
+   * {@link TransportClosedError} when the runtime is gone.
+   */
+  async request(method: string, params?: object, timeoutMs?: number): Promise<unknown> {
+    this.start()
+    // A dead runtime cannot answer; fail with process context instead of
+    // writing into a destroyed pipe and hanging until the timeout.
+    if (this.exitCode !== undefined || this.spawnError !== undefined) {
+      await this.settleStreams()
+      throw this.closedError('DeepSeek Harness runtime is not running')
+    }
+    const transport = this.transport
+    /* v8 ignore next -- start() either sets the transport or throws */
+    if (transport === undefined) throw new TransportClosedError('DeepSeek Harness runtime is not running')
+    const timeout = timeoutMs ?? this.options.requestTimeoutMs
+    try {
+      if (timeout === undefined) return await transport.request(method, params ?? {})
+      // The abort signal makes the timeout an abandonment: the transport drops
+      // its pending entry, so repeated bounded requests against a hung method
+      // retain no per-call state (the server-side work still runs to close).
+      const abandon = new AbortController()
+      const timer = setTimeout(() => {
+        abandon.abort(new RequestTimeoutError(`${method} timed out after ${timeout}ms waiting for the DeepSeek Harness runtime`))
+      }, timeout)
+      try {
+        return await transport.request(method, params ?? {}, abandon.signal)
+      } finally {
+        clearTimeout(timer)
+      }
+    } catch (error) {
+      if (error instanceof JsonRpcResponseError || error instanceof RequestTimeoutError) throw error
+      // Transport-level failures gain process context: exit code + stderr tail.
+      await this.settleStreams()
+      throw this.closedError(errorMessage(error))
+    }
+  }
+
+  /**
+   * Subscribe to server notifications.
+   * @param filter - optional predicate; omitted means every notification.
+   * @returns the subscription handle; close it to stop delivery. After
+   * {@link close} or runtime death the handle is born failed — there is no
+   * producer left, so `next()` rejects instead of waiting forever.
+   */
+  subscribe(filter?: NotificationFilter): NotificationSubscription {
+    const id = String(this.subscriptionSerial++)
+    const state: SubscriptionState = { queue: [], waiters: [], filter, failure: undefined }
+    const subscription = new NotificationSubscriptionImpl(state, () => { this.subscriptions.delete(id) })
+    if (this.closeTask !== undefined || this.exitCode !== undefined || this.spawnError !== undefined) {
+      subscription.fail(this.closedError('DeepSeek Harness runtime closed'))
+      return subscription
+    }
+    this.subscriptions.set(id, subscription)
+    return subscription
+  }
+
+  /**
+   * Subscribe to one session and the descendants discovered from
+   * `subagent.started` lineage edges (the runtime notifies for every session
+   * in its context; scoping is client-side, mirroring the Python SDK).
+   * @param sessionId - the root session id.
+   * @returns the filtered subscription handle.
+   */
+  subscribeSessionTree(sessionId: string): NotificationSubscription {
+    return this.subscribe((notification) => {
+      const params = notification.params
+      if (notification.method === 'subagent.started' || notification.method === 'subagent.finished') {
+        const parentId = params.parentSessionId
+        if (typeof parentId === 'string' && this.isDescendantOf(parentId, sessionId)) return true
+        return params.childSessionId === sessionId
+      }
+      const relatedId = params.sessionId
+      return typeof relatedId === 'string' && this.isDescendantOf(relatedId, sessionId)
+    })
+  }
+
+  /**
+   * Shut the runtime down and reap it: a best-effort protocol `shutdown`
+   * bounded by `shutdownTimeoutMs`, then the shared stdin-EOF → SIGTERM →
+   * SIGKILL ladder until the process actually exited. Idempotent.
+   * @returns settlement of the complete teardown.
+   */
+  close(): Promise<void> {
+    this.closeTask ??= this.performClose()
+    return this.closeTask
+  }
+
+  private async performClose(): Promise<void> {
+    const child = this.child
+    if (child === undefined) return
+    try {
+      await this.request('shutdown', undefined, this.options.shutdownTimeoutMs ?? 1_000)
+    } catch (error) {
+      // Diagnostic only: the dispose ladder below is the authoritative teardown
+      // for a runtime that cannot answer shutdown anymore.
+      this.appendStderr([`shutdown request failed: ${errorMessage(error)}`])
+    }
+    await disposeRuntimeProcess(child, {
+      disposeEofGraceMs: this.options.disposeEofGraceMs ?? 6_000,
+      disposeGraceMs: this.options.disposeGraceMs ?? 3_000,
+    })
+    this.transport?.close()
+    this.failSubscriptions(this.closedError('DeepSeek Harness runtime closed'))
+  }
+
+  private dispatchNotification(notification: HarnessNotification): void {
+    this.recordSessionRelationship(notification)
+    for (const subscription of this.subscriptions.values()) subscription.push(notification)
+  }
+
+  private recordSessionRelationship(notification: HarnessNotification): void {
+    if (notification.method !== 'subagent.started') return
+    const parentId = notification.params.parentSessionId
+    const childId = notification.params.childSessionId
+    if (typeof parentId === 'string' && parentId !== '' && typeof childId === 'string' && childId !== '' && parentId !== childId) {
+      this.sessionParents.set(childId, parentId)
+    }
+  }
+
+  private isDescendantOf(sessionId: string, rootSessionId: string): boolean {
+    const visited = new Set<string>()
+    let current = sessionId
+    while (!visited.has(current)) {
+      if (current === rootSessionId) return true
+      visited.add(current)
+      const parent = this.sessionParents.get(current)
+      if (parent === undefined) return false
+      current = parent
+    }
+    // The parent map only ever extends chains upward, so a cycle cannot form.
+    /* v8 ignore next */
+    return false
+  }
+
+  private failSubscriptions(error: Error): void {
+    for (const subscription of this.subscriptions.values()) subscription.fail(error)
+  }
+
+  private appendStderr(lines: string[]): void {
+    const kept = lines.filter(line => line.length > 0)
+    this.stderrTail.push(...kept)
+    if (this.stderrTail.length > STDERR_TAIL_LIMIT) {
+      this.stderrTail.splice(0, this.stderrTail.length - STDERR_TAIL_LIMIT)
+    }
+  }
+
+  private settleStreams(): Promise<void> {
+    return Promise.race([
+      this.streamsSettled,
+      new Promise<void>((resolve) => { setTimeout(resolve, STREAM_SETTLE_MS) }),
+    ])
+  }
+
+  private closedError(reason: string): TransportClosedError {
+    const parts = [reason]
+    if (this.spawnError !== undefined) parts.push(`spawn error: ${this.spawnError.message}`)
+    if (this.exitCode !== undefined) parts.push(`exit code: ${String(this.exitCode)}`)
+    if (this.stderrTail.length > 0) parts.push(`stderr tail:\n${this.stderrTail.join('\n')}`)
+    return new TransportClosedError(parts.join('\n'))
+  }
+}
+
+/**
+ * Whether `value` is a plain JSON object (the wire-boundary shape probe).
+ * @param value - the wire value to probe.
+ * @returns `true` iff `value` is a non-null, non-array object.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** The message of a thrown value (the transport only throws `Error`s; `String` covers the rest). */
+function errorMessage(error: unknown): string {
+  /* v8 ignore next -- the transport and dispose ladder reject only with Errors */
+  return error instanceof Error ? error.message : String(error)
+}

packages/sdk/client/src/dispose.ts

@@ -0,0 +1,99 @@
+/**
+ * Private teardown ladder for the runtime subprocess: stdin EOF (cooperative
+ * quiesce), then SIGTERM, then SIGKILL, resolving only after the process has
+ * actually exited. The SDK client runs OUTSIDE any harness context, so it
+ * cannot ride the `dsh-subprocess` service — this module is the seam's
+ * documented exception for SDK-managed transports.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/dispose
+ */
+
+import type { ChildProcess } from 'node:child_process'
+
+/**
+ * Race the child's exit against a timer. Neither outcome leaves anything
+ * behind on the child: the exit listener is removed on timeout and the timer
+ * is cleared on exit, so the ladder's tiers never accumulate listeners.
+ */
+function exitsWithin(child: ChildProcess, ms: number): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true)
+  return new Promise<boolean>((resolve) => {
+    const onExit = (): void => {
+      clearTimeout(timer)
+      resolve(true)
+    }
+    // `.unref()` so a pending grace timer never keeps the parent's loop alive.
+    const timer = setTimeout(() => {
+      child.removeListener('exit', onExit)
+      resolve(false)
+    }, ms).unref()
+    child.once('exit', onExit)
+  })
+}
+
+/** Force-terminate the runtime and reject if no exit edge arrives within the grace. */
+function forceTerminateWithin(child: ChildProcess, ms: number): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise<void>((resolve, reject) => {
+    let accepted = false
+    let settled = false
+    const cleanup = (): void => {
+      clearTimeout(timer)
+      child.off('exit', onExit)
+      child.off('error', onError)
+    }
+    const settle = (complete: () => void): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      complete()
+    }
+    const onExit = (): void => { settle(resolve) }
+    const onError = (error: Error): void => { settle(() => { reject(error) }) }
+    child.once('exit', onExit)
+    child.once('error', onError)
+    const timer = setTimeout(() => {
+      const disposition = accepted ? 'accepted' : 'refused'
+      settle(() => {
+        reject(new Error(`runtime process did not exit within ${ms}ms after SIGKILL was ${disposition}`))
+      })
+    }, ms).unref()
+    try {
+      accepted = child.kill('SIGKILL')
+      if (child.exitCode !== null || child.signalCode !== null) settle(resolve)
+    } catch (error: unknown) {
+      settle(() => { reject(new Error('SIGKILL failed', { cause: error })) })
+    }
+  })
+}
+
+/**
+ * Tear the runtime down to quiescence, resolving only after exit: close stdin
+ * and allow cooperative flush, then use the host's graceful and forced
+ * termination semantics. POSIX sends `SIGTERM` before `SIGKILL`; Windows
+ * skips directly to forced termination because Node maps both signals to
+ * `TerminateProcess`.
+ * @param child - the runtime child process to tear down.
+ * @param graces - the EOF and termination-confirmation windows (ms).
+ * @param platform - the host platform, injectable for unit coverage.
+ * @throws When forced termination errors or the child does not report exit
+ * within `disposeGraceMs`.
+ */
+export async function disposeRuntimeProcess(
+  child: ChildProcess,
+  graces: { disposeEofGraceMs: number; disposeGraceMs: number },
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  // Already gone: nothing to reap.
+  if (child.exitCode !== null || child.signalCode !== null) return
+  // 1. Close stdin and allow cooperative teardown and durable-state flush.
+  child.stdin?.end()
+  if (await exitsWithin(child, graces.disposeEofGraceMs)) return
+  // 2. POSIX gets a catchable graceful signal; Windows signals all force-terminate.
+  if (platform !== 'win32') {
+    child.kill('SIGTERM')
+    if (await exitsWithin(child, graces.disposeGraceMs)) return
+  }
+  // 3. Force-kill and await a bounded exit edge.
+  await forceTerminateWithin(child, graces.disposeGraceMs)
+}

packages/sdk/client/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * TypeScript client SDK for the DeepSeek Harness runtime: spawn the
+ * `dsh-jsonrpc-agent` runtime as a subprocess and drive agent turns over
+ * stdio JSON-RPC. `DeepSeekHarness` is the high-level run API;
+ * `HarnessClient` is the lower-level protocol client. A pure library — it
+ * registers nothing on a Cordis context; the runtime process it spawns is a
+ * complete harness configured by its own `cordis.yml`.
+ *
+ * @module @deepseek-ai/dsh-sdk-client
+ */
+
+export { DeepSeekHarness, HarnessSession } from './api.ts'
+export type { RunOptions } from './api.ts'
+export {
+  HarnessClient,
+  RequestTimeoutError,
+  SdkProtocolError,
+  TransportClosedError,
+} from './client.ts'
+export type { NotificationSubscription } from './client.ts'
+export { JsonRpcResponseError } from '@deepseek-ai/dsh-sdk-protocol'
+export type {
+  ContentBlock,
+  DeepSeekHarnessOptions,
+  HarnessClientOptions,
+  HarnessNotification,
+  NotificationFilter,
+  RunResult,
+} from './types.ts'

packages/sdk/client/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-sdk-client`.
+ * @module @deepseek-ai/dsh-sdk-client/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-sdk-client'
+
+/** Cordis companion plugin name. */
+export const name = 'sdk-client-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this client library runs outside any harness context
+ * (its peer is a separate runtime process); the runtime's own packages own
+ * the event-stream relations.
+ */
+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 */

packages/sdk/client/src/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Types for the TypeScript SDK client: launch options, notification shapes,
+ * and owned activity results.
+ *
+ * @module @deepseek-ai/dsh-sdk-client/types
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** One server-to-client notification as received off the wire. */
+export interface HarnessNotification {
+  /** The JSON-RPC notification method name. */
+  method: string
+  /** The raw params object; see `HarnessSdkNotificationMap` for the shapes per method. */
+  params: Record<string, unknown>
+}
+
+/** Predicate deciding whether a subscription receives a notification. */
+export type NotificationFilter = (notification: HarnessNotification) => boolean
+
+/** Launch and timeout options for {@link HarnessClient}. */
+export interface HarnessClientOptions {
+  /** The runtime executable (the `dsh-jsonrpc-agent` bin, a packaged exe, or `node`). */
+  command: string
+  /** Arguments passed to {@link command}. */
+  args?: string[]
+  /** Working directory for the runtime process itself. */
+  cwd?: string
+  /**
+   * The complete child environment. `undefined` inherits the parent env
+   * verbatim; passing an object replaces it entirely, so callers own
+   * credential policy (see `scrubbedParentEnv` in `@deepseek-ai/dsh-subprocess`
+   * for the shared scrub-then-merge base).
+   */
+  env?: NodeJS.ProcessEnv
+  /** Per-request timeout (ms); `undefined` waits indefinitely (a turn can legitimately run long). */
+  requestTimeoutMs?: number
+  /** Bound (ms) on the protocol `shutdown` exchange inside `close()` (default 1000). */
+  shutdownTimeoutMs?: number
+  /** Grace (ms) for the runtime's stdin-EOF quiesce during `close()` (default 6000). */
+  disposeEofGraceMs?: number
+  /** Termination confirmation window (ms) after SIGTERM/SIGKILL during `close()` (default 3000). */
+  disposeGraceMs?: number
+}
+
+/** Options for the high-level {@link DeepSeekHarness} wrapper. */
+export interface DeepSeekHarnessOptions {
+  /** Launch spec for the runtime subprocess (command, args, cwd, env, timeouts). */
+  launch: HarnessClientOptions
+  /** Workspace cwd recorded on every SDK-created session (default: the launch cwd, else `process.cwd()`). */
+  cwd?: string
+  /** Provider route for SDK-created agents (default `deepseek-official`). */
+  provider?: string
+  /** Model for SDK-created agents (default `deepseek-v4-flash`). */
+  model?: string
+  /** Maximum output tokens for each conversation-model request. */
+  maxTokens?: number
+}
+
+/** One owned session activity interval, from enqueue receipt through idle. */
+export interface RunResult {
+  /** The session the activity ran on. */
+  sessionId: string
+  /** Concatenated text of the interval's last assistant message (empty when none). */
+  finalResponse: string
+  /** Every `session.event` payload for the root session, in wire order. */
+  events: SessionEvent[]
+  /** Every notification for the root session and discovered descendants, in wire order. */
+  notifications: HarnessNotification[]
+}
+
+/** Re-exported content-block alias so SDK callers need no extra import. */
+export type { ContentBlock }