Merge branch 'codex/tool-json-schema-dsl' into codex/canonical-tool-output

packages/host/runtime/src/api-proxy.ts

@@ -0,0 +1,429 @@
+/**
+ * Host-side ApiProxy implementation (minimal-first —
+ * describe/list/create/history/prompt/cancel and both streams are real,
+ * respond is a stub). Signature discipline: unary takes the narrow
+ * RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { stat } from 'node:fs/promises'
+import type { Context } from 'cordis'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+
+/** Page size when history is called without maxMessages. */
+const DEFAULT_MAX_MESSAGES = 50
+
+/** Surface message event types (the pagination counting unit). */
+const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message'])
+
+/**
+ * Message-boundary pagination: count maxMessages surface messages backwards from
+ * the window tail; the cut is the starting seq of the oldest message group
+ * (chunks group via sourceEventSeqs — never cut mid-message). The tail page
+ * naturally includes the in-progress partial.
+ */
+function paginate(
+  events: readonly SessionEvent[],
+  beforeSeq: number | undefined,
+  maxMessages: number,
+): { events: SessionEvent[]; hasMore: boolean } {
+  const window = beforeSeq === undefined ? [...events] : events.filter(event => event.seq < beforeSeq)
+  let count = 0
+  let cut = 0
+  for (let i = window.length - 1; i >= 0; i--) {
+    const event = window[i] as SessionEvent
+    if (!MESSAGE_TYPES.has(event.type)) continue
+    count++
+    const sources = (event as { sourceEventSeqs?: number[] }).sourceEventSeqs
+    const groupStart = sources !== undefined && sources.length > 0 ? Math.min(event.seq, ...sources) : event.seq
+    if (count >= maxMessages) {
+      cut = groupStart
+      break
+    }
+  }
+  const page = window.filter(event => event.seq >= cut)
+  return { events: page, hasMore: cut > 0 }
+}
+
+/** Wrap an ok result echoing the request's rpcId. */
+function ok<T>(request: RpcRequest<unknown>, value: T): RpcResponse<T> {
+  return { rpcId: request.rpcId, result: { ok: true, value } }
+}
+
+/** Wrap an error result echoing the request's rpcId. */
+function err<T>(request: RpcRequest<unknown>, error: RpcError): RpcResponse<T> {
+  return { rpcId: request.rpcId, result: { ok: false, error } }
+}
+
+/** Simple async queue: core callbacks push, the AsyncIterable pulls; abort/return cleans up. */
+class FrameQueue<F> {
+  private buffer: F[] = []
+  private waiter: (() => void) | undefined
+  private done = false
+
+  push(item: F): void {
+    if (this.done) return
+    this.buffer.push(item)
+    this.waiter?.()
+  }
+
+  end(): void {
+    this.done = true
+    this.waiter?.()
+  }
+
+  async *iterate(signal: AbortSignal, cleanup: () => void): AsyncGenerator<F> {
+    const onAbort = (): void => { this.end() }
+    signal.addEventListener('abort', onAbort, { once: true })
+    try {
+      while (true) {
+        while (this.buffer.length > 0) yield this.buffer.shift() as F
+        if (this.done || signal.aborted) return
+        await new Promise<void>((resolve) => { this.waiter = resolve })
+        this.waiter = undefined
+      }
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+      cleanup()
+    }
+  }
+}
+
+/**
+ * Server-side frame mint: pure pushes get a fresh rpcId per frame (stable ids
+ * for answerable frames belong to the approval/question registry, absent in
+ * this minimal version).
+ */
+function frame<F>(payload: F): RpcRequest<F> {
+  return { rpcId: RpcId(randomUUID()), payload }
+}
+
+/** SessionSummary projection for attached (in-memory) sessions. */
+function summarize(session: Session, running: boolean): SessionSummary {
+  return {
+    sessionId: session.id,
+    updatedAt: session.events.at(-1)?.time ?? session.header.createdAt,
+    running,
+    ...session.header.parentSession === undefined ? {} : { parentSessionId: session.header.parentSession },
+    ...session.header.cwd === undefined ? {} : { cwd: session.header.cwd },
+  }
+}
+
+/**
+ * SessionSummary projection for cold (persisted, unattached) sessions.
+ * updatedAt is the log file's mtime; backends without a per-session file
+ * (locate() undefined) fall back to the header's createdAt.
+ */
+async function summarizeCold(persistence: SessionPersistence, meta: SessionHeader): Promise<SessionSummary> {
+  let updatedAt = meta.createdAt
+  const location = persistence.locate(meta)
+  if (location !== undefined) {
+    try {
+      updatedAt = (await stat(location.path)).mtimeMs
+    } catch {
+      // The log vanished between list() and stat() (concurrent cleanup); createdAt stands in.
+    }
+  }
+  return {
+    sessionId: meta.id,
+    updatedAt,
+    running: false,
+    ...meta.parentSession === undefined ? {} : { parentSessionId: meta.parentSession },
+    /* v8 ignore next -- the empty arm needs a cwd-less meta, but list()
+    filters those out (legacy logs are not served); the conditional mirrors
+    summarize() shape. */
+    ...meta.cwd === undefined ? {} : { cwd: meta.cwd },
+  }
+}
+
+/** Host-level default agent routing (same shape as bootHost's HostDefaults; avoids an impl→index reverse import). */
+export interface ApiProxyDefaults {
+  provider: string
+  model: string
+  /** Default project directory for new sessions whose create request carries no cwd. */
+  cwd: string
+}
+
+/** The tool/call payload fields the presenter path reads. */
+interface ToolCallData { callId: string; name: string; arguments: string }
+/** The tool/result payload fields the presenter path reads. */
+interface ToolResultData { callId: string; content: ContentBlock[]; isError: boolean; meta?: JsonValue }
+
+/**
+ * Compute the render intent for a tool/call or tool/result event through the
+ * presenters registered at this moment; every other event type gets none. A
+ * result's presenter needs its call's parsed args — `argsFor` supplies them
+ * (live: the per-session call table; history: an in-page backscan), returning
+ * undefined when the pairing is unavailable (e.g. the call fell off the page),
+ * which soft-falls to no view. Presenter or JSON.parse throws also soft-fall:
+ * the client's documented default (generic JSON card) covers every miss.
+ */
+function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) => unknown): ToolEventView | undefined {
+  try {
+    if (event.type === 'tool/call') {
+      const { name, arguments: raw } = event.data as ToolCallData
+      const view = ctx.tools.get(name)?.presentCall?.(JSON.parse(raw))
+      return view === undefined ? undefined : { for: 'call', view }
+    }
+    if (event.type === 'tool/result') {
+      const { callId, content, isError, meta } = event.data as ToolResultData
+      const call = argsFor(callId) as { name: string; args: unknown } | undefined
+      if (call === undefined) return undefined
+      const view = ctx.tools.get(call.name)?.presentResult?.(call.args, { content, isError, ...meta === undefined ? {} : { meta } })
+      return view === undefined ? undefined : { for: 'result', view }
+    }
+  } catch (error: unknown) {
+    // A throwing presenter (or unparseable arguments) must not break delivery;
+    // the event still ships, just without a view.
+    console.error(`api-proxy: presenter failed for ${event.type}, falling back to generic: ${String(error)}`)
+  }
+  return undefined
+}
+
+/**
+ * Resolve a tool/result's call pairing by scanning a window of events backwards
+ * for the matching tool/call. Used by the history path (the page is the
+ * window — a cross-page pairing soft-falls to no view) and by live-path table
+ * misses after a reconnect-eviction.
+ */
+function backscanArgs(events: readonly SessionEvent[], callId: string): { name: string; args: unknown } | undefined {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i] as SessionEvent
+    if (event.type !== 'tool/call') continue
+    const data = event.data as ToolCallData
+    if (data.callId !== callId) continue
+    try {
+      return { name: data.name, args: JSON.parse(data.arguments) }
+    } catch {
+      // Unparseable stored arguments: same soft-fall as a live parse failure.
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * Thrown by the cold-resume path when the id names no servable session
+ * (absent from the store, or a pre-project legacy log without a cwd).
+ */
+class SessionNotFound extends Error {}
+
+/**
+ * Implement ApiProxy over the ctx composed by bootHost.
+ * @param ctx - the root context returned by bootHost (sessions/agents services mounted).
+ * @param defaults - host-level default provider/model: injected as
+ * agentOptions on create/resume, reported by describe from the same source.
+ * @returns the ApiProxy implementation (minimal-first; stubs noted per method).
+ */
+export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
+  const agentOptions = { provider: defaults.provider, model: defaults.model }
+  /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
+  const resumes = new Map<SessionId, Promise<Agent>>()
+
+  /**
+   * Gate the cold path on the store: an id absent from it, or naming a legacy
+   * log without a cwd (pre-release stance: not served, no compatibility), is
+   * not-found before any resume is attempted. With the gate passed, a later
+   * resume failure is genuinely internal. No persistence configured skips the
+   * gate — resume itself then fails loud with its own diagnostic.
+   */
+  async function assertServable(sessionId: SessionId): Promise<void> {
+    const persistence = ctx.get('sessionPersistence')
+    if (persistence === undefined) return
+    const meta = (await persistence.list()).find(m => m.id === sessionId)
+    if (meta === undefined || meta.cwd === undefined) throw new SessionNotFound(`session "${sessionId}" not found`)
+  }
+
+  async function agentFor(sessionId: SessionId): Promise<{ agent: Agent } | { error: RpcError }> {
+    const live = ctx.agents.get(sessionId)
+    if (live !== undefined) return { agent: live }
+    let resume = resumes.get(sessionId)
+    if (resume === undefined) {
+      resume = (async () => {
+        try {
+          await assertServable(sessionId)
+          const handle = await ctx.agents.resume({ resumeSessionId: sessionId, agentOptions })
+          return handle.agent
+        } finally {
+          resumes.delete(sessionId)
+        }
+      })()
+      resumes.set(sessionId, resume)
+    }
+    try {
+      return { agent: await resume }
+    } catch (error: unknown) {
+      if (error instanceof SessionNotFound) {
+        return { error: { code: 'session-not-found', message: error.message, details: { sessionId } } }
+      }
+      // The internal details slot is contractually {}; the reason rides the message.
+      return { error: { code: 'internal', message: `resume failed for session "${sessionId}": ${String(error)}`, details: {} } }
+    }
+  }
+
+  return {
+    sessions: {
+      // Attached sessions summarize from memory; persisted-but-unattached (cold)
+      // sessions merge in from the persistence store so history survives restarts.
+      // Legacy logs without a cwd (pre-project stance) are not served — every
+      // session now records its project at create time.
+      async list(request) {
+        const items = ctx.sessions.list().map((session) => {
+          const agent = ctx.agents.get(session.id)
+          return summarize(session, agent?.status === 'running')
+        })
+        const attached = new Set(items.map(item => item.sessionId))
+        const persistence = ctx.get('sessionPersistence')
+        if (persistence !== undefined) {
+          const cold = (await persistence.list()).filter(meta => !attached.has(meta.id) && meta.cwd !== undefined)
+          items.push(...await Promise.all(cold.map(meta => summarizeCold(persistence, meta))))
+        }
+        items.sort((a, b) => b.updatedAt - a.updatedAt)
+        return ok(request, { items })
+      },
+
+      async create(request) {
+        const sessionId = `session-${randomUUID()}` as SessionId
+        // A session's cwd is its project path. When the creator does not choose
+        // one, the default project is the host-level default (the host process
+        // working directory unless boot overrides it).
+        const cwd = request.payload.cwd ?? defaults.cwd
+        const handle = await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })
+        return ok(request, { sessionId: handle.agent.id })
+      },
+
+      async history(request) {
+        const { sessionId, beforeSeq, maxMessages } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const page = paginate(found.agent.session.events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
+        // Views are computed against the registry at pagination time; result
+        // pairing scans within the page only (message-boundary pagination keeps
+        // a call and its result on one page — a cross-page miss soft-falls).
+        const entries: HistoryEntry[] = page.events.map((event) => {
+          const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
+          return { event, ...view === undefined ? {} : { view } }
+        })
+        return ok(request, { events: entries, hasMore: page.hasMore })
+      },
+
+      async prompt(request) {
+        const { sessionId, mode, content } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const agent = found.agent
+        // The rpcId rides MessageSource into user/message (merge declaration in api/sessions.ts; provisional correlation).
+        const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
+        try {
+          if (mode === 'steer') agent.steer(content, { source })
+          else agent.send(content, { source })
+        } catch (error: unknown) {
+          // A synchronous throw from send/steer means disposed or invalid input; surface as agent-busy with the reason attached.
+          return err(request, { code: 'agent-busy', message: 'prompt rejected', details: { reason: String(error) } })
+        }
+        return ok(request, { accepted: true as const })
+      },
+
+      cancel(request) {
+        const { sessionId } = request.payload
+        const agent = ctx.agents.get(sessionId)
+        if (agent === undefined) {
+          return Promise.resolve(err(request, {
+            code: 'session-not-found',
+            message: `session "${sessionId}" not found (not attached)`,
+            details: { sessionId },
+          }))
+        }
+        agent.cancel()
+        return Promise.resolve(ok(request, { accepted: true as const }))
+      },
+    },
+
+    host: {
+      describe(request) {
+        // TODO(step2): version should read apps/cli's package.json; placeholder for now.
+        return Promise.resolve(ok(request, {
+          version: '0.0.1',
+          cwd: process.cwd(),
+          provider: defaults.provider,
+          model: defaults.model,
+          attachedSessions: ctx.agents.list().length,
+        }))
+      },
+    },
+
+    events: {
+      mux(_request, signal) {
+        const queue = new FrameQueue<RpcRequest<MuxFrame>>()
+        for (const session of ctx.sessions.list()) {
+          queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+        }
+        // Per-session open-call table for result-view pairing. Bounded by the
+        // per-turn call count: entries clear on turn/end; a table miss (stream
+        // opened mid-turn) backscans the session's in-memory events instead.
+        const openCalls = new Map<SessionId, Map<string, { name: string; args: unknown }>>()
+        const disposers = [
+          ctx.on('session/event', (session: Session, event: SessionEvent) => {
+            if (event.type === 'tool/call') {
+              const data = event.data as ToolCallData
+              try {
+                let table = openCalls.get(session.id)
+                if (table === undefined) openCalls.set(session.id, table = new Map<string, { name: string; args: unknown }>())
+                table.set(data.callId, { name: data.name, args: JSON.parse(data.arguments) })
+              } catch {
+                // Unparseable model arguments: leave the table unset; the result view soft-falls.
+              }
+            } else if (event.type === 'turn/end') {
+              openCalls.delete(session.id)
+            }
+            const view = viewFor(ctx, event, callId =>
+              openCalls.get(session.id)?.get(callId) ?? backscanArgs(session.events, callId))
+            queue.push(frame({ type: 'session/event', sessionId: session.id, event, ...view === undefined ? {} : { view } }))
+          }),
+          ctx.on('session/created', (session: Session) => {
+            queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+          }),
+          ctx.on('session/disposed', (session: Session) => {
+            openCalls.delete(session.id)
+          }),
+        ]
+        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+      },
+
+      host(_request, signal) {
+        const queue = new FrameQueue<RpcRequest<HostFrame>>()
+        const disposers = [
+          ctx.on('session/created', (session: Session) => {
+            queue.push(frame({
+              type: 'host/session-added',
+              sessionId: session.id,
+              ...session.header.parentSession === undefined ? {} : { parentSessionId: session.header.parentSession },
+            }))
+          }),
+          ctx.on('session/disposed', (session: Session) => {
+            queue.push(frame({ type: 'host/session-removed', sessionId: session.id }))
+          }),
+          ctx.on('agent/status', (agent: Agent, status: AgentStatus) => {
+            if (status === 'disposed') return
+            queue.push(frame({ type: 'host/session-status', sessionId: agent.id, running: status === 'running' }))
+          }),
+          ctx.on('agent/error', (agent: Agent, _turn: number, _step: number, error: Error) => {
+            queue.push(frame({ type: 'host/agent-error', sessionId: agent.id, message: String(error) }))
+          }),
+        ]
+        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+      },
+    },
+
+    // TODO(step2): approval/question pending registry (wire answerer + proxy provider).
+    respond(_message: ClientResponse): Promise<RpcReceipt> {
+      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+    },
+  }
+}

