Merge remote-tracking branch 'origin/master' into codex/trim-ai-prose

# Conflicts: # docs/config-catalog.md # docs/event-producer-consumer.md # docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md # examples/acp-agent/tests/acp.snapshot.ts # packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts # packages/code-runtime/code-runtime-worker/tsdown.config.ts
2026-07-14 00:40:36 +08:00
parent 274db4966a fdc5dea100
commit 972e7cc77d
115 changed files with 10314 additions and 115 deletions
--- a/packages/ui/jsonrpc/src/index.ts
+++ b/packages/ui/jsonrpc/src/index.ts
@@ -0,0 +1,83 @@
+/**
+ * SDK-facing JSON-RPC plugin over stdio. An external `cordis.yml` decides
+ * whether to load it; see the single-executable RFC and package README.
+ * Stdout is reserved for protocol frames, so the tree must not load a stdout logger.
+ * This plugin answers `shutdown`, disposes its own fiber, and exits 0; the app bin
+ * owns EOF and signal exits. Keep named plugin exports with no default export so
+ * Loader `unwrapExports` preserves `name`, `inject`, `Config`, and `apply`.
+ *
+ * @module @deepseek-ai/dsh-jsonrpc
+ */
+
+import type { Context } from 'cordis'
+import type { Readable, Writable } from 'node:stream'
+import Schema from 'schemastery'
+import { HarnessSdkServer } from './server.ts'
+import { JsonRpcLineTransport } from './transport.ts'
+
+export * from './server.ts'
+export * from './transport.ts'
+
+export const name = 'jsonrpc'
+// Only the agent factory is required; initialize reads the optional LLM seam with ctx.get().
+export const inject = ['agents']
+
+/** Runtime-only test seams; no field is configurable from `cordis.yml`. */
+export interface JsonRpcConfig {
+  /** Transport input override; production uses `process.stdin`. */
+  input?: Readable
+  /** Transport output override; production uses `process.stdout`. */
+  output?: Writable
+  /** Process-exit override; production uses `process.exit`. */
+  exit?: (code: number) => void
+}
+
+export const Config: Schema<JsonRpcConfig> = Schema.object({})
+
+/**
+ * Serve SDK requests over the configured streams. Effect disposal shuts down
+ * SDK-created agents and closes the transport. A `shutdown` response is flushed
+ * before this plugin's fiber is disposed and the process exits 0; the app bin
+ * owns root-context disposal for EOF and signals.
+ */
+export function apply(ctx: Context, config: JsonRpcConfig): void {
+  // The later transport callback must dispose this plugin's fiber, not its ambient context.
+  const fiber = ctx.fiber
+  /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */
+  const input = config.input ?? process.stdin
+  /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */
+  const output = config.output ?? process.stdout
+  /* v8 ignore next -- production exit wiring; tests always inject the runtime seams */
+  const exit = config.exit ?? ((code: number): void => { process.exit(code) })
+
+  const transport = new JsonRpcLineTransport(input, output)
+  const server = new HarnessSdkServer(ctx, transport)
+
+  // Share one exit task and attempt flush and disposal independently before exiting.
+  let exitTask: Promise<void> | undefined
+  const disposeAndExit = (): Promise<void> => {
+    exitTask ??= (async () => {
+      await Promise.allSettled([Promise.resolve().then(() => transport.flush())])
+      await Promise.allSettled([Promise.resolve().then(() => fiber.dispose())])
+      exit(0)
+    })()
+    return exitTask
+  }
+
+  transport.onRequest(async (method, params) => {
+    const result = await server.handleRequest(method, params)
+    if (method === 'shutdown') {
+      // Run after the handler result is written; the task then flushes, disposes, and exits.
+      setImmediate(() => { void disposeAndExit() })
+    }
+    return result
+  })
+
+  ctx.effect(() => {
+    transport.start()
+    return async () => {
+      await server.shutdown()
+      transport.close()
+    }
+  }, 'jsonrpc.serve')
+}
--- a/packages/ui/jsonrpc/src/server.ts
+++ b/packages/ui/jsonrpc/src/server.ts
@@ -0,0 +1,262 @@
+/**
+ * JSON-RPC methods and notifications for SDK clients. Requests are
+ * `initialize`, repeated `session/prompt`, then `shutdown`; notifications carry
+ * durable session events, settled turns, and subagent lineage/outcomes. The
+ * external `cordis.yml` owns plugins, persistence, and the adapter set.
+ *
+ * @module @deepseek-ai/dsh-jsonrpc/server
+ */
+
+import type { Context } from 'cordis'
+import { resolve } from 'node:path'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { AgentHandle } from '@deepseek-ai/dsh-agent'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import { SessionId, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SubagentRunEndInfo } from '@deepseek-ai/dsh-subagent'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import type { JsonRpcTransportPeer } from './transport.ts'
+
+/** One-time SDK initialization parameters. */
+export interface InitializeParams {
+  /** Working directory recorded on every SDK-created session's header. */
+  cwd: string
+  /** Model name every SDK-created agent runs on (see {@link HarnessSdkServer.initialize} for adapter fallback). */
+  model: string
+}
+
+/** SDK handshake result. */
+export interface InitializeResult {
+  /** Wire-stable server identity (`deepseek-harness-sdk-runtime`) and version. */
+  serverInfo: { name: string; version: string }
+}
+
+/**
+ * Parameters of a `session/prompt` request: one user turn on one SDK session,
+ * with at most one in flight per 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[]
+}
+
+/** Accepted prompt result; the outcome is reported by `session.finished`. */
+export interface SessionPromptResult {
+  /** Always `true`; the turn outcome is the paired `session.finished` notification. */
+  accepted: true
+}
+
+interface SessionRecord {
+  handle: AgentHandle
+  lastTurnEnd: TurnEndReason | undefined
+  activePrompt: boolean
+}
+
+interface SubagentRecord {
+  childSessionId: string
+  parentSessionId: string | undefined
+}
+
+/**
+ * SDK server over one booted harness context and transport peer. Construction
+ * subscribes to session, agent, and subagent lifecycle events until shutdown;
+ * reinitialization is unsupported.
+ */
+export class HarnessSdkServer {
+  private cwd = process.cwd()
+  private model = 'deepseek'
+  private llmFiber: { dispose(): Promise<void> } | undefined
+  private readonly sessions = new Map<string, SessionRecord>()
+  private readonly sessionCreations = new Map<string, Promise<SessionRecord>>()
+  private readonly subagentSessions = new Map<string, SubagentRecord>()
+  private readonly disposers: (() => void)[] = []
+  private shutdownTask: Promise<Record<string, never>> | undefined
+  private shuttingDown = false
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly transport: JsonRpcTransportPeer,
+  ) {
+    this.disposers.push(ctx.on('session/event', (session, event) => {
+      if (event.type === 'turn/end') {
+        const rec = this.sessions.get(String(session.id))
+        if (rec) rec.lastTurnEnd = event.data.reason
+      }
+      this.transport.notify('session.event', { sessionId: String(session.id), event })
+    }))
+    this.disposers.push(ctx.on('session/created', (session) => {
+      const parentSession = session.header.parentSession
+      if (parentSession === undefined) return
+      this.transport.notify('subagent.started', {
+        parentSessionId: String(parentSession),
+        childSessionId: String(session.id),
+      })
+    }))
+    // Cache lineage before child disposal removes the agent from the registry.
+    this.disposers.push(ctx.on('agent/created', (agent) => {
+      this.subagentSessions.set(String(agent.id), {
+        childSessionId: String(agent.session.id),
+        parentSessionId: agent.session.header.parentSession === undefined
+          ? undefined
+          : String(agent.session.header.parentSession),
+      })
+    }))
+    this.disposers.push(ctx.on('subagent/end', (info: SubagentRunEndInfo) => {
+      const rec = this.subagentSessions.get(String(info.id))
+      const agent = this.ctx.agents.get(info.id)
+      const childSessionId = rec?.childSessionId ?? (agent === undefined ? undefined : String(agent.session.id))
+      const parentSessionId = rec?.parentSessionId ?? (
+        agent?.session.header.parentSession === undefined ? undefined : String(agent.session.header.parentSession)
+      )
+      if (childSessionId === undefined) return
+      this.transport.notify('subagent.finished', {
+        provider: info.provider,
+        agentId: String(info.id),
+        ...(parentSessionId === undefined ? {} : { parentSessionId }),
+        childSessionId,
+        status: info.stopReason === 'completed' ? 'ok' : 'error',
+        stopReason: info.stopReason,
+        ...(info.lastAssistantMessage === undefined ? {} : { lastAssistantMessage: info.lastAssistantMessage }),
+      })
+    }))
+  }
+
+  /**
+   * Record cwd and model, mounting the DeepSeek adapter only when the config
+   * registered no adapter for that model.
+   * @param params - the SDK handshake parameters.
+   * @returns the server identity for the handshake.
+   */
+  async initialize(params: InitializeParams): Promise<InitializeResult> {
+    this.cwd = resolve(params.cwd)
+    this.model = params.model
+    if (!this.llmFiber && !this.hasAdapterFor(this.model)) {
+      this.llmFiber = await this.ctx.plugin(LlmDeepSeek, { models: [this.model] })
+    }
+    return { serverInfo: { name: 'deepseek-harness-sdk-runtime', version: '0.0.1' } }
+  }
+
+  /**
+   * Get or create the session agent, send the prompt, await quiescence, then
+   * notify `session.finished`. A session accepts one prompt at a time; other
+   * sessions remain independent.
+   * @param params - the target session id and prompt content.
+   * @returns `{ accepted: true }` after the turn settled.
+   */
+  async prompt(params: SessionPromptParams): Promise<SessionPromptResult> {
+    const rec = await this.getOrCreateSession(params.sessionId)
+    if (rec.activePrompt) throw new Error(`session already has an active prompt: ${params.sessionId}`)
+    rec.activePrompt = true
+    try {
+      rec.lastTurnEnd = undefined
+      rec.handle.agent.send(params.contentBlocks)
+      await rec.handle.agent.whenIdle()
+      const status = this.finishedStatus(rec.lastTurnEnd)
+      this.transport.notify('session.finished', {
+        sessionId: params.sessionId,
+        status,
+        reason: rec.lastTurnEnd,
+      })
+      return { accepted: true }
+    } finally {
+      rec.activePrompt = false
+    }
+  }
+
+  /**
+   * Dispose SDK-created agents to quiescence, unmount the server-mounted adapter,
+   * and detach subscriptions. The surrounding context remains running.
+   * @returns an empty object (the JSON-RPC result).
+   */
+  shutdown(): Promise<Record<string, never>> {
+    this.shutdownTask ??= this.performShutdown()
+    return this.shutdownTask
+  }
+
+  private async performShutdown(): Promise<Record<string, never>> {
+    this.shuttingDown = true
+    const pendingCreations = [...this.sessionCreations.values()]
+    await Promise.allSettled(pendingCreations)
+    this.sessionCreations.clear()
+    const records = [...this.sessions.values()]
+    this.sessions.clear()
+    this.subagentSessions.clear()
+    const failures: unknown[] = []
+    while (this.disposers.length > 0) {
+      try {
+        this.disposers.pop()?.()
+      } catch (error) {
+        failures.push(error)
+      }
+    }
+    const teardownResults = await Promise.allSettled([
+      ...records.map(rec => Promise.resolve().then(() => rec.handle.dispose())),
+      ...(this.llmFiber === undefined ? [] : [Promise.resolve().then(() => this.llmFiber?.dispose())]),
+    ])
+    this.llmFiber = undefined
+    failures.push(...teardownResults
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map(result => result.reason as unknown))
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'SDK server teardown failed')
+    return {}
+  }
+
+  /**
+   * Dispatch an incoming request; unknown methods throw for transport conversion
+   * to a JSON-RPC error response.
+   * @param method - the JSON-RPC method name.
+   * @param params - the raw params object from the wire.
+   * @returns the handler's result, to be serialized as the response.
+   */
+  async handleRequest(method: string, params: Record<string, unknown> | undefined): Promise<unknown> {
+    switch (method) {
+      case 'initialize':
+        return this.initialize(params as unknown as InitializeParams)
+      case 'session/prompt':
+        return this.prompt(params as unknown as SessionPromptParams)
+      case 'shutdown':
+        return this.shutdown()
+      default:
+        throw new Error(`unknown DeepSeek Harness SDK runtime method: ${method}`)
+    }
+  }
+
+  private async getOrCreateSession(sessionId: string): Promise<SessionRecord> {
+    if (this.shuttingDown) throw new Error('SDK server is shutting down')
+    const existing = this.sessions.get(sessionId)
+    if (existing) return existing
+    const pending = this.sessionCreations.get(sessionId)
+    if (pending) return pending
+    const creation = this.createSession(sessionId)
+    this.sessionCreations.set(sessionId, creation)
+    void creation.then(
+      () => { this.sessionCreations.delete(sessionId) },
+      () => { this.sessionCreations.delete(sessionId) },
+    )
+    return creation
+  }
+
+  private async createSession(sessionId: string): Promise<SessionRecord> {
+    const handle = await this.ctx.agents.create({
+      agentId: AgentId(sessionId),
+      sessionId: SessionId(sessionId),
+      meta: { cwd: this.cwd },
+      agentOptions: { model: this.model },
+    })
+    const rec: SessionRecord = { handle, lastTurnEnd: undefined, activePrompt: false }
+    this.sessions.set(sessionId, rec)
+    return rec
+  }
+
+  private finishedStatus(reason: TurnEndReason | undefined): 'ok' | 'error' {
+    if (!reason) return 'error'
+    return reason.kind === 'completed' ? 'ok' : 'error'
+  }
+
+  private hasAdapterFor(model: string): boolean {
+    return this.ctx.get('llm')?.models().includes(model) ?? false
+  }
+}
--- a/packages/ui/jsonrpc/src/transport.ts
+++ b/packages/ui/jsonrpc/src/transport.ts
@@ -0,0 +1,223 @@
+/**
+ * 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-jsonrpc/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
+
+/**
+ * Outbound request and notification surface used by {@link HarnessSdkServer}.
+ */
+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 on an error response, write failure, or closure.
+   */
+  request(method: string, params: Record<string, unknown>): 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?: Record<string, unknown>): 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: Record<string, unknown>): 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?: Record<string, unknown>): 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 Error(typeof error.message === 'string' ? error.message : 'JSON-RPC error'))
+      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> : {}
+}