packages/host/runtime/src/boot.ts

@@ -0,0 +1,133 @@
+/**
+ * Core spine composition for the dsh host: mounts the harness core plugins
+ * one by one (each awaited so a load failure surfaces deterministically at
+ * boot, unlike bundle plugins whose children mount unawaited).
+ */
+
+import { Context } from 'cordis'
+import Timer from '@cordisjs/plugin-timer'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import LocalBashExecutor from '@deepseek-ai/dsh-bash-local'
+import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import * as toolTodo from '@deepseek-ai/dsh-tool-todo'
+import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
+import FsLocal from '@deepseek-ai/dsh-fs-local'
+import * as fsPolicy from '@deepseek-ai/dsh-fs-policy'
+import * as toolFs from '@deepseek-ai/dsh-tool-fs'
+import * as toolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
+import SkillService from '@deepseek-ai/dsh-skill'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
+import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
+import TokenMeter from '@deepseek-ai/dsh-token-meter'
+import CompactBasic from '@deepseek-ai/dsh-compact-basic'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork'
+import * as toolSubagent from '@deepseek-ai/dsh-tool-subagent'
+import WorkflowWorkerthread from '@deepseek-ai/dsh-workflow-workerthread'
+import * as toolWorkflow from '@deepseek-ai/dsh-tool-workflow'
+import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
+import SpillLocal from '@deepseek-ai/dsh-spill-local'
+import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
+
+/** Options for bootHost — the assembly-layer composition knobs. */
+export interface BootHostOptions {
+  /** Root directory for JSONL session persistence. */
+  persistenceRoot: string
+  /** Default provider route for created/resumed agents (defaults to 'deepseek', the only adapter bootHost registers). */
+  provider?: string
+  /** Default model id (defaults to 'deepseek-v4-flash', matching the demos). */
+  model?: string
+  /**
+   * Default project directory for sessions created without an explicit cwd
+   * (defaults to the host process working directory). A session's cwd is its
+   * project path — a per-session choice, not a host property; this option only
+   * supplies the value used when the creator does not choose one.
+   */
+  cwd?: string
+}
+
+/** Host-level default agent routing: the single source injected on create and reported by host.describe. */
+export interface HostDefaults {
+  provider: string
+  model: string
+  /** Default project directory for new sessions whose create request carries no cwd. */
+  cwd: string
+}
+
+/** Booted host handle: composed root context + resolved defaults + disposer. */
+export interface HostHandle {
+  /** Root context with the full plugin assembly mounted. */
+  ctx: Context
+  /** Resolved default agent routing (options ?? built-in fallbacks). */
+  defaults: HostDefaults
+  /** Tear down the whole plugin tree. */
+  dispose(): Promise<void>
+}
+
+/**
+ * Compose the harness host plugin assembly (the one place deciding which plugins mount and
+ * with what defaults — shells must not alter the assembly).
+ * @param options - persistence root and optional default provider/model.
+ * @returns the booted handle (ctx + defaults + dispose).
+ */
+export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
+  const defaults: HostDefaults = {
+    provider: options.provider ?? 'deepseek',
+    model: options.model ?? 'deepseek-v4-flash',
+    cwd: options.cwd ?? process.cwd(),
+  }
+  const ctx = new Context()
+  await ctx.plugin(Timer)
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(TaskService)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LlmDeepSeek, {})
+  await ctx.plugin(SessionPersistenceJsonl, { root: options.persistenceRoot, compression: 'none' })
+  await ctx.plugin(LocalBashExecutor, {})
+  // Tool suite mirroring the demo:repl composition (repl-agent/cordis.yml +
+  // the agent-spine bundle) so web sessions get the same coding-agent tool
+  // face; deviations are noted inline.
+  await ctx.plugin(toolBash, {})
+  await ctx.plugin(toolTodo)
+  await ctx.plugin(toolTasks, {})
+  // fs paths resolve against the host default project rather than the raw
+  // process cwd — the same source create() injects into session.cwd.
+  await ctx.plugin(FsLocal, { cwd: defaults.cwd })
+  await ctx.plugin(fsPolicy)
+  await ctx.plugin(toolFs, {})
+  await ctx.plugin(toolFsSearch, {})
+  // Skill stack with the demo default dshHome (~/.dsh via resolveDshHome).
+  await ctx.plugin(SkillService, {})
+  await ctx.plugin(SkillLocal, {})
+  await ctx.plugin(toolSkill, {})
+  // Request pressure + compaction (service-wide defaults, as in repl-agent).
+  await ctx.plugin(TokenMeter)
+  await ctx.plugin(CompactBasic)
+  // Subagent spawn/fork backends and their two model-facing tool instances.
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
+  await ctx.plugin(SubagentFork, { providerName: 'fork' })
+  await ctx.plugin(toolSubagent, { provider: 'spawn', toolName: 'subagent' })
+  await ctx.plugin(toolSubagent, { provider: 'fork', toolName: 'subagent_fork' })
+  await ctx.plugin(WorkflowWorkerthread, { provider: 'spawn' })
+  await ctx.plugin(toolWorkflow, {})
+  // Declared per-tool timeouts become enforced deadlines.
+  await ctx.plugin(timeoutPolicy)
+  // Oversized tool output spills to session-scoped files (repl-agent budget).
+  await ctx.plugin(SpillLocal, {})
+  await ctx.plugin(spillPolicy, { maxInlineBytes: 50000 })
+  return { ctx, defaults, dispose: () => ctx.fiber.dispose() }
+}

packages/host/runtime/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @deepseek-ai/dsh-host-runtime — host runtime assembly layer: the core spine
+ * composition (bootHost), the ApiProxy implementation (createApiProxy), and
+ * the one-step shell seam (startHost). Host-level configuration (defaults,
+ * persistenceRoot, future user profile) lives here.
+ */
+
+export { bootHost } from './boot.ts'
+export type { BootHostOptions, HostDefaults, HostHandle } from './boot.ts'
+export { createApiProxy } from './api-proxy.ts'
+export type { ApiProxyDefaults } from './api-proxy.ts'
+export { startHost } from './start.ts'
+export type { StartHostOptions, RunningHost } from './start.ts'
+export { mountWebPlugins, WEB_UI_PLUGINS } from './web-plugins.ts'

packages/host/runtime/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-runtime`.
+ * @module @deepseek-ai/dsh-host-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'host-runtime-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this assembly layer only composes plugins owned
+ * elsewhere; the event/data relations it touches (session events, agent
+ * lifecycle, wire frames) are asserted by their owning packages' companions.
+ */
+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/host/runtime/src/start.ts

@@ -0,0 +1,58 @@
+/**
+ * One-step host startup seam: boot core → assemble ApiProxy → assemble the
+ * fetch handler. The returned RunningHost is shell-agnostic — node:http
+ * (dsh web), in-process injection (dsh -p, tests), an IPC bridge (future
+ * Electron sidecar), and front-door plugin mounting (future dsh acp) all
+ * consume the same shape.
+ */
+
+import type { Context } from 'cordis'
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+import { bootHost } from './boot.ts'
+import type { BootHostOptions, HostDefaults } from './boot.ts'
+import { createApiProxy } from './api-proxy.ts'
+
+/** Options for startHost. */
+export interface StartHostOptions {
+  /**
+   * Passed through to bootHost verbatim (persistenceRoot required +
+   * provider?/model?). Future host-level knobs (profile, log sink — any
+   * output added to the assembly MUST be switchable off here) land as
+   * additive fields.
+   */
+  boot: BootHostOptions
+}
+
+/** Running host handle: the contract impl plus its fetch carrier and root ctx. */
+export interface RunningHost {
+  /** Contract implementation (direct calls for in-process consumers; the input of an IPC adapter). */
+  api: ApiProxy
+  /** WHATWG-fetch-shaped carrier (web shell bridges it to node:http; host-side endpoint of an IPC bridge). */
+  handler: { fetch: typeof fetch }
+  /** Host-level default routing (describe and every shell share this single source). */
+  defaults: HostDefaults
+  /**
+   * Root context — a formal seam, not an escape hatch: (1) the mount point for
+   * protocol front-door plugins (`dsh acp` = startHost() → ctx.plugin(uiAcp, config));
+   * (2) headless session-event subscription. Discipline: consuming clients must
+   * not bypass `api` through ctx; shells must not ctx.plugin to alter the
+   * assembly (mounting a front door is the shell's own shape, not an assembly change).
+   */
+  ctx: Context
+  /** Single shutdown exit (ctx.fiber.dispose()). Idempotent: a second call returns the same promise. */
+  dispose(): Promise<void>
+}
+
+/**
+ * Boot the host and assemble its consumption surfaces in one step.
+ * @param options - boot passthrough (see StartHostOptions).
+ * @returns the running host handle shared by every shell shape.
+ */
+export async function startHost(options: StartHostOptions): Promise<RunningHost> {
+  const host = await bootHost(options.boot)
+  const api = createApiProxy(host.ctx, host.defaults)
+  const handler = toFetchHandler(api)
+  let disposing: Promise<void> | undefined
+  return { api, handler, defaults: host.defaults, ctx: host.ctx, dispose: () => (disposing ??= host.dispose()) }
+}

packages/host/runtime/src/web-plugins.ts

@@ -0,0 +1,63 @@
+/**
+ * Web UI plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
+ * entry tree listing the eight UI plugin packages (the P-I config-source bar —
+ * a cordis.yml file form comes later; install/remove currently means editing
+ * this list and restarting). The web plugin registry discovers the entries by
+ * their package.json dshClient declarations; node halves are empty applies,
+ * so mounting them here costs nothing beyond Loader governance.
+ */
+import { createRequire } from 'node:module'
+import type { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+
+/** The eight UI plugin packages served to the browser (order = manifest order). */
+export const WEB_UI_PLUGINS = [
+  '@deepseek-ai/dsh-client-connection',
+  '@deepseek-ai/dsh-client-runtime',
+  '@deepseek-ai/dsh-client-ui-theme',
+  '@deepseek-ai/dsh-client-i18n',
+  '@deepseek-ai/dsh-client-ui-layout',
+  '@deepseek-ai/dsh-client-ui-sidebar',
+  '@deepseek-ai/dsh-client-ui-conversation',
+  '@deepseek-ai/dsh-client-ui-trajectory',
+] as const
+
+/** What the shell hands the web plugin registry (loader view + module resolution seam). */
+export interface MountedWebPlugins {
+  /** Entry enumeration surface of the mounted Loader (registry scan source). */
+  loader: { entries(): Iterable<{ options: { name: string }; fiber?: unknown; disabled: boolean }> }
+  /** Resolve a plugin package's package.json absolute path. */
+  resolvePkgJson: (name: string) => string
+}
+
+/**
+ * Mount the Loader (when absent) and create one in-memory entry per UI
+ * plugin, then wait for the tree to settle. A plugin whose import fails
+ * leaves its entry fiber-less — surfaced here as a loud throw listing the
+ * failures (misconfiguration must not silently drop a UI plugin).
+ * @param ctx - host root context (bootHost product).
+ * @returns the loader view and package.json resolver the registry consumes.
+ */
+export async function mountWebPlugins(ctx: Context): Promise<MountedWebPlugins> {
+  // The Loader resolves bare specifiers against ctx.baseUrl; without one the
+  // import silently fails and every entry stays fiber-less. This package
+  // depends on all eight UI plugins, so its own URL is the right anchor.
+  ctx.baseUrl ??= import.meta.url
+  if (ctx.get('loader') === undefined) await ctx.plugin(Loader)
+  const existing = new Set([...ctx.loader.entries()].map(entry => entry.options.name))
+  for (const name of WEB_UI_PLUGINS) {
+    if (!existing.has(name)) await ctx.loader.create({ name })
+  }
+  await ctx.loader.await()
+  const dead = [...ctx.loader.entries()]
+    .filter(entry => (WEB_UI_PLUGINS as readonly string[]).includes(entry.options.name))
+    .filter(entry => entry.fiber === undefined && !entry.disabled)
+  if (dead.length > 0) {
+    throw new Error(`web-plugins: UI plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
+  }
+  const require = createRequire(import.meta.url)
+  return {
+    loader: ctx.loader,
+    resolvePkgJson: name => require.resolve(`${name}/package.json`),
+  }
+}