Merge branch 'master' into feat/subagent-process

packages/README.md

@@ -15,10 +15,12 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
+| [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` tool | Product — stable surface |
 | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
 | [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface |
 | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool | Product — stable surface |
 | [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface |
+| [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, app packages, user-interaction seam, ask-user tool | Product — stable surface |

packages/code-runtime/README.md

@@ -1,6 +1,6 @@
 # code-runtime/ — code-execution capability family
 
-The code-execution capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's Code Mode, specified alongside the seam in the [Code Mode RFC](../../docs/rfc/proposed/feature/2026-06-15-code-mode.md). **Product** packages.
+The code-execution capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the generated TypeScript SDK); design in the [Code Mode RFC](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|

packages/code-runtime/code-runtime-worker/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-code-runtime-worker
 
-Worker-thread implementation of the [`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.md) seam: `WorkerCodeRuntime` runs each program in ONE fresh Node `worker_threads.Worker` — TypeScript in, type-stripped host-side, bindings bridged over the message port, `{ value, logs, error? }` out. **Containment, not a security boundary**: trust posture is bash-equivalent by design (the [Code Mode RFC](../../../docs/rfc/proposed/feature/2026-06-15-code-mode.md) § Trust posture), with containment bash does not have — separate isolate, empty environment, heap cap, hard termination.
+Worker-thread implementation of the [`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.md) seam: `WorkerCodeRuntime` runs each program in ONE fresh Node `worker_threads.Worker` — TypeScript in, type-stripped host-side, bindings bridged over the message port, `{ value, logs, error? }` out. **Containment, not a security boundary**: trust posture is bash-equivalent by design (the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) § Trust posture), with containment bash does not have — separate isolate, empty environment, heap cap, hard termination.
 
 ## Config
 

packages/code-runtime/code-runtime-worker/package.json

@@ -11,6 +11,10 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./worker": {
+      "types": "./lib/types/worker.d.ts",
+      "default": "./lib/worker.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },

packages/code-runtime/code-runtime/README.md

@@ -2,7 +2,7 @@
 
 The **code-execution seam**: an abstract `CodeRuntime` service (`ctx.codeRuntime`) defining WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
 
-This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode RFC](../../../docs/rfc/proposed/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer.
+This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer.
 
 ## Service API (`ctx.codeRuntime`)
 

packages/code-runtime/code-runtime/src/index.ts

@@ -7,7 +7,7 @@
  * substrate (worker thread, separate process, container) and by source
  * language, both declared as readonly descriptors. The design and its
  * consumer (the tool registry's Code Mode) are specified in the Code Mode RFC
- * (docs/rfc/proposed/feature/2026-06-15-code-mode.md).
+ * (docs/rfc/implemented/feature/2026-06-15-code-mode.md).
  *
  * The split mirrors the bash seam (`BashExecutor`): the runtime knows nothing
  * about tools or sessions — it is handed named async functions and a program,

packages/compact/compact-basic/README.md

@@ -8,7 +8,7 @@ This is the implementation tier of the compaction capability — see the [interf
 
 The abstract contract states only WHAT compaction does; this backend owns every HOW decision:
 
-- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length).
+- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). The pressure gate estimates the NEXT request via `estimatePressure()`: the session prefix (the `agent/session-prefix` product — composed by the loop BEFORE the pre-step seam and handed through it, so the gate counts the prefix this instance will actually send in front of the history, never a stale logged one) + the derived history + the system prompt.
 - **Retention policy** — `compactIfNeeded()` walks the surface nodes tail→head summing per-node token estimates, and retains the smallest tail-run of WHOLE units (a closed step, or a single no-step node such as a pre-step `user/message` or inter-step `steering/message`) whose total reaches `retainTokens`; everything older is compacted. Retention is **turn-agnostic** — turn boundaries play no role, so a single runaway turn that alone exceeds the window compacts its OWN early closed steps rather than being retained verbatim (the failure mode that motivated dropping turn-protection: a tool-heavy turn must stay compactable or the harness dies exactly when compaction is needed). The only structural guard is **tool-pairing balance**: the compacted region's edges are balanced cuts on the surface (no unanswered tool-call crosses either edge), so it never splits a step's `assistant/message` tool-calls from their `tool/result`s. When the only compactable content left is an un-splittable open tail step, it declines (returns `null`) and retries once an older step closes. **Single-unit overflow is out of scope, by design**: if one retained unit (a single closed step, or a large pasted `user/message`) ALONE exceeds the budget, compaction cannot help and the call may go out over-budget — bounding an individual unit's size is a separate concern. `compactRegion()` enforces tool-pairing balance strictly, throwing on a boundary that would split a step. `dsh-session` exports `isToolPairingBalanced` for the check.
 - **Dynamic convergence** — no static summary-length config pretends to bound what the model will write. If framing/estimator/system overhead leaves the compacted surface above threshold, `compactIfNeeded()` re-compacts the head checkpoint up to `compactionRetries` extra times; if it still cannot get below threshold, it throws. A summary whose estimated stored size is not smaller than the shadowed content fails closed before it mutates the surface.
 - **Summarization** — `summarize()`: a `GenerateOptions` request assembled via `BlockAssembler` with a fixed system prompt that asks for a structured checkpoint (Primary Request and Intent · Key Technical Concepts · Files and Code · Errors and Fixes · Pending Tasks · Current Work · Next Step · Critical Context), every section mandatory, exact paths/commands/identifiers preserved. The request is a direct one-shot `ctx.llm.stream()` call — NOT a loop step, so it does not run `agent/request` (that seam shapes the loop's conversation requests); the model comes from `summarizationModel` falling back to the agent's own, and per-call routing happens at `llm/stream` like any other direct call. `maxTokens` is the provider-side generation cap; only text blocks from the model's reply are kept before the checkpoint is stored (reasoning is dropped so private chain-of-thought never leaks into the durable summary, and a stray `tool-call` is dropped so the synthesized `user/message` summary cannot land an orphaned call with no matching `tool-result`). The compacted region is flattened to a plain-text transcript first: text and reasoning contribute their text, and every non-text block (tool-call, tool-result, plugin-added types) contributes a type-tagged placeholder (`[tool-call: name(args)]`, `[tool-result: …]`, …) so the summarizer is told what existed rather than silently dropping it.

packages/compact/compact-basic/src/index.ts

@@ -30,7 +30,7 @@
  */
 
 import { Context } from 'cordis'
-import { CompactService } from '@deepseek-ai/dsh-compact'
+import { CompactService, renderTranscript } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
 import { BlockAssembler } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, FinishReason, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
@@ -183,11 +183,11 @@ export class BasicCompactService extends CompactService {
       // log-only `compact/*` records and the replacement node cleanly outside a
       // step, so a crash mid-compaction leaves an inert orphan the turn-repair
       // closes — never a half-open step.
-      ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, signal: AbortSignal) => {
+      ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal) => {
         try {
-          const result = await this.compactIfNeeded(agent, fullSystemPrompt, signal)
+          const result = await this.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
           if (result) {
-            const after = this.estimateTokens(agent.session.deriveMessages(), fullSystemPrompt)
+            const after = this.estimatePressure(agent.session, fullSystemPrompt, sessionPrefix)
             ctx.logger.info(
               `compaction: shadowed ${result.shadowedSeqs.length} surface nodes ` +
               `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, ` +
@@ -359,11 +359,23 @@ export class BasicCompactService extends CompactService {
   // ---- Core API (implements the abstract contract) ----
 
   /**
-   * The sole token-pressure gate: estimate the current surface-derived history,
-   * and if it exceeds the threshold (`contextWindow * thresholdRatio`), compact
+   * The sole token-pressure gate: estimate the NEXT request's pressure — the
+   * session prefix + the surface-derived history + the system prompt
+   * ({@link estimatePressure}) — and if it exceeds the threshold
+   * (`contextWindow * thresholdRatio`), compact
    * the oldest surface nodes outside the `retainTokens` budget. The auto-
    * compaction listener delegates here rather than pre-checking, so this is the
-   * only place the decision lives.
+   * only place the decision lives. The prefix counts because every request
+   * carries it in front of the history (`EpochHeader.messagePrefix`) even
+   * though it is not derived history — omitting it would under-estimate by
+   * exactly the prefix and let a deployment at the window edge skip
+   * compaction, then ship an over-window request. The loop composes the
+   * prefix BEFORE the pre-step seam and hands it through, so the gate sees
+   * this instance's actual prefix (never a previous instance's logged one —
+   * a resumed/forked instance whose contributor grew is gated on the grown
+   * value from its very first step). Compaction itself can only
+   * shrink HISTORY: a prefix that alone approaches the window is a
+   * configuration error no compactor fixes.
    *
    * Retention is a UNIFORM tail→head walk over the whole surface — turn
    * boundaries play NO role. Walking node-by-node from the tail and summing
@@ -387,13 +399,14 @@ export class BasicCompactService extends CompactService {
   override async compactIfNeeded(
     agent: Agent,
     fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
     signal: AbortSignal,
   ): Promise<CompactionResult | null> {
     const session = agent.session
     const threshold = Math.floor(this.config.contextWindow * this.config.thresholdRatio)
     let result: CompactionResult | null = null
     for (let attempt = 0; attempt <= this.config.compactionRetries; attempt++) {
-      const totalTokens = this.estimateTokens(session.deriveMessages(), fullSystemPrompt)
+      const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
       if (totalTokens < threshold) return result
 
       const range = this._compactableRange(session)
@@ -407,7 +420,7 @@ export class BasicCompactService extends CompactService {
       result = await this.compactRegion(session, range.start, range.end, agent, signal)
     }
 
-    const totalTokens = this.estimateTokens(session.deriveMessages(), fullSystemPrompt)
+    const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
     if (totalTokens < threshold) return result
 
     throw new Error(
@@ -416,6 +429,20 @@ export class BasicCompactService extends CompactService {
     )
   }
 
+  /**
+   * Estimated token pressure of the NEXT request: the session prefix
+   * (`EpochHeader.messagePrefix` — request-only messages the loop sends in
+   * front of the derived history, composed before the pre-step seam and
+   * handed to the gate), the derived history, and the system prompt.
+   * @param session - the session whose next request is being estimated.
+   * @param fullSystemPrompt - the assembled system prompt (counts toward pressure).
+   * @param sessionPrefix - the instance's composed session prefix (counts toward pressure).
+   * @returns the estimated token total the next request will carry.
+   */
+  estimatePressure(session: Session, fullSystemPrompt: string, sessionPrefix: readonly Message[]): number {
+    return this.estimateTokens([...sessionPrefix, ...session.deriveMessages()], fullSystemPrompt)
+  }
+
   override async compactRegion(
     session: Session,
     start: number,
@@ -483,7 +510,7 @@ export class BasicCompactService extends CompactService {
 
     try {
       // --- Extract text and summarize ---
-      const text = this._extractText(session, shadowedSeqs)
+      const text = renderTranscript(session.events, shadowedSeqs)
       const { summary, model, maxTokens } = await this.summarize(text, agent, signal)
 
       // Estimate token count of the shadowed content for provenance.
@@ -679,101 +706,6 @@ export class BasicCompactService extends CompactService {
     }
     return null
   }
-
-  /**
-   * Extract plain-text conversation from a set of surface node seqs, for
-   * feeding into the summarization model. Walks the seqs in the order given
-   * (surface order, as `compactRegion` slices the surface-node list) so the
-   * summary follows the conversation as the model sees it — which, after a
-   * `replace`, is NOT ascending log-seq order (a high-seq summary node heads the
-   * surface before older retained lower-seq nodes).
-   */
-  private _extractText(session: Session, seqs: number[]): string {
-    const lines: string[] = []
-
-    // Walk seqs in the order given (surface order, as compactRegion slices the
-    // surface-node list) — NOT ascending log-seq order. After a replace the
-    // summary node carries a fresh high seq while sitting at the head of the
-    // surface before older retained lower-seq nodes, so a log-order scan would
-    // feed the transcript out of order and break the checkpoint-merge prompt.
-    for (const seq of seqs) {
-      const event = session.events[seq]
-      /* v8 ignore next -- seq is a surface-node seq, always a valid log index by construction */
-      if (!event) continue
-
-      switch (event.type) {
-        case 'user/message': {
-          const text = this._blocksToText(event.data.content)
-          if (text) lines.push(`User: ${text}`)
-          break
-        }
-        case 'assistant/message': {
-          const text = this._blocksToText(event.data.content)
-          if (text) lines.push(`Assistant: ${text}`)
-          break
-        }
-        case 'tool/result': {
-          const text = this._blocksToText(event.data.content)
-          const label = event.data.isError ? 'Tool error' : 'Tool result'
-          if (text) lines.push(`${label} (call ${event.data.callId}): ${text}`)
-          break
-        }
-        case 'context/message': {
-          const text = this._blocksToText(event.data.content)
-          if (text) lines.push(`[Context: ${text}]`)
-          break
-        }
-        case 'steering/message': {
-          const text = this._blocksToText(event.data.content)
-          if (text) lines.push(`[Steering: ${text}]`)
-          break
-        }
-        // SessionEventMap is merge-extensible — unknown types are
-        // non-message events that carry no extractable text.
-        /* v8 ignore next 2 -- seqs only name surface nodes, always one of the 5 handled SurfaceEventTypes; unreachable */
-        default:
-          break
-      }
-    }
-
-    return lines.join('\n\n')
-  }
-
-  /**
-   * Render content blocks to a single plain-text string for the summarization
-   * prompt. Text and reasoning contribute their text; every other block type
-   * contributes a type-tagged placeholder (`[tool-call: name(args)]`,
-   * `[tool-result: …]`, …) so the summarizer is told what non-text content
-   * existed in the region rather than silently losing it. Blocks join with
-   * newlines; empty-text blocks contribute nothing.
-   */
-  private _blocksToText(blocks: readonly ContentBlock[]): string {
-    const parts: string[] = []
-    for (const block of blocks) {
-      switch (block.type) {
-        case 'text':
-          if (block.text) parts.push(block.text)
-          break
-        case 'reasoning':
-          if (block.text) parts.push(`[reasoning: ${block.text}]`)
-          break
-        case 'tool-call':
-          parts.push(`[tool-call: ${block.name}(${block.arguments})]`)
-          break
-        case 'tool-result': {
-          const inner = this._blocksToText(block.content)
-          parts.push(inner ? `[tool-result: ${inner}]` : '[tool-result]')
-          break
-        }
-        // ContentBlockMap is merge-extensible — render an unknown block as a
-        // bare type-tagged placeholder so a plugin-added block type is still
-        // signalled to the summarizer rather than dropped.
-        default:
-          parts.push(`[${(block as ContentBlock).type}]`)
-      }
-    }
-    return parts.join('\n')
-  }
 }
 
 export default BasicCompactService

packages/compact/compact-basic/tests/compact-basic.spec.ts

@@ -557,6 +557,24 @@ describe('BasicCompactService.compactIfNeeded', () => {
     expect(result!.shadowedSeqs.length).toBeGreaterThan(0)
   })
 
+  it('counts the session prefix toward pressure (every request carries it in front of the history)', async () => {
+    const svc = createTestService({ contextWindow: 200, thresholdRatio: 0.5, retainTokens: 10 })
+    const session = multiTurnSession(3, 1) // 6 derived messages ≈ 84 estimated tokens — under the 100 threshold alone
+    expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull()
+
+    // The loop composes the agent/session-prefix product before the pre-step
+    // seam and hands it to the gate; it rides every request, so pressure must
+    // include it — the same history now crosses the threshold.
+    const sessionPrefix: Message[] = [
+      { role: 'user', content: [{ type: 'text', text: `opener one.${LONG_FIXTURE_TEXT}` }] },
+      { role: 'user', content: [{ type: 'text', text: `opener two.${LONG_FIXTURE_TEXT}` }] },
+    ]
+    const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL, sessionPrefix)
+    expect(result).not.toBeNull()
+    // The prefix itself is NOT history: compaction shadowed surface nodes only.
+    expect(sessionPrefix).toHaveLength(2)
+  })
+
   it('returns the first compaction result when a zero-retry pass converges after the loop', async () => {
     // With compactionRetries=0 there is no next-loop threshold check after the
     // first mutation, so the success path is the post-loop `return result`.
@@ -982,8 +1000,9 @@ function compactIfNeeded(
   fullSystemPrompt: string,
   model: string,
   signal: AbortSignal,
+  sessionPrefix: readonly Message[] = [],
 ) {
-  return svc.compactIfNeeded(stubAgent(session, model), fullSystemPrompt, signal)
+  return svc.compactIfNeeded(stubAgent(session, model), fullSystemPrompt, sessionPrefix, signal)
 }
 
 function compactRegion(
@@ -1151,7 +1170,7 @@ describe('BasicCompactService.summarize (real ctx.llm.stream)', () => {
 describe('BasicCompactService auto-compaction (agent/pre-step listener)', () => {
   /** Fire the agent/pre-step serial checkpoint as the loop does. */
   function firePreStep(ctx: Context, agent: Agent, step: number, fullSystemPrompt: string): Promise<unknown> {
-    return ctx.serial('agent/pre-step', agent, 1, step, fullSystemPrompt, SIGNAL)
+    return ctx.serial('agent/pre-step', agent, 1, step, fullSystemPrompt, [], SIGNAL)
   }
 
   it('compacts (mutating the surface) when over threshold', async () => {
@@ -1253,7 +1272,7 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () =>
     const session = multiTurnSession(5, 1)
     const agent = stubAgent(session, 'agent-model')
 
-    await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL)
 
     expect(adapter.lastOptions?.model).toBe('routed-model')
     expect(session.events.some(e => e.type === 'compact/summary')).toBe(true)
@@ -1278,7 +1297,7 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () =>
   })
 })
 
-describe('BasicCompactService._extractText branches', () => {
+describe('BasicCompactService transcript rendering (delegated to dsh-compact)', () => {
   it('renders reasoning, context, and steering messages', async () => {
     const svc = createTestService()
     const s = new Session(SessionId('rich'))
@@ -1392,7 +1411,7 @@ describe('BasicCompactService edge cases', () => {
     const session = multiTurnSession(4, 1)
     const agent = stubAgent(session, 'test-model')
 
-    await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL)
     expect(session.events.some(e => e.type === 'compact/summary')).toBe(true)
     // The surface was mutated; the head message is the framed summary checkpoint.
     expect(session.deriveMessages()[0]!.content).toContainEqual({ type: 'text', text: 'SUMMARY' })
@@ -1472,7 +1491,7 @@ describe('BasicCompactService edge cases', () => {
     const agent = stubAgent(session, 'test-model')
     const before = session.surface.nodes.length
 
-    await ctx.serial('agent/pre-step', agent, 1, 1, '', SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL)
     // The failure was swallowed; the surface is untouched and a warning logged.
     expect(session.surface.nodes.length).toBe(before)
     expect(session.events.some(e => e.type === 'compact/summary')).toBe(false)
@@ -1489,7 +1508,7 @@ describe('BasicCompactService edge cases', () => {
     const agent = stubAgent(session, 'test-model')
     const bigSystem = 'x'.repeat(900) // ceil(900/4)=225 > threshold 200
 
-    await ctx.serial('agent/pre-step', agent, 1, 1, bigSystem, SIGNAL)
+    await ctx.serial('agent/pre-step', agent, 1, 1, bigSystem, [], SIGNAL)
     expect(session.events.some(e => e.type === 'compact/start')).toBe(false)
     expect(svc.summarizeCalls.length).toBe(0)
   })

packages/compact/compact/README.md

@@ -6,7 +6,7 @@ This package is the interface tier of the compaction capability, split so each c
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` |
+| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + the shared transcript renderer (`renderTranscript`/`renderContentBlocks`) |
 | `@deepseek-ai/dsh-compact-basic` (deferred) | a backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization |
 | `@deepseek-ai/dsh-tool-compact` (deferred) | the model-facing `/compact` tool over `ctx.compact` |
 
@@ -18,7 +18,7 @@ Both methods are **abstract** — the backend owns the entire strategy (token es
 
 | Member | Semantics |
 |---|---|
-| `compactIfNeeded(agent, fullSystemPrompt, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
+| `compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, composed `sessionPrefix` (request-only messages every request carries but the derived history omits — the pressure estimate must count them), and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
 | `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
 
 `compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The session being compacted comes from the agent context; the turn that the `compact/*` events belong to is recoverable from the log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value.

packages/compact/compact/src/index.ts

@@ -22,10 +22,12 @@
  */
 
 import { Context, Service } from 'cordis'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import type { Session } from '@deepseek-ai/dsh-session'
 import type { CompactionResult } from './types.ts'
 
 export type { CompactionResult } from './types.ts'
+export { renderContentBlocks, renderTranscript } from './render.ts'
 
 /** Minimal agent context compaction needs without depending on the agent package. */
 export interface CompactAgentContext {
@@ -68,16 +70,20 @@ export abstract class CompactService extends Service {
   /**
    * Check token pressure and compact if the conversation is too large.
    *
-   * Estimates the current surface-derived history size (including the system
-   * prompt), and if it exceeds the backend's threshold, compacts an older range
+   * Estimates the NEXT request's size — the session prefix, the
+   * surface-derived history, and the system prompt — and if it exceeds the
+   * backend's threshold, compacts an older range
    * via {@link compactRegion}, keeping recent context intact. Returns `null`
    * when no compaction is needed.
    *
    * Scope and guarantees a backend MUST honor:
-   * - **Surface-derived history only.** The decision is made against the history
-   *   derived from the session surface — the only thing compaction can act on.
-   *   Non-surface context injected downstream (into the request `messages` by a
-   *   later listener) is out of this accounting by construction.
+   * - **Compaction acts on surface-derived history only**, but the ESTIMATE
+   *   counts everything the request carries: the loop composes the session
+   *   prefix before the pre-step seam fires and hands it here, so the gate
+   *   sees the prefix this instance will actually send (`EpochHeader.messagePrefix`
+   *   — request-only, never derived history). Non-surface context injected
+   *   downstream (into the request `messages` by a later listener) is out of
+   *   this accounting by construction.
    * - **Head-anchored, best-effort.** Auto-compaction consolidates from the
    *   surface HEAD up to a balanced tool-pairing cutoff, so a prior head
    *   checkpoint is
@@ -88,10 +94,14 @@ export abstract class CompactService extends Service {
    * - **Single-unit overflow is out of scope.** If a single retained unit (one
    *   closed step, or a large free node such as a pasted `user/message`) ALONE
    *   exceeds the budget, compaction cannot help and the call may go out
-   *   over-budget. Bounding an individual unit's size is a separate concern.
+   *   over-budget. Bounding an individual unit's size is a separate concern —
+   *   as is a session prefix that alone approaches the window (a
+   *   configuration error no compactor fixes: compaction cannot shrink the
+   *   prefix).
    *
    * @param agent - agent context owning the session surface and model options.
    * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
+   * @param sessionPrefix - the instance's composed session prefix, counted toward the estimate.
    * @param signal - cancellation signal. A backend summarizing via
    *   `ctx.llm.stream()` MUST forward this into the call's `GenerateOptions.signal`
    *   so an abort/dispose tears down the in-flight summarization rather than
@@ -101,6 +111,7 @@ export abstract class CompactService extends Service {
   abstract compactIfNeeded(
     agent: CompactAgentContext,
     fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
     signal: AbortSignal,
   ): Promise<CompactionResult | null>
 

packages/compact/compact/src/render.ts

@@ -0,0 +1,118 @@
+/**
+ * Plain-text transcript rendering over session events: the shared projection
+ * used wherever a compaction-class consumer needs "what a model once saw" as
+ * readable text — a summarizer's input, or a recall tool's output.
+ *
+ * Extracted from the basic backend's private helpers so the summarize path and
+ * the recall read path render one span identically (two renderers would drift,
+ * and a recall reader would then see a different transcript than the one the
+ * summary was written from). Both functions are pure over their arguments: no
+ * session access beyond the provided events, no clock, no randomness — a
+ * rendered span is a pure function of the log, so replay reproduces it
+ * byte-identically.
+ *
+ * @module @deepseek-ai/dsh-compact/render
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/**
+ * Render content blocks to a single plain-text string. Text and reasoning
+ * contribute their text (reasoning wrapped as `[reasoning: …]`); every other
+ * block type contributes a type-tagged placeholder (`[tool-call: name(args)]`,
+ * `[tool-result: …]`, …) so the reader is told what non-text content existed
+ * rather than silently losing it. A `tool-result` block recurses into its
+ * nested content (`[tool-result: <inner rendering>]`), falling back to a bare
+ * `[tool-result]` when the nested content renders to nothing. Blocks join
+ * with newlines; empty-text blocks contribute nothing.
+ *
+ * @param blocks - the content blocks to render.
+ * @returns the newline-joined plain-text rendering; empty string when nothing renders.
+ */
+export function renderContentBlocks(blocks: readonly ContentBlock[]): string {
+  const parts: string[] = []
+  for (const block of blocks) {
+    switch (block.type) {
+      case 'text':
+        if (block.text) parts.push(block.text)
+        break
+      case 'reasoning':
+        if (block.text) parts.push(`[reasoning: ${block.text}]`)
+        break
+      case 'tool-call':
+        parts.push(`[tool-call: ${block.name}(${block.arguments})]`)
+        break
+      case 'tool-result': {
+        const inner = renderContentBlocks(block.content)
+        parts.push(inner ? `[tool-result: ${inner}]` : '[tool-result]')
+        break
+      }
+      // ContentBlockMap is merge-extensible — render an unknown block as a
+      // bare type-tagged placeholder so a plugin-added block type is still
+      // signalled to the reader rather than dropped.
+      default:
+        parts.push(`[${(block as ContentBlock).type}]`)
+    }
+  }
+  return parts.join('\n')
+}
+
+/**
+ * Render a set of surface-node seqs as a `User:`/`Assistant:`/`Tool result:`
+ * transcript. Walks `seqs` in the order given — callers pass surface order
+ * (e.g. a `compactRegion` slice of the surface-node list), which after a
+ * `replace` is NOT ascending log-seq order (a high-seq summary node can sit at
+ * the head of the surface before older retained lower-seq nodes); a log-order
+ * scan would render the transcript out of order.
+ *
+ * Only the five surface (message-producing) event types render; a seq naming
+ * any other event type contributes nothing. `SessionEventMap` is
+ * merge-extensible, so unknown types are simply non-message events with no
+ * renderable text.
+ *
+ * @param events - the session log the seqs index into (`session.events`).
+ * @param seqs - the surface-node seqs to render, in surface order.
+ * @returns the transcript, entries joined by blank lines; empty string when nothing renders.
+ */
+export function renderTranscript(events: readonly SessionEvent[], seqs: readonly number[]): string {
+  const lines: string[] = []
+
+  for (const seq of seqs) {
+    const event = events[seq]
+    if (!event) continue
+
+    switch (event.type) {
+      case 'user/message': {
+        const text = renderContentBlocks(event.data.content)
+        if (text) lines.push(`User: ${text}`)
+        break
+      }
+      case 'assistant/message': {
+        const text = renderContentBlocks(event.data.content)
+        if (text) lines.push(`Assistant: ${text}`)
+        break
+      }
+      case 'tool/result': {
+        const text = renderContentBlocks(event.data.content)
+        const label = event.data.isError ? 'Tool error' : 'Tool result'
+        if (text) lines.push(`${label} (call ${event.data.callId}): ${text}`)
+        break
+      }
+      case 'context/message': {
+        const text = renderContentBlocks(event.data.content)
+        if (text) lines.push(`[Context: ${text}]`)
+        break
+      }
+      case 'steering/message': {
+        const text = renderContentBlocks(event.data.content)
+        if (text) lines.push(`[Steering: ${text}]`)
+        break
+      }
+      default:
+        break
+    }
+  }
+
+  return lines.join('\n\n')
+}

packages/compact/compact/tests/compact.spec.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CompactService } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { CompactAgentContext } from '@deepseek-ai/dsh-compact'
 
@@ -18,6 +19,7 @@ class StubCompactService extends CompactService {
   override async compactIfNeeded(
     _agent: CompactAgentContext,
     _fullSystemPrompt: string,
+    _sessionPrefix: readonly Message[],
     signal: AbortSignal,
   ): Promise<CompactionResult | null> {
     this.lastSignal = signal
@@ -78,7 +80,7 @@ describe('CompactService seam', () => {
     const ctx = new Context()
     const svc = new StubCompactService(ctx)
     const session = new Session(SessionId('s'))
-    expect(await svc.compactIfNeeded(stubAgent(session), '', new AbortController().signal)).toBeNull()
+    expect(await svc.compactIfNeeded(stubAgent(session), '', [], new AbortController().signal)).toBeNull()
   })
 
   it('compact/* events merge into SessionEventMap and are log-only', async () => {
@@ -107,7 +109,7 @@ describe('CompactService seam', () => {
     await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'), controller.signal)
     expect(svc.lastSignal).toBe(controller.signal)
 
-    await svc.compactIfNeeded(stubAgent(session), '', controller.signal)
+    await svc.compactIfNeeded(stubAgent(session), '', [], controller.signal)
     expect(svc.lastSignal).toBe(controller.signal)
   })
 })

packages/compact/compact/tests/render.spec.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest'
+import { renderContentBlocks, renderTranscript } from '@deepseek-ai/dsh-compact'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { CallId } from '@deepseek-ai/dsh-llm'
+
+function session(): Session {
+  return new Session(SessionId('render-spec'))
+}
+
+describe('renderContentBlocks', () => {
+  it('renders text blocks verbatim and skips empty ones', () => {
+    expect(renderContentBlocks([
+      { type: 'text', text: 'hello' },
+      { type: 'text', text: '' },
+      { type: 'text', text: 'world' },
+    ])).toBe('hello\nworld')
+  })
+
+  it('wraps reasoning, skipping empty reasoning', () => {
+    expect(renderContentBlocks([
+      { type: 'reasoning', text: 'think' },
+      { type: 'reasoning', text: '' },
+    ])).toBe('[reasoning: think]')
+  })
+
+  it('renders tool-call as a name(args) placeholder', () => {
+    expect(renderContentBlocks([
+      { type: 'tool-call', id: CallId('c1'), name: 'read', arguments: '{"filePath":"a"}' },
+    ])).toBe('[tool-call: read({"filePath":"a"})]')
+  })
+
+  it('renders tool-result with nested content, and bare when empty', () => {
+    expect(renderContentBlocks([
+      { type: 'tool-result', toolCallId: CallId('c1'), content: [{ type: 'text', text: 'ok' }] },
+      { type: 'tool-result', toolCallId: CallId('c2'), content: [] },
+    ])).toBe('[tool-result: ok]\n[tool-result]')
+  })
+
+  it('renders an unknown (merge-extended) block type as a bare type tag', () => {
+    const unknown = { type: 'image', data: 'zzz' } as unknown as ContentBlock
+    expect(renderContentBlocks([unknown])).toBe('[image]')
+  })
+
+  it('returns the empty string for no blocks', () => {
+    expect(renderContentBlocks([])).toBe('')
+  })
+})
+
+describe('renderTranscript', () => {
+  it('renders each surface event type with its label, in the seq order given', () => {
+    const s = session()
+    const user = s.append('user/message', {
+      content: [{ type: 'text', text: 'fix the bug' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const assistant = s.append('assistant/message', {
+      turn: 0, step: 0,
+      content: [{ type: 'text', text: 'looking' }],
+    }, { surfaceOp: 'append' })
+    const result = s.append('tool/result', {
+      turn: 0, step: 0, callId: CallId('c1'),
+      content: [{ type: 'text', text: 'exit 0' }],
+      isError: false,
+    }, { surfaceOp: 'append' })
+    const context = s.append('context/message', {
+      content: [{ type: 'text', text: 'file changed' }],
+      source: { kind: 'plugin', plugin: 'fs' },
+    }, { surfaceOp: 'append' })
+    const steering = s.append('steering/message', {
+      turn: 0,
+      content: [{ type: 'text', text: 'stop that' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+
+    expect(renderTranscript(s.events, [user.seq, assistant.seq, result.seq, context.seq, steering.seq])).toBe([
+      'User: fix the bug',
+      'Assistant: looking',
+      'Tool result (call c1): exit 0',
+      '[Context: file changed]',
+      '[Steering: stop that]',
+    ].join('\n\n'))
+  })
+
+  it('labels an error tool result "Tool error"', () => {
+    const s = session()
+    const result = s.append('tool/result', {
+      turn: 0, step: 0, callId: CallId('c9'),
+      content: [{ type: 'text', text: 'boom' }],
+      isError: true,
+    }, { surfaceOp: 'append' })
+    expect(renderTranscript(s.events, [result.seq])).toBe('Tool error (call c9): boom')
+  })
+
+  it('renders NON-log-order seqs in the order given (surface order after a replace)', () => {
+    const s = session()
+    const first = s.append('user/message', {
+      content: [{ type: 'text', text: 'first' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const second = s.append('user/message', {
+      content: [{ type: 'text', text: 'second' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    expect(renderTranscript(s.events, [second.seq, first.seq])).toBe('User: second\n\nUser: first')
+  })
+
+  it('skips events that render to nothing, non-message events, and seqs with no event', () => {
+    const s = session()
+    const empty = s.append('user/message', {
+      content: [{ type: 'text', text: '' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const emptyAssistant = s.append('assistant/message', {
+      turn: 0, step: 0,
+      content: [{ type: 'text', text: '' }],
+    }, { surfaceOp: 'append' })
+    const emptyResult = s.append('tool/result', {
+      turn: 0, step: 0, callId: CallId('c3'),
+      content: [{ type: 'text', text: '' }],
+      isError: false,
+    }, { surfaceOp: 'append' })
+    const emptyContext = s.append('context/message', {
+      content: [{ type: 'text', text: '' }],
+      source: { kind: 'plugin', plugin: 'fs' },
+    }, { surfaceOp: 'append' })
+    const emptySteering = s.append('steering/message', {
+      turn: 0,
+      content: [{ type: 'text', text: '' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    // A log-only (non-surface) event type: contributes nothing to a transcript.
+    const lock = s.append('compact/start', { turn: 0 })
+    expect(renderTranscript(s.events, [
+      empty.seq, emptyAssistant.seq, emptyResult.seq, emptyContext.seq, emptySteering.seq, lock.seq, 9999,
+    ])).toBe('')
+  })
+})

packages/cordis/README.md

@@ -0,0 +1,7 @@
+# packages/cordis — the self-referential runtime toolset
+
+Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again. Design home: [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`tool-cordis/`](tool-cordis/README.md) | The `cordis_inspect` / `cordis_mount` / `cordis_unmount` tools: read the runtime, evaluate model-written plugin code in a `node:vm` sandbox, and manage the dynamic mounts under one group fiber | registers on `ctx.tools` |

packages/cordis/tool-cordis/README.md

@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-tool-cordis
+
+The self-referential cordis toolset: three model-facing tools over the live runtime the agent runs inside. Design home — sandbox semantics, mount lifecycle, cross-mount composition, the generated API catalog, standing decisions: [the toolset RFC](../../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+
+## What it does
+
+- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references.
+- `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-<n>`.
+- `cordis_unmount` — disposes one mount by id, returning only after quiescence.
+
+Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-catalog.md).
+
+## Trust stance
+
+The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. These traps steer honest code onto the cordis services; they do not contain a mount that goes looking — the host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are reachable functions, so mount code can reach the host realm and Node through one of them, which is fine because `ctx` is fully privileged anyway. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `vmTimeoutMs` | `5000` | Bound on the SYNCHRONOUS portion of mount-code evaluation; an async body escapes it |
+
+## The generated API catalog
+
+`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time.
+
+## Rendering
+
+All three tools render `generic` cards (`read` / `execute` / `delete`); `cordis_mount` carries the mount code as `rawInput`. Presenters are pure functions of the args; results keep the default text rendering.
+
+## Export shape
+
+Namespace plugin: named exports `name` / `inject` / `Config` / `apply`, no default export ([docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)).

packages/cordis/tool-cordis/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-tool-cordis",
+  "description": "Self-referential cordis toolset: inspect the live runtime, mount and dispose model-written plugins",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "cordis": "^4.0.0-rc.6",
+    "@cordisjs/plugin-timer": "workspace:^"
+  }
+}

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -0,0 +1,926 @@
+/**
+ * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run
+ * `pnpm run gen-cordis-api` to regenerate (freshness-gated by
+ * `pnpm run verify-cordis-api` in doc-sync).
+ *
+ * The machine-readable cordis API catalog `cordis_inspect` serves to the
+ * model: harness services (summary + public method signatures), harness
+ * events (mode + signature), and the inherited `ctx` surface. Produced by
+ * the same AST walk as docs/cordis-catalog, so this data and the rendered
+ * docs cannot diverge.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/api-catalog
+ */
+
+/** One harness `ctx.<key>` service: its one-line summary and public method signatures. */
+export interface ServiceApiEntry {
+  /** The `ctx.<key>` name, e.g. `tools`. */
+  key: string
+  /** First sentence of the service class JSDoc. */
+  summary: string
+  /** Public method signatures, bodies stripped, in source order. */
+  methods: readonly string[]
+}
+
+/** One harness event: its dispatch mode, exact signature, and one-line summary. */
+export interface EventApiEntry {
+  /** The scoped event name, e.g. `agent/status`. */
+  name: string
+  /** The dispatch mode from the declaration's `@mode` tag. */
+  mode: string
+  /** The exact listener signature, whitespace-normalized. */
+  signature: string
+  /** First sentence of the event JSDoc. */
+  summary: string
+}
+
+/** One inherited (cordis core + loader/hmr/timer) `ctx` member group with its summary. */
+export interface InheritedApiEntry {
+  /** The `ctx` member name(s), e.g. `ctx.on / ctx.once`. */
+  name: string
+  /** One-line summary of what the member does. */
+  summary: string
+}
+
+/** One named type shape the service signatures reference. */
+export interface TypeApiEntry {
+  /** The exported type/interface name, e.g. `BashRunResult`. */
+  name: string
+  /** The full declaration text, comments stripped. */
+  declaration: string
+}
+
+/** Every harness `ctx.<key>` service, sorted by key. */
+export const SERVICE_API: readonly ServiceApiEntry[] = [
+  {
+    key: 'agentLoop',
+    summary: 'The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`.',
+    methods: [
+      'create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent',
+      'createAgent(options: CreateAgentOptions): AgentHandle',
+      'async resume(options: ResumeAgentOptions): Promise<AgentHandle>',
+    ],
+  },
+  {
+    key: 'agents',
+    summary: 'Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package.',
+    methods: [
+      'setFactory(factory: AgentFactory): () => void',
+      'create(options: CreateAgentOptions): AgentHandle',
+      'async resume(options: ResumeAgentOptions): Promise<AgentHandle>',
+      'register(agent: Agent): () => void',
+      'get(id: AgentId): Agent | undefined',
+      'list(): Agent[]',
+    ],
+  },
+  {
+    key: 'bash',
+    summary: 'Abstract bash execution service.',
+    methods: [
+      'abstract resolve(request: BashExecRequest): BashExecSpec',
+      'abstract run(spec: BashExecSpec): Promise<BashRunResult>',
+      'abstract start(spec: BashExecSpec): BashTask',
+      'abstract get(id: BashTaskId): BashTask | undefined',
+      'abstract ownerOf(id: BashTaskId): OwnerToken | undefined',
+      'abstract list(): BashTask[]',
+      'abstract readOutput(id: BashTaskId): BashTaskRead',
+      'abstract kill(id: BashTaskId): boolean',
+      'onTaskDone(listener: BashTaskListener): () => void',
+    ],
+  },
+  {
+    key: 'codeRuntime',
+    summary: 'Abstract code-execution service.',
+    methods: [
+      'abstract run(request: CodeRunRequest): Promise<CodeRunResult>',
+    ],
+  },
+  {
+    key: 'compact',
+    summary: 'Abstract compaction service.',
+    methods: [
+      'abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>',
+      'abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
+    ],
+  },
+  {
+    key: 'fs',
+    summary: 'Abstract filesystem provider service.',
+    methods: [
+      'abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>',
+      'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
+      'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
+      'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
+      'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>',
+      'abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>',
+      'abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>',
+    ],
+  },
+  {
+    key: 'llm',
+    summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.',
+    methods: [
+      'registerAdapter(models: string[], adapter: LlmAdapter): () => void',
+      'models(): string[]',
+      'stream(options: GenerateOptions): AsyncIterable<StreamChunk>',
+    ],
+  },
+  {
+    key: 'sessionPersistence',
+    summary: 'Abstract durable session-persistence service.',
+    methods: [
+      'abstract create(meta: SessionHeader): Promise<void>',
+      'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
+      'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
+      'abstract list(): Promise<SessionHeader[]>',
+    ],
+  },
+  {
+    key: 'sessions',
+    summary: 'In-memory session store (`ctx.sessions`).',
+    methods: [
+      'create(id?: SessionId, options?: CreateSessionOptions): Session',
+      'prepare(id?: SessionId, options?: CreateSessionOptions): Session',
+      'enter(session: Session): () => void',
+      'announce(session: Session): void',
+      'get(id: SessionId): Session | undefined',
+      'list(): Session[]',
+      'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session',
+    ],
+  },
+  {
+    key: 'subagents',
+    summary: 'The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.',
+    methods: [
+      'registerProvider(provider: SubagentProvider): () => void',
+      'getProvider(name: string): SubagentProvider | undefined',
+      'list(): string[]',
+      'start(name: string, request: SubagentStartRequest): SubagentRun',
+    ],
+  },
+  {
+    key: 'systemPrompt',
+    summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step.',
+    methods: [
+      'section(section: PromptSection): () => void',
+      'tools(provider: () => ToolSchema[]): () => void',
+      'variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void',
+      'async assemble(context: AssembleContext = {}): Promise<PromptAssembly>',
+    ],
+  },
+  {
+    key: 'tools',
+    summary: 'Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → `tools/execute` → `tools/post-execute` pipeline.',
+    methods: [
+      'register(definition: ToolDefinition): () => void',
+      'get(name: string): ToolDefinition | undefined',
+      'schemas(): ToolSchema[]',
+      'async execute(exec: ToolExecution): Promise<ToolExecutionResult>',
+    ],
+  },
+  {
+    key: 'userInteraction',
+    summary: '`ctx.userInteraction`: one active UI provider plus an `ask()` surface.',
+    methods: [
+      'registerProvider(provider: UserInteractionProvider): () => void',
+      'async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>',
+    ],
+  },
+  {
+    key: 'web',
+    summary: 'The web access service.',
+    methods: [
+      'registerSearchProvider(provider: WebSearchProvider): () => void',
+      'registerFetchProvider(provider: WebFetchProvider): () => void',
+      'async search(request: WebSearchRequest, exec?: WebExecContext): Promise<WebSearchResult>',
+      'async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise<WebFetchResult>',
+    ],
+  },
+  {
+    key: 'workflows',
+    summary: 'Abstract workflow execution service.',
+    methods: [
+      'abstract start(request: WorkflowStartRequest): WorkflowRun',
+    ],
+  },
+]
+
+/** Every harness event, sorted by name. */
+export const EVENT_API: readonly EventApiEntry[] = [
+  {
+    name: 'agent/created',
+    mode: 'emit',
+    signature: '\'agent/created\'(agent: Agent): void',
+    summary: 'An agent was registered in the AgentRegistry and is ready to receive messages.',
+  },
+  {
+    name: 'agent/disposed',
+    mode: 'emit',
+    signature: '\'agent/disposed\'(agent: Agent): void',
+    summary: 'An agent was disposed and removed from the registry; its fiber and any in-flight turn have been torn down.',
+  },
+  {
+    name: 'agent/error',
+    mode: 'emit',
+    signature: '\'agent/error\'(agent: Agent, turn: number, step: number, error: Error): void',
+    summary: 'A step or turn errored.',
+  },
+  {
+    name: 'agent/pre-step',
+    mode: 'serial',
+    signature: '\'agent/pre-step\'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void',
+    summary: 'Awaited pre-step surface-mutation checkpoint, fired once per step AFTER `turn/start` (and after the prior step closed) but BEFORE this step\'s `step/start` — so anything a listener appends lands OUTSIDE the step, between `turn/start`/`step/end` and the upcoming `step/start`.',
+  },
+  {
+    name: 'agent/prompt-submit',
+    mode: 'waterfall',
+    signature: '\'agent/prompt-submit\'(agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>',
+    summary: 'Waterfall: decide what happens to ONE drained queued message before it becomes a `user/message` — allow (optionally rewriting the prompt bytes or attaching `additionalContext`) or block it.',
+  },
+  {
+    name: 'agent/queued',
+    mode: 'emit',
+    signature: '\'agent/queued\'(agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void',
+    summary: 'A message entered the agent\'s inbox (queued or steering).',
+  },
+  {
+    name: 'agent/request',
+    mode: 'waterfall',
+    signature: '\'agent/request\'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
+    summary: 'Waterfall: shape the step\'s call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use).',
+  },
+  {
+    name: 'agent/session-prefix',
+    mode: 'waterfall',
+    signature: '\'agent/session-prefix\'(agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>',
+    summary: 'Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider\'s system slot) on every request this loop instance sends.',
+  },
+  {
+    name: 'agent/session-start',
+    mode: 'emit',
+    signature: '\'agent/session-start\'(agent: Agent, source: SessionStartSource): void',
+    summary: 'The agent\'s session lifecycle began, fired once before its first turn.',
+  },
+  {
+    name: 'agent/status',
+    mode: 'emit',
+    signature: '\'agent/status\'(agent: Agent, status: AgentStatus): void',
+    summary: 'Agent status changed (`idle` ⇄ `running`, or → `disposed`).',
+  },
+  {
+    name: 'agent/step-result',
+    mode: 'waterfall',
+    signature: '\'agent/step-result\'(agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>',
+    summary: 'Waterfall: post-process the assembled assistant Message before tool dispatch (validation, content rewriting, …).',
+  },
+  {
+    name: 'agent/turn-continuation',
+    mode: 'waterfall',
+    signature: '\'agent/turn-continuation\'(agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>',
+    summary: 'Waterfall: override the turn-continuation decision via a typed ContinuationDecision.',
+  },
+  {
+    name: 'fs/edit-intent',
+    mode: 'waterfall',
+    signature: '\'fs/edit-intent\'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>',
+    summary: 'Single-slot decision: produce the optional version guard for the next FileSystem.editText.',
+  },
+  {
+    name: 'fs/observed',
+    mode: 'emit',
+    signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void',
+    summary: 'Record that an actor observed a target at a version, after a successful read/write/edit.',
+  },
+  {
+    name: 'fs/write-intent',
+    mode: 'waterfall',
+    signature: '\'fs/write-intent\'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>',
+    summary: 'Single-slot decision: produce the write intent for the next FileSystem.writeText.',
+  },
+  {
+    name: 'llm/stream',
+    mode: 'waterfall',
+    signature: '\'llm/stream\'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>',
+    summary: 'Waterfall around every streaming model call (retry, replay, routing).',
+  },
+  {
+    name: 'session/created',
+    mode: 'emit',
+    signature: '\'session/created\'(session: Session): void',
+    summary: 'A session was created in the store.',
+  },
+  {
+    name: 'session/event',
+    mode: 'emit',
+    signature: '\'session/event\'(session: Session, event: SessionEvent): void',
+    summary: 'An event was appended to a session log (sync, fire-and-forget).',
+  },
+  {
+    name: 'session/flush',
+    mode: 'parallel',
+    signature: '\'session/flush\'(session: Session): Promise<void> | void',
+    summary: 'Awaited durability checkpoint.',
+  },
+  {
+    name: 'subagent/end',
+    mode: 'emit',
+    signature: '\'subagent/end\'(info: SubagentRunEndInfo): void',
+    summary: 'A subagent run settled — emitted when SubagentRun.result resolves (any stop reason).',
+  },
+  {
+    name: 'subagent/provider-added',
+    mode: 'emit',
+    signature: '\'subagent/provider-added\'(provider: SubagentProvider): void',
+    summary: 'A provider became resolvable in the SubagentService registry.',
+  },
+  {
+    name: 'subagent/provider-removed',
+    mode: 'emit',
+    signature: '\'subagent/provider-removed\'(name: string): void',
+    summary: 'A provider left the registry (its plugin\'s fiber was disposed — an unload or an HMR reload).',
+  },
+  {
+    name: 'subagent/start',
+    mode: 'emit',
+    signature: '\'subagent/start\'(info: SubagentRunInfo): void',
+    summary: 'A subagent run started — emitted after the provider is resolved and its capabilities validated, as the child run begins.',
+  },
+  {
+    name: 'system-prompt/assemble',
+    mode: 'waterfall',
+    signature: '\'system-prompt/assemble\'(this: SystemPrompt, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>',
+    summary: 'Waterfall around prompt assembly — mutate or extend the PromptAssembly (sections + tools + variables) before it is rendered.',
+  },
+  {
+    name: 'system-prompt/change',
+    mode: 'emit',
+    signature: '\'system-prompt/change\'(): void',
+    summary: 'A section, tool provider, or variable provider was registered or unregistered (the assembly inputs changed).',
+  },
+  {
+    name: 'tools/change',
+    mode: 'emit',
+    signature: '\'tools/change\'(): void',
+    summary: 'A tool was registered or unregistered (the available tool set changed).',
+  },
+  {
+    name: 'tools/execute',
+    mode: 'waterfall',
+    signature: '\'tools/execute\'(this: ToolRegistry, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>',
+    summary: 'Around-dispatch waterfall wrapping the registry\'s core tool dispatch, between the `tools/pre-execute` gate and the `tools/post-execute` seam.',
+  },
+  {
+    name: 'tools/post-execute',
+    mode: 'waterfall',
+    signature: '\'tools/post-execute\'(this: ToolRegistry, exec: ToolExecution, result: ToolExecutionResult, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
+    summary: 'Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code\'s `PostToolUse`).',
+  },
+  {
+    name: 'tools/pre-execute',
+    mode: 'waterfall',
+    signature: '\'tools/pre-execute\'(this: ToolRegistry, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>',
+    summary: 'Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code\'s `PreToolUse`).',
+  },
+  {
+    name: 'workflow/agent-end',
+    mode: 'emit',
+    signature: '\'workflow/agent-end\'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void',
+    summary: 'One `agent()` call settled (clean result, child failure, or run cancellation).',
+  },
+  {
+    name: 'workflow/agent-start',
+    mode: 'emit',
+    signature: '\'workflow/agent-start\'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void',
+    summary: 'One `agent()` call started a child run.',
+  },
+  {
+    name: 'workflow/end',
+    mode: 'emit',
+    signature: '\'workflow/end\'(info: WorkflowRunInfo, result: WorkflowResultInfo): void',
+    summary: 'A workflow run settled (any stop reason).',
+  },
+  {
+    name: 'workflow/log',
+    mode: 'emit',
+    signature: '\'workflow/log\'(info: WorkflowRunInfo, message: string): void',
+    summary: 'The script emitted a narration line (a `log(message)` call).',
+  },
+  {
+    name: 'workflow/phase',
+    mode: 'emit',
+    signature: '\'workflow/phase\'(info: WorkflowRunInfo, title: string): void',
+    summary: 'The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.',
+  },
+  {
+    name: 'workflow/start',
+    mode: 'emit',
+    signature: '\'workflow/start\'(info: WorkflowRunInfo): void',
+    summary: 'A workflow run started — the script\'s meta block validated, the body about to execute.',
+  },
+]
+
+/** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */
+export const TYPE_API: readonly TypeApiEntry[] = [
+  {
+    name: 'Agent',
+    declaration: 'export interface Agent {\n    readonly id: AgentId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    send(content: ContentBlock[], options?: SendOptions): void;\n    steer(content: ContentBlock[], options?: SendOptions): void;\n    inject(content: ContentBlock[], options?: SendOptions): void;\n    cancel(reason?: string): void;\n    whenIdle(): Promise<void>;\n}',
+  },
+  {
+    name: 'AgentFactory',
+    declaration: 'export interface AgentFactory {\n    createAgent(options: CreateAgentOptions): AgentHandle;\n    resume(options: ResumeAgentOptions): Promise<AgentHandle>;\n}',
+  },
+  {
+    name: 'AgentHandle',
+    declaration: 'export interface AgentHandle {\n    agent: Agent;\n    dispose(): Promise<void>;\n}',
+  },
+  {
+    name: 'AgentId',
+    declaration: 'export type AgentId = Branded<\'AgentId\'>;',
+  },
+  {
+    name: 'AgentOptions',
+    declaration: 'export interface AgentOptions {\n    model?: string;\n}',
+  },
+  {
+    name: 'AgentStatus',
+    declaration: 'export type AgentStatus = \'idle\' | \'running\' | \'disposed\';',
+  },
+  {
+    name: 'AskUserQuestionAnswer',
+    declaration: 'export interface AskUserQuestionAnswer {\n    answers: AskUserQuestionAnswerItem[];\n}',
+  },
+  {
+    name: 'AskUserQuestionAnswerItem',
+    declaration: 'export interface AskUserQuestionAnswerItem {\n    id: string;\n    selected: string[];\n    custom?: string;\n}',
+  },
+  {
+    name: 'AskUserQuestionItem',
+    declaration: 'export interface AskUserQuestionItem {\n    id: string;\n    question: string;\n    header?: string;\n    options?: AskUserQuestionOption[];\n    multiSelect?: boolean;\n}',
+  },
+  {
+    name: 'AskUserQuestionOption',
+    declaration: 'export interface AskUserQuestionOption {\n    label: string;\n    description?: string;\n}',
+  },
+  {
+    name: 'AskUserQuestionRequest',
+    declaration: 'export interface AskUserQuestionRequest {\n    questions: AskUserQuestionItem[];\n    agent?: Agent;\n    signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'AssembleContext',
+    declaration: 'export interface AssembleContext {\n}',
+  },
+  {
+    name: 'AssembledSection',
+    declaration: 'export interface AssembledSection {\n    name: string;\n    order: number;\n    text: string;\n}',
+  },
+  {
+    name: 'BashExecRequest',
+    declaration: 'export interface BashExecRequest {\n    command: string;\n    workdir?: string | undefined;\n    timeoutMs?: number | undefined;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    owner?: OwnerToken | undefined;\n}',
+  },
+  {
+    name: 'BashExecSpec',
+    declaration: 'export interface BashExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    owner: OwnerToken | undefined;\n}',
+  },
+  {
+    name: 'BashRunResult',
+    declaration: 'export interface BashRunResult {\n    exitCode: number | null;\n    signal: NodeJS.Signals | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: CollectedOutput;\n    stderr: CollectedOutput;\n}',
+  },
+  {
+    name: 'BashTask',
+    declaration: 'export interface BashTask {\n    readonly id: BashTaskId;\n    readonly command: string;\n    status: BashTaskStatus;\n    exitCode: number | null;\n    signal: NodeJS.Signals | null;\n    readonly done: Promise<void>;\n}',
+  },
+  {
+    name: 'BashTaskId',
+    declaration: 'export type BashTaskId = Branded<\'BashTaskId\'>;',
+  },
+  {
+    name: 'BashTaskListener',
+    declaration: 'export type BashTaskListener = (task: BashTask) => void;',
+  },
+  {
+    name: 'BashTaskRead',
+    declaration: 'export interface BashTaskRead {\n    task: BashTask;\n    delta: string;\n    lossy: boolean;\n    stdoutSpillPath?: string;\n    stderrSpillPath?: string;\n}',
+  },
+  {
+    name: 'BashTaskStatus',
+    declaration: 'export type BashTaskStatus = \'running\' | \'completed\' | \'killed\';',
+  },
+  {
+    name: 'Branded',
+    declaration: 'export type Branded<B extends string> = string & {\n    readonly [BRAND]: B;\n};',
+  },
+  {
+    name: 'CallId',
+    declaration: 'export type CallId = Branded<\'CallId\'>;',
+  },
+  {
+    name: 'CodeBindingFunction',
+    declaration: 'export type CodeBindingFunction = (args: unknown) => Promise<unknown>;',
+  },
+  {
+    name: 'CodeBindingNamespace',
+    declaration: 'export interface CodeBindingNamespace {\n    global: string;\n    functions: Record<string, CodeBindingFunction>;\n}',
+  },
+  {
+    name: 'CodeLogEntry',
+    declaration: 'export interface CodeLogEntry {\n    source: \'console\' | \'stdout\' | \'stderr\';\n    level?: \'log\' | \'info\' | \'warn\' | \'error\' | \'debug\';\n    text: string;\n}',
+  },
+  {
+    name: 'CodeRunFailure',
+    declaration: 'export interface CodeRunFailure {\n    kind: \'exception\' | \'timeout\' | \'abort\' | \'worker-exit\';\n    message: string;\n}',
+  },
+  {
+    name: 'CodeRunRequest',
+    declaration: 'export interface CodeRunRequest {\n    program: string;\n    bindings: CodeBindingNamespace[];\n    signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'CodeRunResult',
+    declaration: 'export interface CodeRunResult {\n    value?: unknown;\n    logs: CodeLogEntry[];\n    error?: CodeRunFailure;\n}',
+  },
+  {
+    name: 'CollectedOutput',
+    declaration: 'export interface CollectedOutput {\n    text: string;\n    truncated: boolean;\n    spillPath?: string;\n}',
+  },
+  {
+    name: 'CompactAgentContext',
+    declaration: 'export interface CompactAgentContext {\n    session: Session;\n    options: {\n        model?: string;\n    };\n}',
+  },
+  {
+    name: 'CompactionResult',
+    declaration: 'export interface CompactionResult {\n    startSeq: number;\n    summarySeq: number;\n    endSeq: number;\n    summary: ContentBlock[];\n    shadowedRange: {\n        start: number;\n        end: number;\n    };\n    shadowedSeqs: number[];\n    shadowedTokenCount: number;\n}',
+  },
+  {
+    name: 'ContentBlockMap',
+    declaration: 'export interface ContentBlockMap {\n    \'text\': TextBlock;\n    \'reasoning\': ReasoningBlock;\n    \'tool-call\': ToolCallBlock;\n    \'tool-result\': ToolResultBlock;\n}',
+  },
+  {
+    name: 'ContentBlockType',
+    declaration: 'export type ContentBlockType = keyof ContentBlockMap;',
+  },
+  {
+    name: 'CreateAgentOptions',
+    declaration: 'export interface CreateAgentOptions {\n    agentId: AgentId;\n    sessionId: SessionId;\n    meta?: {\n        cwd?: string;\n        parentSession?: SessionId;\n        seedLength?: number;\n    };\n    seed?: SessionEvent[];\n    agentOptions?: AgentOptions;\n}',
+  },
+  {
+    name: 'CreateSessionOptions',
+    declaration: 'export interface CreateSessionOptions {\n    seed?: SessionEvent[];\n    meta?: {\n        cwd?: string;\n        parentSession?: SessionId;\n        createdAt?: number;\n        seedLength?: number;\n    };\n}',
+  },
+  {
+    name: 'DiffCallView',
+    declaration: 'export interface DiffCallView {\n    card: \'diff\';\n    title: string;\n    diffs: FileDiff[];\n    locations?: FileLocation[];\n}',
+  },
+  {
+    name: 'DiffResultView',
+    declaration: 'export interface DiffResultView {\n    card: \'diff\';\n    title?: string;\n    diffs: FileDiff[];\n}',
+  },
+  {
+    name: 'FileDiff',
+    declaration: 'export interface FileDiff {\n    path: string;\n    oldText: string | null;\n    newText: string;\n}',
+  },
+  {
+    name: 'FileLocation',
+    declaration: 'export interface FileLocation {\n    path: string;\n    line?: number;\n}',
+  },
+  {
+    name: 'FinishReason',
+    declaration: 'export type FinishReason = FinishReasonMap[keyof FinishReasonMap];',
+  },
+  {
+    name: 'FinishReasonMap',
+    declaration: 'export interface FinishReasonMap {\n    \'stop\': {\n        kind: \'stop\';\n    };\n    \'tool-calls\': {\n        kind: \'tool-calls\';\n    };\n    \'max-tokens\': {\n        kind: \'max-tokens\';\n    };\n    \'aborted\': {\n        kind: \'aborted\';\n    };\n    \'error\': {\n        kind: \'error\';\n        message: string;\n        code?: string;\n    };\n}',
+  },
+  {
+    name: 'FsDirEntry',
+    declaration: 'export interface FsDirEntry {\n    name: string;\n    type: \'file\' | \'directory\' | \'other\';\n    target: FsTarget;\n    version?: FsVersion;\n    size?: number;\n}',
+  },
+  {
+    name: 'FsEditOutcome',
+    declaration: 'export interface FsEditOutcome {\n    version: FsVersion;\n    before: string;\n    after: string;\n}',
+  },
+  {
+    name: 'FsEditRequest',
+    declaration: 'export interface FsEditRequest {\n    oldString: string;\n    newString: string;\n    replaceAll: boolean;\n}',
+  },
+  {
+    name: 'FsInfo',
+    declaration: 'export interface FsInfo {\n    version: FsVersion;\n    type: \'file\' | \'directory\' | \'other\';\n    size?: number;\n}',
+  },
+  {
+    name: 'FsTarget',
+    declaration: 'export interface FsTarget {\n    targetKey: FsTargetKey;\n    displayPath: string;\n}',
+  },
+  {
+    name: 'FsTargetKey',
+    declaration: 'export type FsTargetKey = Branded<\'FsTargetKey\'>;',
+  },
+  {
+    name: 'FsVersion',
+    declaration: 'export type FsVersion = Branded<\'FsVersion\'>;',
+  },
+  {
+    name: 'FsWriteIntent',
+    declaration: 'export type FsWriteIntent = {\n    kind: \'createIfAbsent\';\n} | {\n    kind: \'replaceIfVersion\';\n    version: FsVersion;\n};',
+  },
+  {
+    name: 'FsWriteOutcome',
+    declaration: 'export interface FsWriteOutcome {\n    operation: \'create\' | \'update\';\n    version: FsVersion;\n    before: string | null;\n    after: string;\n}',
+  },
+  {
+    name: 'GenerateOptions',
+    declaration: 'export interface GenerateOptions {\n    model: string;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<\'SessionId\'>;\n}',
+  },
+  {
+    name: 'GenericCallView',
+    declaration: 'export interface GenericCallView {\n    card: \'generic\';\n    title: string;\n    kind?: ToolCallKind;\n    rawInput?: unknown;\n    content?: ContentBlock[];\n    locations?: FileLocation[];\n}',
+  },
+  {
+    name: 'GenericResultView',
+    declaration: 'export interface GenericResultView {\n    card: \'generic\';\n    title?: string;\n    content?: ContentBlock[];\n}',
+  },
+  {
+    name: 'HookContext',
+    declaration: 'export interface HookContext {\n    content: ContentBlock[];\n    source: MessageSource;\n}',
+  },
+  {
+    name: 'Message',
+    declaration: 'export interface Message {\n    role: \'system\' | \'user\' | \'assistant\';\n    content: ContentBlock[];\n}',
+  },
+  {
+    name: 'MessageSource',
+    declaration: 'export type MessageSource = MessageSourceMap[keyof MessageSourceMap];',
+  },
+  {
+    name: 'MessageSourceMap',
+    declaration: 'export interface MessageSourceMap {\n    user: {\n        kind: \'user\';\n    };\n    plugin: {\n        kind: \'plugin\';\n        plugin: string;\n    };\n}',
+  },
+  {
+    name: 'OwnerToken',
+    declaration: 'export type OwnerToken = Branded<\'OwnerToken\'>;',
+  },
+  {
+    name: 'PromptAssembly',
+    declaration: 'export interface PromptAssembly {\n    sections: AssembledSection[];\n    tools: ToolSchema[];\n    variables: Record<string, string | undefined>;\n}',
+  },
+  {
+    name: 'PromptSection',
+    declaration: 'export interface PromptSection {\n    name: string;\n    order: number;\n    text: string | ((context: AssembleContext) => string);\n}',
+  },
+  {
+    name: 'ReasoningBlock',
+    declaration: 'export interface ReasoningBlock {\n    type: \'reasoning\';\n    text: string;\n}',
+  },
+  {
+    name: 'ResumeAgentOptions',
+    declaration: 'export interface ResumeAgentOptions {\n    agentId: AgentId;\n    resumeSessionId: SessionId;\n    agentOptions?: AgentOptions;\n}',
+  },
+  {
+    name: 'SendOptions',
+    declaration: 'export interface SendOptions {\n    source?: MessageSource;\n}',
+  },
+  {
+    name: 'SessionEvent',
+    declaration: 'export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n    [K in SessionEventType]: {\n        type: K;\n        seq: number;\n        time: number;\n        data: SessionEventMap[K];\n    } & (K extends SurfaceEventType ? {\n        sourceEventSeqs?: number[];\n        surfaceOp?: SurfaceOp;\n    } : object);\n}[T];',
+  },
+  {
+    name: 'SessionEventMap',
+    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': {\n        turn: number;\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: E /* …truncated — full shape in source */',
+  },
+  {
+    name: 'SessionEventType',
+    declaration: 'export type SessionEventType = keyof SessionEventMap;',
+  },
+  {
+    name: 'SessionForkSource',
+    declaration: 'export type SessionForkSource = Session | SessionId;',
+  },
+  {
+    name: 'SessionHeader',
+    declaration: 'export interface SessionHeader {\n    version: number;\n    id: SessionId;\n    createdAt: number;\n    cwd?: string;\n    parentSession?: SessionId;\n    seedLength?: number;\n}',
+  },
+  {
+    name: 'SessionId',
+    declaration: 'export type SessionId = Branded<\'SessionId\'>;',
+  },
+  {
+    name: 'StreamChunk',
+    declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n};',
+  },
+  {
+    name: 'StructuredOutputSchema',
+    declaration: 'export type StructuredOutputSchema = StructuredSchemaNode & {\n    type: \'object\';\n};',
+  },
+  {
+    name: 'StructuredScalar',
+    declaration: 'export type StructuredScalar = string | number | boolean | null;',
+  },
+  {
+    name: 'StructuredSchemaNode',
+    declaration: 'export interface StructuredSchemaNode {\n    type: StructuredSchemaType;\n    properties?: Record<string, StructuredSchemaNode>;\n    required?: string[];\n    additionalProperties?: boolean;\n    items?: StructuredSchemaNode;\n    enum?: StructuredScalar[];\n    const?: StructuredScalar;\n    description?: string;\n    title?: string;\n    default?: unknown;\n    examples?: unknown;\n}',
+  },
+  {
+    name: 'StructuredSchemaType',
+    declaration: 'export type StructuredSchemaType = \'object\' | \'array\' | \'string\' | \'number\' | \'integer\' | \'boolean\' | \'null\';',
+  },
+  {
+    name: 'SubagentCapabilities',
+    declaration: 'export interface SubagentCapabilities {\n    outputSchema: boolean;\n    depthLimit: boolean;\n    toolFilter: boolean;\n}',
+  },
+  {
+    name: 'SubagentProvider',
+    declaration: 'export interface SubagentProvider {\n    readonly name: string;\n    readonly capabilities: SubagentCapabilities;\n    readonly inheritsParentContext: boolean;\n    start(request: SubagentStartRequest): SubagentRun;\n}',
+  },
+  {
+    name: 'SubagentResult',
+    declaration: 'export interface SubagentResult {\n    output: ContentBlock[];\n    structured?: unknown;\n    stopReason: SubagentStopReason;\n}',
+  },
+  {
+    name: 'SubagentRun',
+    declaration: 'export interface SubagentRun {\n    readonly id: AgentId;\n    readonly result: Promise<SubagentResult>;\n    cancel(reason?: string): void;\n    dispose(): Promise<void>;\n    sendMessage?(content: ContentBlock[]): void;\n    resume?(content: ContentBlock[]): SubagentRun;\n}',
+  },
+  {
+    name: 'SubagentStartRequest',
+    declaration: 'export interface SubagentStartRequest {\n    prompt: ContentBlock[];\n    parent: Agent;\n    signal?: AbortSignal;\n    agentOptions?: AgentOptions;\n    outputSchema?: StructuredOutputSchema;\n    maxDepth?: number;\n    toolFilter?: {\n        allow?: string[];\n        deny?: string[];\n    };\n}',
+  },
+  {
+    name: 'SubagentStopReason',
+    declaration: 'export type SubagentStopReason = SubagentStopReasonMap[keyof SubagentStopReasonMap];',
+  },
+  {
+    name: 'SubagentStopReasonMap',
+    declaration: 'export interface SubagentStopReasonMap {\n    completed: \'completed\';\n    aborted: \'aborted\';\n    error: \'error\';\n    \'max-tokens\': \'max-tokens\';\n    refusal: \'refusal\';\n}',
+  },
+  {
+    name: 'SurfaceEventType',
+    declaration: 'export type SurfaceEventType = \'user/message\' | \'assistant/message\' | \'tool/result\' | \'context/message\' | \'steering/message\';',
+  },
+  {
+    name: 'SurfaceOp',
+    declaration: 'export type SurfaceOp = \'append\' | {\n    op: \'replace\';\n    start: number;\n    end: number;\n};',
+  },
+  {
+    name: 'TerminalCallView',
+    declaration: 'export interface TerminalCallView {\n    card: \'terminal\';\n    title: string;\n    description?: string;\n    cwd?: string;\n}',
+  },
+  {
+    name: 'TerminalResultView',
+    declaration: 'export interface TerminalResultView {\n    card: \'terminal\';\n    title?: string;\n    output?: string;\n    exitCode?: number;\n    signal?: string;\n}',
+  },
+  {
+    name: 'TodoItem',
+    declaration: 'export interface TodoItem {\n    content: string;\n    status: \'pending\' | \'in_progress\' | \'completed\';\n}',
+  },
+  {
+    name: 'TokenUsage',
+    declaration: 'export interface TokenUsage {\n    inputTokens: number;\n    outputTokens: number;\n    cacheReadTokens?: number;\n    cacheWriteTokens?: number;\n    reasoningTokens?: number;\n}',
+  },
+  {
+    name: 'ToolCallBlock',
+    declaration: 'export interface ToolCallBlock {\n    type: \'tool-call\';\n    id: CallId;\n    name: string;\n    arguments: string;\n}',
+  },
+  {
+    name: 'ToolCallKind',
+    declaration: 'export type ToolCallKind = \'read\' | \'edit\' | \'delete\' | \'move\' | \'search\' | \'execute\' | \'fetch\' | \'other\';',
+  },
+  {
+    name: 'ToolCallView',
+    declaration: 'export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;',
+  },
+  {
+    name: 'ToolDefinition',
+    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
+  },
+  {
+    name: 'ToolErrorInfo',
+    declaration: 'export interface ToolErrorInfo {\n    name: string;\n    code: string;\n}',
+  },
+  {
+    name: 'ToolExecuteReturn',
+    declaration: 'export type ToolExecuteReturn = ContentBlock[] | {\n    content: ContentBlock[];\n    meta?: unknown;\n};',
+  },
+  {
+    name: 'ToolExecution',
+    declaration: 'export interface ToolExecution {\n    callId: CallId;\n    name: string;\n    arguments: unknown;\n    agent?: Agent;\n    signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'ToolExecutionResult',
+    declaration: 'export interface ToolExecutionResult {\n    callId: CallId;\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContext?: HookContext;\n    meta?: unknown;\n}',
+  },
+  {
+    name: 'ToolResult',
+    declaration: 'export interface ToolResult {\n    content: ContentBlock[];\n    isError: boolean;\n    meta?: unknown;\n}',
+  },
+  {
+    name: 'ToolResultBlock',
+    declaration: 'export interface ToolResultBlock {\n    type: \'tool-result\';\n    toolCallId: CallId;\n    content: ContentBlock[];\n    isError?: boolean;\n}',
+  },
+  {
+    name: 'ToolResultView',
+    declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;',
+  },
+  {
+    name: 'ToolSchema',
+    declaration: 'export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}',
+  },
+  {
+    name: 'TurnEndReason',
+    declaration: 'export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];',
+  },
+  {
+    name: 'TurnEndReasonMap',
+    declaration: 'export interface TurnEndReasonMap {\n    completed: {\n        kind: \'completed\';\n    };\n    aborted: {\n        kind: \'aborted\';\n        reason?: string;\n    };\n    error: {\n        kind: \'error\';\n        step: number;\n        message: string;\n        code?: string;\n    };\n    disposed: {\n        kind: \'disposed\';\n    };\n    \'max-tokens\': {\n        kind: \'max-tokens\';\n    };\n    rejected: {\n        kind: \'rejected\';\n        reason: string;\n    };\n    interrupted: {\n        kind: \'interrupted\';\n    };\n}',
+  },
+  {
+    name: 'TurnTrigger',
+    declaration: 'export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];',
+  },
+  {
+    name: 'TurnTriggerMap',
+    declaration: 'export interface TurnTriggerMap {\n    message: {\n        kind: \'message\';\n        source: MessageSource;\n    };\n    injection: {\n        kind: \'injection\';\n        source: MessageSource;\n    };\n}',
+  },
+  {
+    name: 'UserInteractionProvider',
+    declaration: 'export interface UserInteractionProvider {\n    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>;\n}',
+  },
+  {
+    name: 'WebExecContext',
+    declaration: 'export interface WebExecContext {\n    readonly signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'WebFetchBody',
+    declaration: 'export type WebFetchBody = {\n    readonly kind: \'html\';\n    readonly content: string;\n} | {\n    readonly kind: \'text\';\n    readonly content: string;\n};',
+  },
+  {
+    name: 'WebFetchProvider',
+    declaration: 'export interface WebFetchProvider {\n    readonly id: string;\n    status(): WebProviderStatus;\n    fetch(request: WebFetchRequest, exec?: WebExecContext): Promise<WebFetchResult>;\n}',
+  },
+  {
+    name: 'WebFetchRequest',
+    declaration: 'export interface WebFetchRequest {\n    readonly url: string;\n    readonly timeoutMs?: number;\n}',
+  },
+  {
+    name: 'WebFetchResult',
+    declaration: 'export interface WebFetchResult {\n    readonly providerId: string;\n    readonly url: string;\n    readonly statusCode: number;\n    readonly body: WebFetchBody;\n    readonly truncated: boolean;\n}',
+  },
+  {
+    name: 'WebProviderStatus',
+    declaration: 'export type WebProviderStatus = {\n    readonly available: true;\n} | {\n    readonly available: false;\n    readonly reason: \'missing-credential\' | \'misconfigured\';\n};',
+  },
+  {
+    name: 'WebSearchProvider',
+    declaration: 'export interface WebSearchProvider {\n    readonly id: string;\n    status(): WebProviderStatus;\n    search(request: WebSearchRequest, exec?: WebExecContext): Promise<WebSearchResult>;\n}',
+  },
+  {
+    name: 'WebSearchRequest',
+    declaration: 'export interface WebSearchRequest {\n    readonly query: string;\n    readonly maxResults?: number;\n}',
+  },
+  {
+    name: 'WebSearchResult',
+    declaration: 'export interface WebSearchResult {\n    readonly providerId: string;\n    readonly query: string;\n    readonly content?: string;\n    readonly sources: readonly WebSearchSource[];\n    readonly truncated: boolean;\n}',
+  },
+  {
+    name: 'WebSearchSource',
+    declaration: 'export interface WebSearchSource {\n    readonly url: string;\n    readonly title?: string;\n    readonly snippet?: string;\n    readonly publishedAt?: string;\n}',
+  },
+  {
+    name: 'WorkflowMeta',
+    declaration: 'export interface WorkflowMeta {\n    name: string;\n    description: string;\n    whenToUse?: string;\n    phases?: WorkflowPhase[];\n}',
+  },
+  {
+    name: 'WorkflowPhase',
+    declaration: 'export interface WorkflowPhase {\n    title: string;\n    detail?: string;\n    model?: string;\n}',
+  },
+  {
+    name: 'WorkflowResult',
+    declaration: 'export interface WorkflowResult {\n    value: unknown;\n    stopReason: WorkflowStopReason;\n    error?: string;\n    agentsStarted: number;\n}',
+  },
+  {
+    name: 'WorkflowRun',
+    declaration: 'export interface WorkflowRun {\n    readonly id: WorkflowRunId;\n    readonly meta: WorkflowMeta;\n    readonly result: Promise<WorkflowResult>;\n    cancel(reason?: string): void;\n    dispose(): Promise<void>;\n}',
+  },
+  {
+    name: 'WorkflowRunId',
+    declaration: 'export type WorkflowRunId = Branded<\'WorkflowRunId\'>;',
+  },
+  {
+    name: 'WorkflowStartRequest',
+    declaration: 'export interface WorkflowStartRequest {\n    script: string;\n    meta: WorkflowMeta;\n    args?: unknown;\n    parent: Agent;\n    signal?: AbortSignal;\n}',
+  },
+  {
+    name: 'WorkflowStopReason',
+    declaration: 'export type WorkflowStopReason = \'completed\' | \'cancelled\' | \'error\';',
+  },
+]
+
+/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */
+export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [
+  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).' },
+  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).' },
+  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.' },
+  { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.' },
+  { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.' },
+  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).' },
+  { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.' },
+  { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).' },
+  { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).' },
+  { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).' },
+]

packages/cordis/tool-cordis/src/fiber-state.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime mirror of the cordis `FiberState` const enum plus human-readable
+ * labels, shared by the mount lifecycle (state reporting) and the inspect
+ * renderers (plugin-list and mount-table labels).
+ *
+ * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for
+ * Node's type-stripping runner to import, so the members are mirrored here as
+ * values — each typed (via the type-only import) as the cordis enum member it
+ * mirrors, so enum-typed reads like `fiber.state` compare against them under a
+ * shared enum type. Source of truth: vendor/cordis/src/fiber.ts (pinned; drift
+ * only happens through a deliberate vendor sync).
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/fiber-state
+ */
+
+import type { FiberState as FiberStateEnum } from 'cordis'
+
+/** Value mirror of the cordis `FiberState` const enum (see the module doc for why a mirror exists). */
+export const FiberState = {
+  PENDING: 0 as FiberStateEnum.PENDING,
+  LOADING: 1 as FiberStateEnum.LOADING,
+  ACTIVE: 2 as FiberStateEnum.ACTIVE,
+  FAILED: 3 as FiberStateEnum.FAILED,
+  DISPOSED: 4 as FiberStateEnum.DISPOSED,
+  UNLOADING: 5 as FiberStateEnum.UNLOADING,
+} as const
+
+/** The cordis `FiberState` enum type, re-exported so mirror consumers need one import. */
+export type FiberState = FiberStateEnum
+
+/** Human-readable label for each {@link FiberState}, keyed by member (inlining-safe — no reverse mapping). */
+export const STATE_LABELS: Record<FiberState, string> = {
+  [FiberState.PENDING]: 'pending',
+  [FiberState.LOADING]: 'loading',
+  [FiberState.ACTIVE]: 'active',
+  [FiberState.FAILED]: 'failed',
+  [FiberState.DISPOSED]: 'disposed',
+  [FiberState.UNLOADING]: 'unloading',
+}

packages/cordis/tool-cordis/src/guard.ts

@@ -0,0 +1,447 @@
+/**
+ * The registration boundary between sandboxed mount code and the real runtime:
+ * SchemaSpec normalization + validation with teaching errors, the
+ * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the
+ * SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives in place of the
+ * real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox
+ * return values with.
+ *
+ * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do
+ * exactly four things — register a tool, listen to an event, provide a service,
+ * call an injected service (timers included) — so the façade exposes only those
+ * verbs and the injected services, each object-valued service individually
+ * wrapped (a primitive provided value passes through as-is — see
+ * {@link sandboxContext}). Every framework plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`,
+ * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is
+ * DENIED with a teaching error rather than passed through. This closes an
+ * entire escape class at once: a pass-through proxy that only special-cased
+ * `ctx.tools` still handed back the raw context through `ctx.root`,
+ * `ctx.extend()`, or a service instance's `.ctx`, and mount code could then
+ * `ctx.root.tools.register({…})` to bypass the marker check and host-realm
+ * normalization — a raw vm-realm result then errors a real agent turn at the
+ * session-log plainness check. The whitelist has no such hole: there is no
+ * context-valued member to reach, and any injected-service method that returns
+ * a `Context` is rejected (harness services never do — see {@link denyContext}).
+ *
+ * Two realm facts drive the tool path. Objects built inside the vm carry the vm
+ * realm's `Object.prototype`, and the session log's append-time plainness check
+ * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects
+ * foreign-realm data — so every dynamic tool's `execute` return is JSON
+ * round-tripped into the host realm and shape-checked against the two
+ * `ToolExecuteReturn` forms before it reaches the registry (the registry
+ * trusts the shape blindly — it spreads `result.content`, so an unvalidated
+ * `{ content: 'ok' }` would enter the session log as `['o','k']` and silently
+ * corrupt the next model request), and the schema itself is rebuilt as fresh
+ * host-realm objects. And a malformed tool
+ * schema must fail at REGISTRATION, not when a later request assembles it — so
+ * dynamic tool registration accepts only definitions produced by the sandbox's
+ * `harness.defineTool`, which normalizes `parameters` up front.
+ *
+ * Normalize, don't lecture, where the input has exactly one meaning: models
+ * write the JSON-Schema dialect by strong prior (the `{ type: 'object',
+ * properties, required: […] }` wrapper, `type: 'integer'`, `required: false`),
+ * and each rejection costs a model turn — so those convert to the SchemaSpec
+ * DSL silently, and only genuinely meaningless input (an unknown type, a
+ * non-boolean `required`) is rejected, with the error enumerating the valid
+ * vocabulary.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/guard
+ */
+
+import { Context } from 'cordis'
+import type { Plugin } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools'
+
+const DYNAMIC_TOOL = Symbol('tool-cordis.dynamic-tool')
+const SCHEMA_TYPES = new Set<unknown>(['string', 'number', 'boolean', 'object', 'array'])
+const VALID_TYPES = '\'string\' | \'number\' | \'boolean\' | \'object\' | \'array\''
+
+type DynamicToolDefinition = ToolDefinition & { [DYNAMIC_TOOL]: true }
+type DynamicToolMarker = { [DYNAMIC_TOOL]?: unknown }
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}
+
+/**
+ * Normalize a sandbox-provided `parameters` value into a fresh host-realm
+ * SchemaSpec. Accepts the DSL directly, or the JSON-Schema-style
+ * `{ type: 'object', properties, required: […] }` wrapper models write by
+ * prior — the wrapper unwraps and its `required` array becomes per-property
+ * flags (see the module doc).
+ */
+function normalizeSchemaSpec(value: unknown, path = 'parameters'): Record<string, unknown> {
+  if (!isPlainRecord(value)) {
+    throw new Error(`harness.defineTool ${path} must be a SchemaSpec object`)
+  }
+  let entries = value
+  const requiredNames = new Set<unknown>()
+  if (value.type === 'object' && isPlainRecord(value.properties)) {
+    if (Array.isArray(value.required)) {
+      for (const name of value.required) requiredNames.add(name)
+    }
+    entries = value.properties
+  }
+  const spec: Record<string, unknown> = {}
+  for (const [key, prop] of Object.entries(entries)) {
+    spec[key] = normalizeSchemaProp(prop, `${path}.${key}`, requiredNames.has(key))
+  }
+  return spec
+}
+
+/** Normalize one property: `integer` → `number`, `required: false` → absent, nested wrappers unwrapped recursively. */
+function normalizeSchemaProp(value: unknown, path: string, forceRequired = false): Record<string, unknown> {
+  if (!isPlainRecord(value)) {
+    throw new Error(`harness.defineTool ${path} must be a SchemaSpec property object`)
+  }
+  const type = value.type === 'integer' ? 'number' : value.type
+  if (!SCHEMA_TYPES.has(type)) {
+    throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`)
+  }
+  // On an object property a JSON-Schema-style `required` ARRAY names required
+  // children (handled by the nested unwrap below); everywhere else `required`
+  // must be a boolean, and `false` simply reads as optional.
+  const nestedRequiredArray = type === 'object' && Array.isArray(value.required)
+  if (value.required !== undefined && typeof value.required !== 'boolean' && !nestedRequiredArray) {
+    throw new Error(`harness.defineTool ${path}.required must be a boolean when present`)
+  }
+  const prop: Record<string, unknown> = { type }
+  if (forceRequired || value.required === true) prop.required = true
+  if (typeof value.description === 'string') prop.description = value.description
+  if (Array.isArray(value.enum)) prop.enum = [...value.enum as unknown[]]
+  if (value.default !== undefined) prop.default = value.default
+  if (value.properties !== undefined) {
+    if (type !== 'object') {
+      throw new Error(`harness.defineTool ${path}.properties is only valid for type "object"`)
+    }
+    // Re-wrap so the nested unwrap applies a nested `required` array too.
+    prop.properties = normalizeSchemaSpec(
+      { type: 'object', properties: value.properties, required: value.required },
+      `${path}.properties`,
+    )
+  }
+  if (value.items !== undefined) {
+    if (type !== 'array') {
+      throw new Error(`harness.defineTool ${path}.items is only valid for type "array"`)
+    }
+    prop.items = normalizeSchemaProp(value.items, `${path}.items`)
+  }
+  return prop
+}
+
+function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition {
+  Object.defineProperty(tool, DYNAMIC_TOOL, { value: true })
+  return tool as DynamicToolDefinition
+}
+
+function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition {
+  if (!isPlainRecord(tool) || (tool as DynamicToolMarker)[DYNAMIC_TOOL] !== true) {
+    throw new Error('dynamic tool registration must use a tool returned by harness.defineTool(...)')
+  }
+}
+
+/**
+ * Structurally a content block, checked AFTER the JSON round-trip: a plain
+ * object carrying a string `type` tag. Deliberately nothing deeper — the
+ * ContentBlock union is merge-extensible (an unknown tag must pass), and every
+ * downstream consumer dispatches on `type` and falls through unknowns.
+ */
+function isContentBlockShape(value: unknown): boolean {
+  return isPlainRecord(value) && typeof value.type === 'string'
+}
+
+/**
+ * How much of an invalid execute return the teaching error echoes back — a
+ * huge blob would burn the model turn the error is trying to save.
+ */
+const RETURN_PREVIEW_LIMIT = 120
+
+/**
+ * Compact JSON preview of an invalid execute return for the teaching error
+ * (`String(…)` for the un-stringifiable undefined case), truncated to
+ * {@link RETURN_PREVIEW_LIMIT}.
+ */
+function describeReturn(value: unknown): string {
+  // JSON.stringify is TYPED as always returning string, but it yields
+  // undefined for an undefined input (the routed forgot-return case) — the
+  // assertion widens the type back to the runtime truth.
+  const json = JSON.stringify(value) as string | undefined
+  if (json === undefined) return String(value)
+  return json.length > RETURN_PREVIEW_LIMIT ? `${json.slice(0, RETURN_PREVIEW_LIMIT)}…` : json
+}
+
+/**
+ * Validate a round-tripped `execute` return against the two shapes
+ * {@link ToolExecuteReturn} allows: an ARRAY of content blocks, or
+ * `{ content: blocks, meta? }`. The registry trusts the shape blindly — it
+ * spreads `result.content`, so an unvalidated `{ content: 'ok' }` would enter
+ * the session log as `['o','k']` and silently corrupt the next model request —
+ * so a wrong shape fails THIS call with a teaching error instead.
+ */
+function assertExecuteReturn(value: unknown): ToolExecuteReturn {
+  if (Array.isArray(value) && value.every(isContentBlockShape)) {
+    return value as ToolExecuteReturn
+  }
+  if (isPlainRecord(value) && Array.isArray(value.content) && value.content.every(isContentBlockShape)) {
+    return value as ToolExecuteReturn
+  }
+  throw new Error(
+    `execute returned ${describeReturn(value)} — a tool's execute must return an ARRAY of content blocks, never a bare string:\n`
+    + '  ✓ return [{ type: \'text\', text: someString }]\n'
+    + '  ✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }',
+  )
+}
+
+/**
+ * The `harness.defineTool` handed into the sandbox: the real DSL, with
+ * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema
+ * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the
+ * tool's `execute` return normalized into the host realm via a JSON round-trip
+ * (see the module doc). The round-trip projects the return onto exactly what
+ * the log would durably store, and {@link assertExecuteReturn} then vets that
+ * projection — so a non-JSON-serializable OR wrong-shape return surfaces as
+ * that one call's teaching error instead of poisoning the turn.
+ * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper.
+ * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts.
+ */
+export function sandboxDefineTool(options: Parameters<typeof defineTool>[0]): ToolDefinition {
+  const parameters = normalizeSchemaSpec((options as { parameters?: unknown }).parameters)
+  const tool = defineTool({ ...options, parameters } as Parameters<typeof defineTool>[0])
+  const execute = tool.execute.bind(tool)
+  return markDynamicTool({
+    ...tool,
+    async execute(args, exec) {
+      // JSON.stringify yields NO JSON for an undefined (or function/symbol)
+      // return despite its string-typed signature — route that into
+      // assertExecuteReturn's teaching error rather than letting JSON.parse
+      // throw its cryptic '"undefined" is not valid JSON'.
+      const json = JSON.stringify(await execute(args, exec)) as string | undefined
+      return assertExecuteReturn(json === undefined ? undefined : JSON.parse(json) as unknown)
+    },
+  })
+}
+
+/**
+ * The `harness.registerTool` handed into the sandbox: registers a
+ * marker-verified dynamic tool on the given context's registry.
+ * @param ctx - the (guarded) context whose `tools` service receives the tool.
+ * @param tool - a definition produced by {@link sandboxDefineTool}; anything else is rejected.
+ * @returns the registry disposer for the registration.
+ */
+export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void {
+  assertDynamicTool(tool)
+  return ctx.tools.register(tool)
+}
+
+/**
+ * The verbs a mounted plugin may reach through the sandbox `ctx` façade,
+ * beyond its injected services. `on`/`once` observe events, `provide` exposes
+ * a service to other mounts, and the timer helpers schedule work — each a
+ * fiber effect that unwinds on unmount. Everything else on a real cordis `ctx`
+ * is framework plumbing and is denied. Forwarded LAZILY: the timer helpers are
+ * mixin accessors that throw `without inject` when read on a plugin that did
+ * not inject `timer`, so the façade reads `ctx[verb]` only at call time — the
+ * plugin that never touches a timer never trips that, and one that does gets
+ * cordis's own inject error at the call site.
+ */
+const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce'])
+
+/**
+ * The tool-registry façade: `register` (marker-guarded) plus READ-ONLY
+ * metadata (`schemas`, and `get` returning a schema view, never the live
+ * `ToolDefinition`). Exposing the raw definition would hand mount code the
+ * tool's `execute` function, letting it call another tool directly and bypass
+ * `ToolRegistry.execute` — the pre/post-execute waterfall (permission gates,
+ * accounting) and result normalization. So `get` returns the same
+ * name/description/parameters view as `schemas()`, and nothing invocable.
+ */
+function sandboxTools(ctx: Context): Record<string, unknown> {
+  return {
+    register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool),
+    schemas: () => ctx.tools.schemas(),
+    get: (name: string) => ctx.tools.schemas().find(schema => schema.name === name),
+  }
+}
+
+/**
+ * Reject any injected-service return that is a cordis `Context`. Harness
+ * services return data, never a context; a value that is one would be a
+ * fresh, unguarded handle back into the runtime — the exact escape the façade
+ * exists to close — so it fails loud instead of reaching sandbox code.
+ */
+function denyContext(value: unknown, service: string): unknown {
+  if (value instanceof Context) {
+    throw new Error(
+      `service "${service}" returned a cordis Context, which the sandbox does not expose. `
+      + 'Operate through your own plugin ctx (ctx.on / ctx.provide / ctx.tools.register) '
+      + 'and the services you inject — never another context.',
+    )
+  }
+  return value
+}
+
+/**
+ * Wrap an injected service so its methods forward to the real instance but
+ * their return values pass through {@link denyContext}. Non-function members
+ * (plain data) pass through as-is; a returned Promise is guarded on resolve.
+ */
+function guardedService(service: object, name: string): unknown {
+  return new Proxy(service, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop, target) as unknown
+      if (typeof value !== 'function') return denyContext(value, name)
+      return (...args: unknown[]): unknown => {
+        const result = Reflect.apply(value, target, args) as unknown
+        if (result instanceof Promise) return result.then(v => denyContext(v, name))
+        return denyContext(result, name)
+      }
+    },
+  })
+}
+
+/**
+ * The service names a plugin declared in `inject`, as a lookup set. Whatever
+ * declaration style the plugin used — an `inject: ['bash', 'tools']` array or
+ * the `{ required, optional }` object form — cordis resolves it into a single
+ * name-keyed map on the fiber before `apply` runs (`{ bash: null, tools: null }`),
+ * so the gate just reads that map's keys. A mount may reach only the services
+ * it declared — that is what lets cordis park the mount when a declared
+ * provider unmounts.
+ */
+function declaredInjects(ctx: Context): Set<string> {
+  return new Set(Object.keys(ctx.fiber.inject))
+}
+
+/**
+ * The sandbox context façade handed to a mounted plugin's `apply` in place of
+ * the real `ctx`. A whitelist (see the module doc): the registration/eventing
+ * verbs, the timer helpers, a guarded `tools`, and injected services resolved
+ * through a guarded `get` / property access. A service is reachable only if the
+ * plugin DECLARED it in `inject` — an undeclared service is denied even when a
+ * global provider exists, so cordis's activation/unload semantics (park the
+ * mount when a declared provider goes away) actually bind. Every
+ * framework-plumbing member is denied with a teaching error; there is no
+ * context-valued member to reach.
+ */
+function sandboxContext(ctx: Context): Context {
+  const tools = sandboxTools(ctx)
+  const declared = declaredInjects(ctx)
+  // A framework member or an undeclared service — distinguish the two so the
+  // error teaches the right fix (declare it in inject vs it is withheld).
+  const denyRead = (prop: string): never => {
+    if (ctx.get(prop) !== undefined) {
+      throw new Error(
+        `service "${prop}" is not injected. Declare it: inject: ['${prop}', …] on your plugin, `
+        + 'so cordis parks this mount if the provider is later unmounted.',
+      )
+    }
+    throw new Error(
+      `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / `
+      + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. '
+      + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.',
+    )
+  }
+  // Read a service for either access path (property or `get`). `tools` is the
+  // façade's own surface. An UNDECLARED name is denied with the teaching
+  // error; a DECLARED one resolves to the guarded service. A declared inject
+  // is required in cordis (the fiber only activates once every declared
+  // service is live), so at `apply`/`execute` time `ctx.get(name)` is present
+  // for a declared name — no undefined case to handle here. `provide()`
+  // accepts ANY value though (cross-mount composition advertises
+  // `ctx.provide('name', value)`), so a primitive or null value passes
+  // through unwrapped: Proxy throws on a non-object target, and only an
+  // object can carry a method that hands back a Context.
+  const readService = (name: string): unknown => {
+    if (name === 'tools') return tools
+    if (!declared.has(name)) return denyRead(name)
+    const service = denyContext(ctx.get(name), name)
+    if (service === null || (typeof service !== 'object' && typeof service !== 'function')) return service
+    return guardedService(service, name)
+  }
+  const get = (name: string): unknown => readService(name)
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop === 'tools') return tools
+      if (prop === 'get') return get
+      if (typeof prop !== 'string') return undefined
+      // Lazy verb forwarder — reads `ctx[verb]` only when called, so a plugin
+      // that never uses a timer never triggers the timer mixin's inject check
+      // (cordis raises its own "without inject" error there for undeclared timer use).
+      if (CTX_VERBS.has(prop)) {
+        return (...args: unknown[]): unknown => {
+          const method = ctx[prop as keyof Context]
+          return Reflect.apply(method as (...a: unknown[]) => unknown, ctx, args)
+        }
+      }
+      return readService(prop)
+    },
+    // A façade is not the real ctx; block writes rather than let mount code
+    // stash state on a throwaway object and think it persisted.
+    set(_target, prop) {
+      throw new Error(`sandbox ctx is read-only; cannot assign "${String(prop)}"`)
+    },
+    // `in` reflects reachability: the façade surface plus DECLARED services
+    // (whether or not currently live). Does not resolve/wrap — no throw.
+    has: (_target, prop) => prop === 'tools' || prop === 'get'
+      || (typeof prop === 'string' && (CTX_VERBS.has(prop) || declared.has(prop))),
+  }) as unknown as Context
+}
+
+/**
+ * Narrow an arbitrary sandbox return value to a mountable cordis plugin: a
+ * function, or an object with an `apply` function. (A bare function passes the
+ * first arm, so the object arm never sees `Function.prototype.apply`.)
+ * @param value - whatever the mount code returned.
+ * @returns whether the value is mountable via `ctx.plugin`.
+ */
+export function isPlugin(value: unknown): value is Plugin {
+  if (typeof value === 'function') return true
+  return typeof value === 'object' && value !== null
+    && typeof (value as { apply?: unknown }).apply === 'function'
+}
+
+/**
+ * Wrap a plugin so its `apply` receives the sandbox context façade instead of
+ * the real `ctx` (see {@link sandboxContext} and the module doc). Both
+ * function-form and object-form plugins go through the same wrap; the plugin's
+ * own `inject` declaration is preserved (cordis reads it from the plugin
+ * object, and pending/active gating happens on the real fiber before `apply`
+ * runs), so cross-mount provide/inject works unmodified.
+ *
+ * `ctx.effect(customCleanup)` is deliberately absent from the façade for now —
+ * `on` / `provide` / `tools.register` cover every mount seen so far, and each
+ * is already a fiber effect. FIXME(sandbox-effect): expose a guarded `effect`
+ * once a real mount needs a bespoke disposer.
+ * @param plugin - the plugin the mount code returned.
+ * @returns an equivalent plugin whose `apply` sees the sandbox context façade.
+ */
+export function guardedPlugin(plugin: Plugin): Plugin {
+  if (typeof plugin === 'function') {
+    const functionPlugin = plugin as (ctx: Context, config?: unknown) => unknown
+    return {
+      name: pluginName(plugin),
+      apply(ctx: Context, config?: unknown) {
+        return functionPlugin(sandboxContext(ctx), config)
+      },
+    }
+  }
+  const objectPlugin = plugin as { apply(ctx: Context, config?: unknown): unknown }
+  return {
+    ...plugin,
+    apply(ctx: Context, config?: unknown) {
+      return objectPlugin.apply(sandboxContext(ctx), config)
+    },
+  }
+}
+
+/**
+ * Display name for a mounted plugin: its `name` property, else anonymous.
+ * @param plugin - the plugin the mount code returned.
+ * @returns the human-readable name used in mount results and inspect output.
+ */
+export function pluginName(plugin: Plugin): string {
+  const named = (plugin as { name?: unknown }).name
+  if (typeof named === 'string' && named.length > 0) return named
+  return '<anonymous>'
+}

packages/cordis/tool-cordis/src/index.ts

@@ -0,0 +1,236 @@
+/**
+ * The self-referential cordis toolset: three model-facing tools that let the
+ * agent inspect and MODIFY the live cordis runtime it is running inside.
+ *
+ * - `cordis_inspect` — read-only: provided services, the flat plugin list
+ *   with lifecycle states, registered tools, the dynamic mounts, and the
+ *   catalog-backed `api` / `events` references.
+ * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the
+ *   code returns a cordis plugin, which is mounted as a child of a dedicated
+ *   `cordis-dynamic` group fiber and tracked under an id (`dyn-1`, `dyn-2`, …).
+ * - `cordis_unmount` — dispose one dynamic mount by id, awaiting quiescence.
+ *
+ * Everything the model's plugin registers (listeners via `ctx.on`, tools via
+ * `harness.registerTool`, services via `ctx.provide`) is an effect on the
+ * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans
+ * it all up through the ordinary cordis lifecycle. The group fiber exists
+ * exactly so the dynamic mounts form ONE subtree, disposed as a unit with
+ * this plugin. Design home:
+ * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
+ *
+ * The vm sandbox guards against ACCIDENTAL global pollution only, and the `ctx`
+ * a mounted plugin's `apply` receives is a WHITELIST façade (register a tool,
+ * observe events, provide/consume services, use timers — framework internals
+ * withheld; see the guard module). Neither is a security boundary: the verbs
+ * the façade DOES expose reach the real runtime unsandboxed (a mounted tool can
+ * shell out through `ctx.bash`), so a deployment loads this plugin as
+ * deliberately as it grants a bash tool. Design home:
+ * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
+ *
+ * Plugin export shape: named exports, NO default. The cordis Loader's
+ * `unwrapExports` does `exports.default ?? exports`, so a stray default would
+ * collapse the module to the bare `apply` and drop `inject`, crashing at load
+ * (see docs/postmortem/0001).
+ *
+ * @module @deepseek-ai/dsh-tool-cordis
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { STATE_LABELS } from './fiber-state.ts'
+import { isPlugin, pluginName } from './guard.ts'
+import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts'
+import { missingServices, mountDynamic } from './mount.ts'
+import type { DynamicMount } from './mount.ts'
+import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts'
+import { createSandbox, evaluateMountCode } from './sandbox.ts'
+
+export const name = 'tool-cordis'
+export const inject = ['tools']
+
+/** Config for the tool-cordis plugin: the sandbox evaluation bound. */
+export interface Config {
+  /**
+   * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm
+   * before evaluation is aborted (default 5000). An async body escapes this
+   * bound — see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance.
+   */
+  vmTimeoutMs?: number
+}
+
+/** Schemastery validator for {@link Config}: `vmTimeoutMs` must be at least 1 (defaults to 5000). */
+export const Config: z<Config> = z.object({
+  vmTimeoutMs: z.number().min(1).default(5000),
+})
+
+/** {@link Config} with every defaulted field present, as schemastery resolves it at load. */
+type ResolvedConfig = Required<Config>
+
+/**
+ * Mount the three cordis tools on `ctx.tools` and create the `cordis-dynamic`
+ * group fiber every dynamic mount hangs under.
+ * @param ctx - the plugin context (`tools` injected).
+ * @param config - the schemastery-resolved {@link Config}.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const { vmTimeoutMs } = config as ResolvedConfig
+  // The one group fiber every dynamic mount hangs under. Mounted here (a child
+  // of this plugin's fiber) so disposing tool-cordis cascades over the whole
+  // dynamic subtree — the ordinary parent→child fiber lifecycle, nothing extra.
+  const group = ctx.plugin({ name: 'cordis-dynamic', apply: () => {} })
+
+  const mounts = new Map<string, DynamicMount>()
+  let nextId = 1
+
+  ctx.tools.register(defineTool({
+    name: 'cordis_inspect',
+    description:
+      'Inspect the live cordis runtime that is running THIS agent. Read-only. '
+      + 'Sections: `services` (every provided ctx service and the plugin fiber that owns it), '
+      + '`plugins` (a flat list of the loaded plugins with their lifecycle states), '
+      + '`tools` (the model-facing tools currently registered, i.e. what you can call), '
+      + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), '
+      + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), '
+      + '`events` (every harness event with its dispatch mode and exact signature — pick listener targets here). '
+      + 'Omit `what` to get all six sections.',
+    parameters: {
+      what: {
+        type: 'string',
+        enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'],
+        description: 'Limit the report to one section. Omit for all sections.',
+      },
+    },
+    execute(args): Promise<{ type: 'text'; text: string }[]> {
+      const sections: [heading: string, body: () => string[]][] = [
+        ['services', () => describeServices(ctx)],
+        ['plugins', () => describePlugins(ctx)],
+        ['tools', () => describeTools(ctx)],
+        ['dynamic', () => describeDynamic(ctx, mounts)],
+        ['api', () => describeApi(ctx)],
+        ['events', () => describeEvents()],
+      ]
+      const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading)
+      const text = selected
+        .map(([heading, body]) => `## ${heading}\n${body().join('\n')}`)
+        .join('\n\n')
+      return Promise.resolve([{ type: 'text', text }])
+    },
+    presentCall: presentInspectCall,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'cordis_mount',
+    description:
+      'Mount a NEW cordis plugin into the live runtime that is running THIS agent '
+      + '(self-modification). `code` runs as the body of an async JavaScript function '
+      + 'in an isolated sandbox and MUST `return` a plugin. Two forms: '
+      + 'FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register '
+      + 'tools, listen to events, and provide services, but reaching ANY service (e.g. '
+      + 'ctx.bash) throws; use it only when you need no services. '
+      + 'OBJECT form `return { name?, inject: [\'bash\', \'llm\', …], apply(ctx) { … } }` '
+      + '— declares dependencies, and cordis activates the plugin only after the '
+      + 'services exist; PREFER this form. You may reach ONLY the services you list in '
+      + 'inject: an undeclared service throws even if it exists, because an undeclared '
+      + 'dependency would not be cleaned up if its provider is unmounted. '
+      + 'BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists '
+      + 'method signatures AND the type shapes of their arguments/returns (do not guess a '
+      + 'field\'s type; e.g. a bash run\'s stdout is an object, not a string). '
+      + 'Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe '
+      + 'events (see cordis_inspect what:"events"), or call '
+      + '`harness.registerTool(ctx, harness.defineTool({ name, description, parameters: '
+      + '{ text: { type: \'string\', required: true } }, async execute(args) { … } }))` '
+      + 'to give yourself a new tool — it becomes callable on your NEXT step. '
+      + 'Tool parameters: each key IS a property — { type: \'string\'|\'number\'|\'boolean\'|\'object\'|\'array\', '
+      + 'required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style '
+      + '{ type: \'object\', properties, required: […] } wrapper and type \'integer\' are also accepted and normalized. A '
+      + 'tool\'s `execute` MUST return an ARRAY of content blocks, e.g. `return '
+      + '[{ type: \'text\', text: someString }]` — never a bare string. '
+      + 'Mounts can COMPOSE: one plugin may `ctx.provide(\'name\', value)` a service and '
+      + 'another may declare `inject: [\'name\']` to consume it — the consumer stays pending '
+      + 'until the provider exists and returns to pending when the provider is unmounted. '
+      + 'Everything registered inside `apply` is cleaned up automatically on unmount. '
+      + 'Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness '
+      + 'terminal), `harness.defineTool`, `harness.registerTool`, '
+      + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`. '
+      + 'Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, '
+      + 'never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect '
+      + 'errors; `process` and `Buffer` are undefined. Instead use inject: [\'fs\'] + ctx.fs for '
+      + 'files, inject: [\'web\'] + ctx.web for HTTP, inject: [\'bash\'] + ctx.bash for processes, '
+      + 'and inject: [\'timer\'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, '
+      + 'auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. '
+      + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). '
+      + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a '
+      + 'trailing `next` callback which MUST be called — returning without `next()` '
+      + 'VETOES the call; prefer plain notification events unless you intend to '
+      + 'intercept. (2) Never await something that only resolves after the current '
+      + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). '
+      + '(3) Your `ctx` is a restricted façade: you can register tools, observe '
+      + 'events, provide/consume services, and use timers, but framework internals '
+      + '(ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a '
+      + 'security boundary though — the services you inject (e.g. ctx.bash) reach the '
+      + 'real runtime.',
+    parameters: {
+      code: {
+        type: 'string',
+        required: true,
+        description: 'Body of an async JS function; must `return` the plugin to mount.',
+      },
+    },
+    async execute(args) {
+      const id = `dyn-${nextId++}`
+      const sandbox = createSandbox(id)
+      const evaluated = await evaluateMountCode(sandbox, args.code, id, vmTimeoutMs)
+      if (!isPlugin(evaluated)) {
+        if (evaluated === undefined) {
+          throw new Error(
+            'mount code returned `undefined` — did you forget `return`?\n'
+            + '  ✓ return (ctx) => { … }\n'
+            + '  ✓ return { name: \'…\', inject: […], apply(ctx) { … } }',
+          )
+        }
+        throw new Error(
+          'mount code must `return` a plugin: a function, or an object with an `apply(ctx)` method',
+        )
+      }
+      const fiber = await mountDynamic(group, evaluated)
+      mounts.set(id, { fiber, pluginName: pluginName(evaluated) })
+      // A settled fiber that is not ACTIVE is waiting on unsatisfied inject —
+      // legal cordis semantics (it activates when the service appears), so keep
+      // it mounted but tell the model what it is waiting for.
+      const missing = missingServices(ctx, fiber)
+      const state = STATE_LABELS[fiber.state]
+      const note = missing.length > 0
+        ? ` — waiting for service(s): ${missing.join(', ')} (activates when provided)`
+        : ''
+      return [{ type: 'text', text: `mounted ${id} (plugin "${pluginName(evaluated)}", state: ${state}${note})` }]
+    },
+    presentCall: presentMountCall,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'cordis_unmount',
+    description:
+      'Dispose a plugin previously mounted with cordis_mount, by id. All its '
+      + 'registrations (event listeners, tools, services) are cleaned up through '
+      + 'the cordis effect lifecycle. Returns only after disposal has fully '
+      + 'completed (quiescence, not just a request to stop).',
+    parameters: {
+      id: {
+        type: 'string',
+        required: true,
+        description: 'The dynamic mount id returned by cordis_mount (e.g. "dyn-1").',
+      },
+    },
+    async execute(args) {
+      const mount = mounts.get(args.id)
+      if (!mount) {
+        throw new Error(`no dynamic plugin with id "${args.id}" (list mounts with cordis_inspect what:"dynamic")`)
+      }
+      await mount.fiber.dispose()
+      mounts.delete(args.id)
+      return [{ type: 'text', text: `unmounted ${args.id} (plugin "${mount.pluginName}")` }]
+    },
+    presentCall: presentUnmountCall,
+  }))
+}

packages/cordis/tool-cordis/src/inspect.ts

@@ -0,0 +1,191 @@
+/**
+ * Read-only renderers over the live runtime for `cordis_inspect`: the service
+ * list, the flat plugin list, the registered tools, the dynamic-mount
+ * table (with per-mount provides/waits), and the catalog-backed `api` /
+ * `events` sections. Every renderer is a pure function of the runtime handles
+ * it receives — no session state, no clock — so inspect output is exactly the
+ * runtime it describes.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/inspect
+ */
+
+import type { Context, Fiber } from 'cordis'
+import { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts'
+import type { EventApiEntry, InheritedApiEntry, ServiceApiEntry, TypeApiEntry } from './api-catalog.ts'
+import { FiberState, STATE_LABELS } from './fiber-state.ts'
+import { missingServices } from './mount.ts'
+import type { DynamicMount } from './mount.ts'
+
+/** The live service registrations from `ctx.reflect.store` (map + filter keeps the possibly-undefined index read branch-free). */
+function liveImpls(ctx: Context): { name: string; fiber: Fiber }[] {
+  const store = ctx.reflect.store
+  return Object.getOwnPropertySymbols(store)
+    .map(key => store[key])
+    .filter((impl): impl is NonNullable<typeof impl> => impl !== undefined)
+}
+
+/** Whether `fiber` is `root` itself or mounted anywhere inside `root`'s subtree. */
+function withinFiber(fiber: Fiber, root: Fiber): boolean {
+  let current = fiber
+  while (true) {
+    if (current === root) return true
+    const parent = current.parent.fiber
+    if (parent === current) return false
+    current = parent
+  }
+}
+
+/** The service names provided by a mount's fiber subtree, sorted. */
+function providedBy(ctx: Context, fiber: Fiber): string[] {
+  return liveImpls(ctx)
+    .filter(impl => withinFiber(impl.fiber, fiber))
+    .map(impl => impl.name)
+    .sort()
+}
+
+/**
+ * The `services` section: every provided ctx service with its owning fiber,
+ * annotating non-active owners with their lifecycle state.
+ * @param ctx - the runtime to enumerate.
+ * @returns one line per service, or a single placeholder line when none are provided.
+ */
+export function describeServices(ctx: Context): string[] {
+  const lines = liveImpls(ctx).map((impl) => {
+    const active = impl.fiber.state === FiberState.ACTIVE
+    return `- ${impl.name} (provided by ${impl.fiber.name}${active ? '' : `, ${STATE_LABELS[impl.fiber.state]}`})`
+  })
+  return lines.length > 0 ? lines : ['(no services provided)']
+}
+
+/**
+ * The `plugins` section: a flat list of every fiber the registry knows, one
+ * line per fiber with its lifecycle state, sorted by plugin name (a plugin
+ * mounted more than once repeats — one line per instance). Dynamic mounts are
+ * listed like any other plugin; their ids live in the `dynamic` section.
+ * @param ctx - the runtime whose registry is enumerated.
+ * @returns one line per loaded plugin fiber.
+ */
+export function describePlugins(ctx: Context): string[] {
+  const fibers: Fiber[] = []
+  for (const runtime of ctx.registry.values()) {
+    for (const fiber of runtime.fibers) fibers.push(fiber)
+  }
+  return fibers
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(fiber => `- ${fiber.name} [${STATE_LABELS[fiber.state]}]`)
+}
+
+/**
+ * The `tools` section: the model-facing tool names currently registered.
+ * @param ctx - the runtime whose tool registry is read.
+ * @returns one line per registered tool.
+ */
+export function describeTools(ctx: Context): string[] {
+  return ctx.tools.schemas().map(schema => `- ${schema.name}`)
+}
+
+/**
+ * The `dynamic` section: one line per mount with id, plugin name, lifecycle
+ * state, the services its subtree provides, and — for a pending mount — the
+ * services it waits for.
+ * @param ctx - the runtime the mounts live in.
+ * @param mounts - the tracked mounts, in mount order.
+ * @returns one line per mount, or a single placeholder line when none exist.
+ */
+export function describeDynamic(ctx: Context, mounts: ReadonlyMap<string, DynamicMount>): string[] {
+  if (mounts.size === 0) return ['(no dynamic plugins mounted)']
+  return [...mounts].map(([id, mount]) => {
+    const provides = providedBy(ctx, mount.fiber)
+    const waiting = missingServices(ctx, mount.fiber)
+    const providesNote = provides.length > 0 ? ` — provides: ${provides.join(', ')}` : ''
+    const waitingNote = waiting.length > 0 ? ` — waiting for: ${waiting.join(', ')}` : ''
+    return `- ${id}: ${mount.pluginName} [${STATE_LABELS[mount.fiber.state]}]${providesNote}${waitingNote}`
+  })
+}
+
+/**
+ * The transitive closure of catalogued type shapes referenced (word-bounded)
+ * by the seed texts — the runtime scoping that keeps the `api` section to the
+ * shapes the LIVE signatures actually mention.
+ */
+function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEntry[] {
+  const included = new Map<string, TypeApiEntry>()
+  let frontier = seeds
+  while (frontier.length > 0) {
+    const next: string[] = []
+    for (const entry of types) {
+      if (included.has(entry.name)) continue
+      const pattern = new RegExp(`\\b${entry.name}\\b`)
+      if (frontier.some(text => pattern.test(text))) {
+        included.set(entry.name, entry)
+        next.push(entry.declaration)
+      }
+    }
+    frontier = next
+  }
+  return [...included.values()].sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * The `api` section: the generated service catalog intersected with the LIVE
+ * runtime — catalogued live services render summary + method signatures, live
+ * services without a catalog entry (e.g. ones another mount provides) render
+ * name + owning fiber, catalog services that are not running are listed
+ * tersely, the type shapes the live signatures reference follow, and the
+ * inherited `ctx` surface closes the section.
+ * @param ctx - the runtime to intersect the catalog with.
+ * @param api - the service catalog (the generated one by default; injectable for tests).
+ * @param inherited - the inherited `ctx` surface lines (generated by default; injectable for tests).
+ * @param types - the type-shape catalog (generated by default; injectable for tests).
+ * @returns the section lines.
+ */
+export function describeApi(
+  ctx: Context,
+  api: readonly ServiceApiEntry[] = SERVICE_API,
+  inherited: readonly InheritedApiEntry[] = INHERITED_CTX_API,
+  types: readonly TypeApiEntry[] = TYPE_API,
+): string[] {
+  const live = new Map<string, string>()
+  for (const impl of liveImpls(ctx)) live.set(impl.name, impl.fiber.name)
+  const lines: string[] = []
+  const liveMethodTexts: string[] = []
+  for (const entry of api) {
+    if (!live.has(entry.key)) continue
+    lines.push(`- ${entry.key} — ${entry.summary}`)
+    for (const method of entry.methods) {
+      lines.push(`    ${method}`)
+      liveMethodTexts.push(method)
+    }
+  }
+  const catalogued = new Set(api.map(entry => entry.key))
+  for (const [name, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!catalogued.has(name)) lines.push(`- ${name} (provided by ${fiber}, no catalog entry)`)
+  }
+  const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key)
+  if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`)
+  const shapes = typeClosure(liveMethodTexts, types)
+  if (shapes.length > 0) {
+    lines.push('type shapes (referenced by the signatures above — read these before assuming a field is a string):')
+    for (const shape of shapes) {
+      for (const declLine of shape.declaration.split('\n')) lines.push(`    ${declLine}`)
+    }
+  }
+  lines.push('inherited ctx API:')
+  for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`)
+  return lines
+}
+
+/**
+ * The `events` section: every harness event with its dispatch mode, one-line
+ * summary, and exact signature, closed by the waterfall caution.
+ * @param events - the event catalog (the generated one by default; injectable for tests).
+ * @returns the section lines.
+ */
+export function describeEvents(events: readonly EventApiEntry[] = EVENT_API): string[] {
+  const lines = events.flatMap(event => [
+    `- ${event.name} [${event.mode}] — ${event.summary}`,
+    `    ${event.signature}`,
+  ])
+  lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.')
+  return lines
+}

packages/cordis/tool-cordis/src/mount.ts

@@ -0,0 +1,64 @@
+/**
+ * Dynamic-mount lifecycle over the `cordis-dynamic` group fiber: settle a
+ * sandbox-produced plugin as a child fiber (never leaving a failed fiber
+ * mounted), and report the services a settled-but-pending fiber still waits
+ * for. Disposal needs no helper — a mount unwinds through an ordinary awaited
+ * `fiber.dispose()`, because everything the plugin registered is an effect on
+ * its fiber.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/mount
+ */
+
+import type { Context, Fiber, Plugin } from 'cordis'
+import { guardedPlugin } from './guard.ts'
+
+/** One tracked dynamic mount: the fiber plus the display name captured at mount time. */
+export interface DynamicMount {
+  /** The child fiber under the `cordis-dynamic` group. */
+  fiber: Fiber
+  /** The plugin's display name at mount time (its `name`, else `<anonymous>`). */
+  pluginName: string
+}
+
+/**
+ * Mount a plugin under the group fiber and settle it. The group fiber loads
+ * asynchronously right after the owning plugin's `apply`, so it is awaited
+ * before hanging a child off its context. The child fiber's `await()` settles
+ * its lifecycle work and rethrows a startup error (e.g. a throwing `apply`);
+ * on error the fiber is disposed first — a failed mount never lingers.
+ * @param group - the `cordis-dynamic` group fiber every mount hangs under.
+ * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before mounting.
+ * @returns the settled child fiber (possibly pending on unsatisfied `inject`).
+ */
+export async function mountDynamic(group: Fiber, plugin: Plugin): Promise<Fiber> {
+  await group.await()
+  const fiber = group.ctx.plugin(guardedPlugin(plugin))
+  try {
+    await fiber.await()
+  } catch (error) {
+    await fiber.dispose()
+    const message = error instanceof Error ? error.message : String(error)
+    // The commonest startup collision is remounting a NEW version of a tool
+    // while the old mount still holds the name — teach the replace recipe.
+    if (message.includes('already registered')) {
+      throw new Error(
+        `${message} — to REPLACE something an earlier mount registered, first cordis_unmount that mount's id `
+        + '(find it with cordis_inspect what:"dynamic"), then mount the new version.',
+      )
+    }
+    throw error instanceof Error ? error : new Error(message)
+  }
+  return fiber
+}
+
+/**
+ * The services a fiber declared in `inject` that do not exist yet — a settled
+ * fiber that is not active is waiting on exactly these (legal cordis
+ * semantics: it activates when the service appears).
+ * @param ctx - the context to resolve service existence against.
+ * @param fiber - the mount fiber whose `inject` declarations are checked.
+ * @returns the missing service names, in declaration order.
+ */
+export function missingServices(ctx: Context, fiber: Fiber): string[] {
+  return Object.keys(fiber.inject).filter(service => ctx.get(service) === undefined)
+}

packages/cordis/tool-cordis/src/present.ts

@@ -0,0 +1,51 @@
+/**
+ * ACP render intents for the three cordis tools — all `generic` cards, decided
+ * up front as part of the tool design. Presenters are pure functions of the
+ * call arguments (they run on replay too): no I/O, no session state, no clock.
+ * No `presentResult` overrides exist — the tools' text results are their
+ * correct completed rendering.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/present
+ */
+
+import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+
+/**
+ * The `cordis_inspect` call card: a read, titled with the requested section.
+ * @param args - the validated call arguments.
+ * @returns the generic card the ACP bridge renders.
+ */
+export function presentInspectCall(args: { what?: string }): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'read',
+    title: args.what === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${args.what}`,
+  }
+}
+
+/**
+ * The `cordis_mount` call card: an execute carrying the mount code as raw input.
+ * @param args - the validated call arguments.
+ * @returns the generic card the ACP bridge renders.
+ */
+export function presentMountCall(args: { code: string }): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'execute',
+    title: 'Mount plugin into live cordis runtime',
+    rawInput: { code: args.code },
+  }
+}
+
+/**
+ * The `cordis_unmount` call card: a delete, titled with the mount id.
+ * @param args - the validated call arguments.
+ * @returns the generic card the ACP bridge renders.
+ */
+export function presentUnmountCall(args: { id: string }): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'delete',
+    title: `Unmount ${args.id}`,
+  }
+}

packages/cordis/tool-cordis/src/sandbox.ts

@@ -0,0 +1,201 @@
+/**
+ * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose
+ * globals are a tagged write-through console, the `harness` registration
+ * helpers, the encoding primitives a bare vm context lacks, and callable traps
+ * over the Node APIs the sandbox deliberately withholds. Capability access is
+ * routed through cordis services, never Node built-ins: filesystem work goes
+ * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`,
+ * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount)
+ * — so a well-behaved mount stays inspectable and disposable. That routing is
+ * STEERING toward the cordis services, not containment: the sandbox guards
+ * against ACCIDENTAL global pollution, and it is not a security boundary. The
+ * host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are
+ * reachable functions, so a mount that goes looking — e.g. through such a
+ * helper's `.constructor` — can still reach the host realm; that is accepted,
+ * because the `ctx` a mounted plugin's `apply` later receives is the real,
+ * fully privileged runtime handle, and that is the point of the toolset.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/sandbox
+ */
+
+import { createContext, runInContext } from 'node:vm'
+import { sandboxDefineTool, sandboxRegisterTool } from './guard.ts'
+
+/**
+ * A write-through console for one sandbox, tagging every line with the mount
+ * id. Write-through (host stdout/stderr), NOT buffered into the tool result:
+ * a mounted listener fires long after the mount call returned, and its output
+ * must land somewhere the user can see — for the stdio demo, the terminal.
+ */
+function taggedConsole(id: string): Record<'log' | 'info' | 'warn' | 'error' | 'debug', (...args: unknown[]) => void> {
+  const tag = `[cordis:${id}]`
+  const log = (...args: unknown[]): void => { console.log(tag, ...args) }
+  const error = (...args: unknown[]): void => { console.error(tag, ...args) }
+  return { log, info: log, warn: log, debug: log, error }
+}
+
+/**
+ * Per-sandbox prelude: give the vm realm's own constructors a
+ * `Symbol.hasInstance` that checks BOTH realms. Model code runs against a
+ * fresh vm realm, but most objects it touches are HOST-realm (the `args` a
+ * tool's `execute` receives, event payloads a listener observes, service
+ * return values), so a plain `x instanceof Array` / `instanceof Object` in
+ * sandbox code would silently be false. The patch replaces each vm
+ * constructor's own `[Symbol.hasInstance]` with "ordinary check against the
+ * vm constructor OR the host counterpart" — the ordinary algorithm is a pure
+ * prototype-chain walk, so calling it with the host constructor as receiver
+ * needs no host-side change. ONLY vm-realm globals are modified; host
+ * intrinsics are passed in as values and never touched.
+ */
+const DUAL_REALM_INSTANCEOF_PRELUDE = `
+(hostIntrinsics) => {
+  'use strict'
+  const ordinary = Function.prototype[Symbol.hasInstance]
+  for (const name of Object.keys(hostIntrinsics)) {
+    const VmCtor = globalThis[name]
+    const HostCtor = hostIntrinsics[name]
+    if (typeof VmCtor !== 'function' || typeof HostCtor !== 'function') continue
+    Object.defineProperty(VmCtor, Symbol.hasInstance, {
+      value: (instance) => ordinary.call(VmCtor, instance) || ordinary.call(HostCtor, instance),
+      configurable: true,
+    })
+  }
+}
+`
+
+/** Run {@link DUAL_REALM_INSTANCEOF_PRELUDE} in a freshly created sandbox, handing it the host intrinsics to pair up. */
+function patchDualRealmInstanceof(sandbox: object): void {
+  const patch = runInContext(DUAL_REALM_INSTANCEOF_PRELUDE, sandbox) as (intrinsics: Record<string, unknown>) => void
+  patch({ Object, Array, Function, Error, TypeError, RangeError, SyntaxError, Promise, RegExp, Date, Map, Set })
+}
+
+const TIMER_REDIRECT
+  = 'Node timers are unavailable. Use the cordis timer service instead: declare inject: [\'timer\'] on your plugin '
+    + 'and call ctx.setTimeout / ctx.setInterval — those are fiber effects, cleaned up automatically on unmount.'
+
+/**
+ * The callable Node APIs the sandbox deliberately disables, each mapped to the
+ * cordis alternative its trap error names. Only FUNCTION-shaped globals are
+ * trapped — a data-shaped global like `process` stays `undefined`, because a
+ * throwing accessor would detonate the common `typeof process` feature probe
+ * at resolution time.
+ */
+const NODE_API_REDIRECTS: Record<string, string> = {
+  require:
+    'Node modules are unavailable. Use the cordis services on ctx instead — e.g. inject: [\'fs\'] for files, '
+    + '[\'web\'] for HTTP, [\'bash\'] for processes; cordis_inspect what:"api" lists what THIS runtime provides.',
+  setTimeout: TIMER_REDIRECT,
+  setInterval: TIMER_REDIRECT,
+  setImmediate: TIMER_REDIRECT,
+  clearTimeout: TIMER_REDIRECT,
+  clearInterval: TIMER_REDIRECT,
+  fetch:
+    'Network access goes through the cordis web service: declare inject: [\'web\'] and call ctx.web '
+    + '(see cordis_inspect what:"api" for its methods).',
+}
+
+/** Build the trap functions for {@link NODE_API_REDIRECTS}: calling one throws the redirect. */
+function nodeApiTraps(): Record<string, () => never> {
+  const traps: Record<string, () => never> = {}
+  for (const [name, redirect] of Object.entries(NODE_API_REDIRECTS)) {
+    traps[name] = () => {
+      throw new Error(`${name} is not available in the mount sandbox — ${redirect}`)
+    }
+  }
+  return traps
+}
+
+/**
+ * Build the vm context one `cordis_mount` call evaluates in: the tagged
+ * console, the `harness` registration helpers, the encoding primitives, the
+ * Node-API traps, and the dual-realm `instanceof` patch, already
+ * `createContext`-ed.
+ * @param id - the mount id (`dyn-<n>`), used as the console tag and filename stem.
+ * @returns the contextified sandbox object to pass to {@link evaluateMountCode}.
+ */
+export function createSandbox(id: string): object {
+  const sandbox = {
+    ...nodeApiTraps(),
+    console: taggedConsole(id),
+    harness: { defineTool: sandboxDefineTool, registerTool: sandboxRegisterTool },
+    // Web APIs absent from fresh vm contexts — made available so the model
+    // can encode/decode base64 without Buffer (which is also absent). Host
+    // closures over Buffer, never Buffer itself.
+    btoa: (s: string) => Buffer.from(s, 'utf-8').toString('base64'),
+    atob: (s: string) => Buffer.from(s, 'base64').toString('utf-8'),
+    TextEncoder,
+    TextDecoder,
+  }
+  createContext(sandbox)
+  patchDualRealmInstanceof(sandbox)
+  return sandbox
+}
+
+/**
+ * Cross-realm SyntaxError detection: a compile failure inside `runInContext`
+ * constructs its error in the SANDBOX realm, so a host `instanceof
+ * SyntaxError` is silently false — the `name` property is the realm-safe tag.
+ */
+function isSyntaxError(error: unknown): error is Error {
+  return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'SyntaxError'
+}
+
+/**
+ * The parse-failure context a vm `SyntaxError` carries: the vm prints the
+ * offending source line and a caret before the message, which is exactly what
+ * a model needs to self-correct — surface it instead of the bare message.
+ * Falls back to `String(error)` when the stack carries no such prelude.
+ * @param error - the `SyntaxError` (host- or sandbox-realm) thrown while compiling mount code.
+ * @returns the stack prefix up to and including the `SyntaxError: …` line.
+ */
+export function syntaxErrorContext(error: Error): string {
+  const lines = (error.stack ?? '').split('\n')
+  const messageIndex = lines.findIndex(line => line.startsWith('SyntaxError'))
+  if (messageIndex === -1) return String(error)
+  return lines.slice(0, messageIndex + 1).join('\n')
+}
+
+/**
+ * Evaluate mount code as the body of an async function inside the sandbox.
+ * `vmTimeoutMs` only bounds the SYNCHRONOUS portion; an async body escapes it
+ * — acceptable under the module's trust stance. A parse failure is answered
+ * with the offending line + caret and a teaching hint: TypeScript syntax on
+ * the failing line gets the remove-annotations fix, anything else gets the
+ * function-body/bracket-balance reminder (models habitually close the returned
+ * plugin object with `});` as if it were a callback argument).
+ * @param sandbox - the contextified object from {@link createSandbox}.
+ * @param code - the model-written function body; must `return` a plugin.
+ * @param id - the mount id, used as the vm filename (`cordis-mount-<id>.js`).
+ * @param vmTimeoutMs - the synchronous evaluation bound in milliseconds.
+ * @returns whatever the code returned, still un-narrowed (the mount lifecycle checks plugin shape).
+ */
+export async function evaluateMountCode(sandbox: object, code: string, id: string, vmTimeoutMs: number): Promise<unknown> {
+  try {
+    return await runInContext(
+      `(async () => {\n${code}\n})()`,
+      sandbox,
+      { filename: `cordis-mount-${id}.js`, timeout: vmTimeoutMs },
+    )
+  } catch (error) {
+    if (!isSyntaxError(error)) throw error
+    const context = syntaxErrorContext(error)
+    // Scope the TypeScript heuristic to the OFFENDING line, not the whole
+    // code: an ` as ` inside an ordinary description string must not turn a
+    // plain syntax error into a misleading remove-annotations message.
+    const offendingLine = context.split('\n')[1] ?? ''
+    if (/\bas\b/.test(offendingLine)) {
+      throw new Error(
+        `mount code failed to parse:\n${context}\n`
+        + 'The sandbox runs plain JavaScript, not TypeScript. Remove type annotations:\n'
+        + '  ✗ { type: \'text\' as const, text: x }\n'
+        + '  ✓ { type: \'text\', text: x }',
+      )
+    }
+    throw new Error(
+      `mount code failed to parse:\n${context}\n`
+      + 'Note: `code` runs as the BODY of an async function (line numbers are offset by the 1-line wrapper). '
+      + 'Check bracket balance — ending the returned plugin object with `});` closes a call that was never opened; '
+      + 'a plain `return { … }` ends with `}` (an optional `;`), never `)`.',
+    )
+  }
+}

packages/cordis/tool-cordis/tests/cross-mount.spec.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest'
+import { call, CONSUMER_CODE, PROVIDER_CODE, setup, text } from './helpers.ts'
+
+/**
+ * Cross-mount composition through ordinary cordis provide/inject semantics:
+ * one mount provides a service, another injects it, and mount ids stay the
+ * lifecycle handles. Every assertion is against the WORLD — the registry, the
+ * service store, real tool dispatch — not the tool's own summary line.
+ */
+
+describe('cross-mount provide/inject', () => {
+  it('provider first: the consumer activates immediately and its tool reaches the provided service', async () => {
+    const ctx = await setup()
+    const provider = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
+    expect(text(provider)).toContain('state: active')
+
+    const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })
+    expect(consumer.isError).toBe(false)
+    expect(text(consumer)).toContain('state: active')
+
+    // The vm-realm service value is callable across mounts, and the result
+    // normalizes into the host realm like any dynamic tool result.
+    const greeted = await call(ctx, 'greet', { name: 'harness' })
+    expect(greeted.isError).toBe(false)
+    expect(text(greeted)).toBe('hi harness')
+  })
+
+  it('consumer first: stays pending naming the missing service, then activates when the provider mounts', async () => {
+    const ctx = await setup()
+    const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })
+    expect(consumer.isError).toBe(false)
+    expect(text(consumer)).toContain('state: pending')
+    expect(text(consumer)).toContain('waiting for service(s): greeter')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('waiting for: greeter')
+    expect(ctx.tools.get('greet')).toBeUndefined()
+
+    await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
+    expect(ctx.tools.get('greet')).toBeDefined()
+    expect(text(await call(ctx, 'greet', { name: 'late' }))).toBe('hi late')
+  })
+
+  it('unmounting the provider sends the consumer back to pending and unwinds its registrations', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })   // dyn-1
+    await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })   // dyn-2
+    expect(ctx.tools.get('greet')).toBeDefined()
+
+    const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
+    expect(unmounted.isError).toBe(false)
+    expect(ctx.tools.get('greet')).toBeUndefined()
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))
+    expect(report).toContain('dyn-2: greeter-consumer [pending] — waiting for: greeter')
+  })
+
+  it('re-providing the service re-runs the consumer through the same guard (active again, tool back)', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })   // dyn-1
+    await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })   // dyn-2
+    await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
+    expect(ctx.tools.get('greet')).toBeUndefined()
+
+    await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })   // dyn-3
+    expect(ctx.tools.get('greet')).toBeDefined()
+    expect(text(await call(ctx, 'greet', { name: 'again' }))).toBe('hi again')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-2: greeter-consumer [active]')
+  })
+
+  it('a duplicate provide fails loud with the owning fiber named, and the failed mount is disposed', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
+    const duplicate = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
+    expect(duplicate.isError).toBe(true)
+    expect(text(duplicate)).toContain('has been registered')
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))
+    expect(report).toContain('dyn-1: greeter-provider')
+    expect(report).not.toContain('dyn-2')
+  })
+
+  it('inspect surfaces the linkage: provides on the provider row, the service in services and api sections', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })
+    await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })
+
+    const dynamic = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))
+    expect(dynamic).toContain('dyn-1: greeter-provider [active] — provides: greeter')
+
+    const services = text(await call(ctx, 'cordis_inspect', { what: 'services' }))
+    expect(services).toContain('- greeter (provided by greeter-provider)')
+
+    const api = text(await call(ctx, 'cordis_inspect', { what: 'api' }))
+    expect(api).toContain('- greeter (provided by greeter-provider, no catalog entry)')
+  })
+
+  it('a primitive (or null) provided value passes through the façade unwrapped, on both read paths', async () => {
+    const ctx = await setup()
+    const provider = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'answer-provider',
+          apply(ctx) {
+            ctx.provide('answer', 42)
+            ctx.provide('nothing', null)
+          },
+        }
+      `,
+    })
+    expect(provider.isError).toBe(false)
+
+    const consumer = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'answer-consumer',
+          inject: ['answer', 'nothing', 'tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'answer',
+              description: 'Read the provided primitive services.',
+              parameters: {},
+              async execute() {
+                return [{ type: 'text', text: ctx.answer + '/' + ctx.get('answer') + '/' + ctx.nothing }]
+              },
+            }))
+          },
+        }
+      `,
+    })
+    expect(consumer.isError).toBe(false)
+    expect(text(consumer)).toContain('state: active')
+    expect(text(await call(ctx, 'answer', {}))).toBe('42/42/null')
+  })
+
+  it('unmounting the consumer leaves the provider and its service intact', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: PROVIDER_CODE })   // dyn-1
+    await call(ctx, 'cordis_mount', { code: CONSUMER_CODE })   // dyn-2
+    await call(ctx, 'cordis_unmount', { id: 'dyn-2' })
+
+    expect(ctx.tools.get('greet')).toBeUndefined()
+    const services = text(await call(ctx, 'cordis_inspect', { what: 'services' }))
+    expect(services).toContain('- greeter (provided by greeter-provider)')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-1: greeter-provider [active]')
+  })
+})

packages/cordis/tool-cordis/tests/helpers.ts

@@ -0,0 +1,104 @@
+import { Context } from 'cordis'
+import Timer from '@cordisjs/plugin-timer'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import type { ToolDefinition, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import * as tool from '../src/index.ts'
+
+/**
+ * Shared spec helpers: a real `SystemPrompt` + `ToolRegistry` + timer +
+ * tool-cordis tree (only the model is absent — the code strings below stand in
+ * for what it would write), plus the canonical mount-code fixtures the suites
+ * share.
+ */
+
+/** Mount the plugin on a fresh context with a real ToolRegistry and the timer service. */
+export async function setup(config?: tool.Config): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(Timer)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(tool, config)
+  return ctx
+}
+
+let callCounter = 0
+
+/** Execute a registered tool through the real registry pipeline. */
+export function call(ctx: Context, name: string, args: unknown): Promise<ToolExecutionResult> {
+  return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args })
+}
+
+/** Concatenated text blocks of one tool result. */
+export function text(result: ToolExecutionResult): string {
+  return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+/** Mount code for a listener plugin: logs on every `tools/change`. */
+export const LISTENER_CODE = `
+  return {
+    name: 'change-logger',
+    apply(ctx) {
+      ctx.on('tools/change', () => console.log('tools changed'))
+    },
+  }
+`
+
+/** Mount code for a self-made tool: registers `reverse_text` via the sandbox's harness helpers. */
+export const REVERSE_TOOL_CODE = `
+  return {
+    name: 'reverse-text',
+    inject: ['tools'],
+    apply(ctx) {
+      harness.registerTool(ctx, harness.defineTool({
+        name: 'reverse_text',
+        description: 'Reverse a string.',
+        parameters: { text: { type: 'string', required: true } },
+        async execute(args) {
+          return [{ type: 'text', text: args.text.split('').reverse().join('') }]
+        },
+      }))
+    },
+  }
+`
+
+/** Mount code providing a `greeter` service other mounts can inject. */
+export const PROVIDER_CODE = `
+  return {
+    name: 'greeter-provider',
+    apply(ctx) {
+      ctx.provide('greeter', { greet: (name) => 'hi ' + name })
+    },
+  }
+`
+
+/** Mount code consuming the `greeter` service through inject, exposing it as a tool. */
+export const CONSUMER_CODE = `
+  return {
+    name: 'greeter-consumer',
+    inject: ['greeter', 'tools'],
+    apply(ctx) {
+      harness.registerTool(ctx, harness.defineTool({
+        name: 'greet',
+        description: 'Greet someone via the greeter service.',
+        parameters: { name: { type: 'string', required: true } },
+        async execute(args) {
+          return [{ type: 'text', text: ctx.greeter.greet(args.name) }]
+        },
+      }))
+    },
+  }
+`
+
+/** A registrable no-op tool the tests use to trigger a real `tools/change`. */
+export function dummyTool(name: string): ToolDefinition {
+  return {
+    name,
+    description: 'test trigger',
+    parameters: { type: 'object' as const, properties: {} },
+    async execute(): Promise<[]> {
+      return []
+    },
+  }
+}

packages/cordis/tool-cordis/tests/inspect.spec.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest'
+import type { Context, Fiber } from 'cordis'
+import { FiberState } from '../src/fiber-state.ts'
+import { describeApi, describeEvents, describePlugins, describeServices } from '../src/inspect.ts'
+import { call, LISTENER_CODE, setup, text } from './helpers.ts'
+
+/**
+ * The `cordis_inspect` sections: rendered against the real runtime through the
+ * tool, plus direct renderer calls for the states a minimal harness cannot
+ * reach (empty service store, same-named sibling fibers, a fully-live catalog).
+ */
+
+describe('cordis_inspect', () => {
+  it('reports all six sections by default', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_inspect', {})
+    expect(result.isError).toBe(false)
+    const report = text(result)
+    for (const heading of ['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) {
+      expect(report).toContain(`## ${heading}`)
+    }
+    // The services section sees the real providers; the plugins list shows
+    // this plugin and its dynamic group flat; the tools section lists the
+    // cordis tools.
+    expect(report).toContain('- tools (provided by ToolRegistry)')
+    expect(report).toContain('- tool-cordis [active]')
+    expect(report).toContain('- cordis-dynamic [active]')
+    expect(report).toContain('- cordis_mount')
+    expect(report).toContain('(no dynamic plugins mounted)')
+  })
+
+  it('limits the report to one section via `what`', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_inspect', { what: 'tools' })
+    const report = text(result)
+    expect(report).toContain('## tools')
+    expect(report).not.toContain('## services')
+    expect(report).not.toContain('## plugins')
+  })
+
+  it('shows a mount in the dynamic section and in the flat plugins list', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
+    const report = text(await call(ctx, 'cordis_inspect', {}))
+    expect(report).toContain('- dyn-1: change-logger [active]')
+    expect(report).toContain('- change-logger [active]')
+  })
+
+  it('renders the api section from the generated catalog intersected with the LIVE runtime', async () => {
+    const ctx = await setup()
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'api' }))
+    // Live catalogued services render summary + signatures.
+    expect(report).toContain('- tools — ')
+    expect(report).toContain('register(definition: ToolDefinition)')
+    expect(report).toContain('- systemPrompt — ')
+    // Catalogued services with no live provider are listed tersely.
+    expect(report).toMatch(/not running \(loadable services with no live provider\): .*bash/)
+    // The type shapes the LIVE signatures reference follow (closure over the
+    // generated TYPE_API — a consumer can see field types, not just names).
+    expect(report).toContain('type shapes (referenced by the signatures above')
+    expect(report).toContain('export interface ToolExecution')
+    // A type only reachable through a NOT-live service (e.g. bash) is scoped out.
+    expect(report).not.toContain('export interface BashRunResult')
+    // The inherited ctx surface closes the section.
+    expect(report).toContain('inherited ctx API:')
+    expect(report).toContain('- ctx.effect — ')
+  })
+
+  it('renders the events section with mode badges, signatures, and the waterfall caution', async () => {
+    const ctx = await setup()
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'events' }))
+    expect(report).toContain('- tools/change [emit]')
+    expect(report).toContain('- tools/pre-execute [waterfall]')
+    expect(report).toMatch(/'agent\/status'\(/)
+    expect(report).toContain('returning without next() vetoes the chain')
+  })
+})
+
+describe('inspect renderers (direct)', () => {
+  it('describeServices reports an empty store as such, and labels a non-active provider', () => {
+    const empty = { reflect: { store: {} } } as unknown as Context
+    expect(describeServices(empty)).toEqual(['(no services provided)'])
+
+    const pendingFiber = { state: FiberState.PENDING, name: 'half-loaded' } as unknown as Fiber
+    const store: Record<symbol, unknown> = {}
+    store[Symbol('impl')] = { name: 'thing', fiber: pendingFiber }
+    const ctx = { reflect: { store } } as unknown as Context
+    expect(describeServices(ctx)).toEqual(['- thing (provided by half-loaded, pending)'])
+  })
+
+  it('describePlugins lists every fiber flat, sorted by name, one line per instance', () => {
+    const fiber = (name: string): Fiber => ({ name, state: FiberState.ACTIVE }) as unknown as Fiber
+    const ctx = {
+      registry: { values: () => [{ fibers: [fiber('beta'), fiber('alpha')] }, { fibers: [fiber('alpha')] }] },
+    } as unknown as Context
+    expect(describePlugins(ctx)).toEqual([
+      '- alpha [active]',
+      '- alpha [active]',
+      '- beta [active]',
+    ])
+  })
+
+  it('describeApi omits the not-running line and type shapes when nothing applies', async () => {
+    const ctx = await setup()
+    const lines = describeApi(ctx, [{ key: 'tools', summary: 'The registry.', methods: ['register(x): void'] }], [], [])
+    expect(lines[0]).toBe('- tools — The registry.')
+    expect(lines[1]).toBe('    register(x): void')
+    expect(lines.join('\n')).not.toContain('not running')
+    expect(lines.join('\n')).not.toContain('type shapes')
+  })
+
+  it('describeEvents renders an empty catalog as just the waterfall caution', () => {
+    expect(describeEvents([])).toEqual([
+      'waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.',
+    ])
+  })
+})

packages/cordis/tool-cordis/tests/integration.spec.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+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, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import * as ToolCordis from '../src/index.ts'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import { REVERSE_TOOL_CODE } from './helpers.ts'
+
+/**
+ * Full-loop integration: a scripted mock model mounts a plugin that registers
+ * a NEW tool, calls that tool on the very next step (tool schemas are
+ * reassembled per step — the real loop proves the self-extension contract),
+ * and unmounts it again. Only the model is mocked; the sandbox, the fiber
+ * tree, and the session log are real.
+ */
+
+async function harness(adapter: MockAdapter): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(ToolCordis)
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+describe('cordis tools through the agent loop', () => {
+  it('mounts a tool, calls it on the next step, and unmounts it — all as real tool/call events', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('call-1', 'cordis_mount', { code: REVERSE_TOOL_CODE }, 'Extending myself.'),
+      toolCallResponse('call-2', 'reverse_text', { text: 'harness' }),
+      toolCallResponse('call-3', 'cordis_unmount', { id: 'dyn-1' }),
+      textResponse('Done.'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('it-cordis'), { model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
+    await waitForIdle(ctx, agent)
+
+    const log = agent.session.events
+    const calls = log.filter(event => event.type === 'tool/call').map(event => event.data.name)
+    expect(calls).toEqual(['cordis_mount', 'reverse_text', 'cordis_unmount'])
+
+    const results = log.filter(event => event.type === 'tool/result')
+    expect(results.map(event => event.data.isError)).toEqual([false, false, false])
+    const reversed = results[1]!.data.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    expect(reversed).toBe('ssenrah')
+
+    // After the unmount the self-made tool is gone from the registry.
+    expect(ctx.tools.get('reverse_text')).toBeUndefined()
+  })
+})

packages/cordis/tool-cordis/tests/mount.spec.ts

@@ -0,0 +1,575 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { isJsonValue } from '@deepseek-ai/dsh-session'
+import { syntaxErrorContext } from '../src/sandbox.ts'
+import { call, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts'
+
+/**
+ * The `cordis_mount` success/failure family: real plugins land on a genuine
+ * cordis fiber tree, their registrations are observable through the real
+ * registry/event bus, and every rejection path teaches the fix.
+ */
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('cordis_mount', () => {
+  it('mounts a listener plugin that observes real events, tagged-logging through to the host console', async () => {
+    const ctx = await setup()
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    const result = await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('mounted dyn-1 (plugin "change-logger", state: active)')
+
+    // Fire a REAL tools/change by registering a tool; the mounted listener logs.
+    ctx.tools.register(dummyTool('trigger_a'))
+    expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'tools changed')
+  })
+
+  it('mounts a bare-function plugin as <anonymous>, and a named function under its name', async () => {
+    const ctx = await setup()
+    const anonymous = await call(ctx, 'cordis_mount', { code: 'return (ctx) => { ctx.on(\'tools/change\', () => {}) }' })
+    expect(anonymous.isError).toBe(false)
+    expect(text(anonymous)).toContain('plugin "<anonymous>"')
+    const named = await call(ctx, 'cordis_mount', { code: 'return function watcher(ctx) {}' })
+    expect(text(named)).toContain('plugin "watcher"')
+  })
+
+  it('lets the agent give ITSELF a new tool, immediately callable through the registry', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE })
+    expect(result.isError).toBe(false)
+
+    expect(ctx.tools.schemas().map(schema => schema.name)).toContain('reverse_text')
+    const reversed = await call(ctx, 'reverse_text', { text: 'harness' })
+    expect(reversed.isError).toBe(false)
+    expect(text(reversed)).toBe('ssenrah')
+  })
+
+  it('normalizes a self-made tool\'s result into the host realm, so the session log accepts it', async () => {
+    // The model's execute builds its content blocks INSIDE the vm, where
+    // Object.prototype is a different object — dsh-session's isJsonValue (the
+    // gate every `tool/result` append runs through) compares prototype
+    // IDENTITY, so a raw foreign-realm result would error the whole turn the
+    // first time the self-made tool runs. harness.defineTool round-trips the
+    // return into host-realm JSON before it reaches the registry.
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE })
+    const reversed = await call(ctx, 'reverse_text', { text: 'harness' })
+    expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true)
+  })
+
+  it('threads the { content, meta } object return form through to the registry result', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'meta-return',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'meta_tool',
+              description: 'attaches a private presentation payload',
+              parameters: {},
+              async execute() {
+                return { content: [{ type: 'text', text: 'ok' }], meta: { kind: 'demo' } }
+              },
+            }))
+          },
+        }
+      `,
+    })
+    const result = await call(ctx, 'meta_tool', {})
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe('ok')
+    expect(result.meta).toEqual({ kind: 'demo' })
+  })
+
+  it.each([
+    ['a bare string', 'return \'ok\'', '"ok"'],
+    ['an object whose content is a string', 'return { content: \'ok\' }', '{"content":"ok"}'],
+    ['an array of non-objects', 'return [\'ok\']', '["ok"]'],
+    ['blocks missing the type tag', 'return [{ text: \'hi\' }]', '[{"text":"hi"}]'],
+    ['object-form blocks missing the type tag', 'return { content: [{ text: \'hi\' }] }', '{"content":[{"text":"hi"}]}'],
+    ['undefined — a forgotten return', 'return undefined', 'undefined'],
+  ])('rejects an execute return of %s as that one call\'s teaching error', async (_label, returnStatement, preview) => {
+    // The failure this prevents: the registry trusts the return shape
+    // (postExecute spreads result.content), so an unvalidated { content: 'ok' }
+    // would enter the session log as ['o','k'] and silently corrupt the next
+    // model request. The shape check turns it into THIS call's error instead —
+    // one well-formed text block the log and the model can digest.
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'bad-return',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'bad_return_tool',
+              description: 'returns a wrong shape',
+              parameters: {},
+              async execute() { ${returnStatement} },
+            }))
+          },
+        }
+      `,
+    })
+    const result = await call(ctx, 'bad_return_tool', {})
+    expect(result.isError).toBe(true)
+    expect(result.content).toHaveLength(1)
+    expect(result.content[0]!.type).toBe('text')
+    expect(text(result)).toContain(`execute returned ${preview}`)
+    expect(text(result)).toContain('must return an ARRAY of content blocks')
+    expect(text(result)).toContain('✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }')
+  })
+
+  it('truncates a huge invalid execute return in the teaching error', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'huge-return',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'huge_return_tool',
+              description: 'returns a huge wrong shape',
+              parameters: {},
+              async execute() { return 'x'.repeat(500) },
+            }))
+          },
+        }
+      `,
+    })
+    const result = await call(ctx, 'huge_return_tool', {})
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('…')
+    expect(text(result)).not.toContain('x'.repeat(200))
+  })
+
+  it('accepts a JSON-Schema-style parameters wrapper and normalizes it to the DSL', async () => {
+    // The dialect models write by strong prior: the { type:'object',
+    // properties, required: […] } wrapper, `type: 'integer'`, and
+    // `required: false`. All of it has exactly one meaning — normalize instead
+    // of burning a model turn on a lecture.
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'json-schema-tool',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'json_schema_tool',
+              description: 'written in the JSON-Schema dialect',
+              parameters: {
+                type: 'object',
+                properties: {
+                  text: { type: 'string', description: 'the text' },
+                  count: { type: 'integer', default: 1 },
+                  mode: { type: 'string', enum: ['fast', 'slow'] },
+                  extra: { type: 'string', required: false },
+                },
+                required: ['text'],
+              },
+              async execute(args) { return [{ type: 'text', text: args.text + ':' + (args.count ?? 0) }] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+
+    // The registered schema is canonical JSON Schema derived from the DSL:
+    // the required array survived, integer became number, extra is optional.
+    const schema = ctx.tools.schemas().find(s => s.name === 'json_schema_tool')!
+    const parameters = schema.parameters as { properties: Record<string, { type: string; enum?: string[] }>; required?: string[] }
+    expect(parameters.required).toEqual(['text'])
+    expect(parameters.properties.count!.type).toBe('number')
+    expect(parameters.properties.mode!.enum).toEqual(['fast', 'slow'])
+    // Arg validation enforces the normalized spec: text required, extra not.
+    expect((await call(ctx, 'json_schema_tool', { count: 2 })).isError).toBe(true)
+    expect(text(await call(ctx, 'json_schema_tool', { text: 'ok', count: 2 }))).toBe('ok:2')
+  })
+
+  it('normalizes a nested object property carrying a JSON-Schema required array', async () => {
+    // On an object PROPERTY, a JSON-Schema-style `required` array names the
+    // required children — the nested unwrap converts it just like the top level.
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'nested-json-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'nested_json_schema_tool',
+              description: 'nested dialect',
+              parameters: {
+                cfg: { type: 'object', properties: { label: { type: 'string' } }, required: ['label'] },
+              },
+              async execute(args) { return [{ type: 'text', text: args.cfg.label }] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    const schema = ctx.tools.schemas().find(s => s.name === 'nested_json_schema_tool')!
+    const cfg = (schema.parameters as { properties: { cfg: { required?: string[] } } }).properties.cfg
+    expect(cfg.required).toEqual(['label'])
+    expect(text(await call(ctx, 'nested_json_schema_tool', { cfg: { label: 'hi' } }))).toBe('hi')
+  })
+
+  it.each([
+    ['parameters: 42', 'must be a SchemaSpec object'],
+    ['parameters: { text: 42 }', 'parameters.text must be a SchemaSpec property object'],
+    ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type: \'string\' | \'number\' | \'boolean\' | \'object\' | \'array\' (got "str")'],
+    ['parameters: { text: { type: \'string\', required: \'yes\' } }', 'parameters.text.required must be a boolean when present'],
+    ['parameters: { text: { type: \'string\', properties: {} } }', 'parameters.text.properties is only valid for type "object"'],
+    ['parameters: { text: { type: \'string\', items: { type: \'string\' } } }', 'parameters.text.items is only valid for type "array"'],
+  ])('rejects a malformed SchemaSpec (%s) with a teaching error', async (parameters, message) => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'bad-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'bad_schema_tool',
+              description: 'bad',
+              ${parameters},
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain(message)
+  })
+
+  it('accepts a nested object/array SchemaSpec (the DSL recursion)', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'nested-schema',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'nested_schema_tool',
+              description: 'nested',
+              parameters: {
+                item: { type: 'object', required: true, properties: { label: { type: 'string', required: true } } },
+                tags: { type: 'array', items: { type: 'string' } },
+              },
+              async execute(args) { return [{ type: 'text', text: args.item.label }] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    const echoed = await call(ctx, 'nested_schema_tool', { item: { label: 'ok' }, tags: ['a'] })
+    expect(text(echoed)).toBe('ok')
+  })
+
+  it('rejects raw dynamic ctx.tools.register calls that bypass harness helpers', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'raw-register',
+          inject: ['tools'],
+          apply(ctx) {
+            ctx.tools.register({
+              name: 'raw_dynamic_tool',
+              description: 'raw',
+              parameters: { type: 'object', properties: {} },
+              async execute() { return [] },
+            })
+          },
+        }
+      `,
+    })
+
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('dynamic tool registration must use a tool returned by harness.defineTool')
+    expect(ctx.tools.get('raw_dynamic_tool')).toBeUndefined()
+  })
+
+  it('guards the registry reached through ctx.get(\'tools\') identically', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'raw-register-get',
+          apply(ctx) {
+            ctx.get('tools').register({ name: 'raw_via_get', description: 'raw', parameters: {}, async execute() { return [] } })
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('dynamic tool registration must use a tool returned by harness.defineTool')
+    expect(ctx.tools.get('raw_via_get')).toBeUndefined()
+  })
+
+  it('passes non-register registry members through the guard with correct binding', async () => {
+    const ctx = await setup()
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'schema-reader',
+          inject: ['tools'],
+          apply(ctx) {
+            console.log('sees', ctx.tools.schemas().length, 'tools; mount is', typeof ctx.tools.get('cordis_mount'))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'sees', 3, 'tools; mount is', 'object')
+  })
+
+  it('keeps a plugin with unsatisfied inject mounted as pending and names what it waits for', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: 'return { name: \'waiter\', inject: [\'no-such-service\'], apply(ctx) {} }',
+    })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('state: pending')
+    expect(text(result)).toContain('waiting for service(s): no-such-service')
+    // Unmounting a pending mount works like any other.
+    const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
+    expect(unmounted.isError).toBe(false)
+  })
+
+  it('rejects code that throws, leaving nothing mounted', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', { code: 'throw new Error(\'boom in sandbox\')' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('boom in sandbox')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+  })
+
+  it('passes non-Error and null throws through untouched (no SyntaxError misclassification)', async () => {
+    const ctx = await setup()
+    const primitive = await call(ctx, 'cordis_mount', { code: 'throw \'plain-string-throw\'' })
+    expect(primitive.isError).toBe(true)
+    expect(text(primitive)).toContain('plain-string-throw')
+    const nullish = await call(ctx, 'cordis_mount', { code: 'throw null' })
+    expect(nullish.isError).toBe(true)
+  })
+
+  it('rejects code that does not return a plugin', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', { code: 'return 42' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('must `return` a plugin')
+  })
+
+  it('answers a missing return with the two valid plugin forms', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', { code: 'const plugin = (ctx) => {}' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('did you forget `return`?')
+  })
+
+  it('disposes a plugin whose apply throws, and reports the error', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: 'return { name: \'broken\', apply(ctx) { throw new Error(\'apply exploded\') } }',
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('apply exploded')
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+  })
+
+  it('rolls back a plugin that collides with an existing tool name, keeping the original tool intact', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'usurper',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'cordis_mount',
+              description: 'dup',
+              parameters: {},
+              async execute() { return [] },
+            }))
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('already registered')
+    expect(text(result)).toContain('first cordis_unmount')
+    // The original cordis_mount still dispatches — the failed fiber is gone.
+    const retry = await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
+    expect(retry.isError).toBe(false)
+  })
+
+  it('isolates sandbox globals: no process/Buffer, and globalThis writes do not leak to the host', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        globalThis.__cordis_tool_leak = 'leaked'
+        return { name: 'probe-' + typeof process + '-' + typeof Buffer, apply(ctx) {} }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('plugin "probe-undefined-undefined"')
+    expect((globalThis as Record<string, unknown>).__cordis_tool_leak).toBeUndefined()
+  })
+
+  it.each([
+    ['require(\'fs\')', 'require is not available in the mount sandbox', 'inject: [\'fs\']'],
+    ['setTimeout(() => {}, 5)', 'setTimeout is not available in the mount sandbox', 'ctx.setTimeout'],
+    ['fetch(\'https://example.com\')', 'fetch is not available in the mount sandbox', 'ctx.web'],
+  ])('traps the Node API call %s with a redirect to the cordis alternative', async (invocation, trapMessage, redirect) => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', { code: `${invocation}\nreturn (ctx) => {}` })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain(trapMessage)
+    expect(text(result)).toContain(redirect)
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+  })
+
+  it('lets a mounted plugin schedule through the cordis timer service (inject: [\'timer\'])', async () => {
+    const ctx = await setup()
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'ticker',
+          inject: ['timer'],
+          apply(ctx) {
+            ctx.setTimeout(() => console.log('tick'), 10)
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('state: active')
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'tick')
+  })
+
+  it('provides btoa/atob and the tagged console variants inside the sandbox', async () => {
+    const ctx = await setup()
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        console.warn('warned')
+        console.error('errored')
+        const round = atob(btoa('hi'))
+        const bytes = new TextEncoder().encode(round)
+        return { name: 'codec-' + new TextDecoder().decode(bytes), apply(ctx) { console.log('applied', typeof ctx.on) } }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('plugin "codec-hi"')
+    expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'warned')
+    expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'applied', 'function')
+    expect(error).toHaveBeenCalledWith('[cordis:dyn-1]', 'errored')
+  })
+
+  it('answers TypeScript syntax in the plain-JS sandbox with the fix', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: 'return { name: \'ts\' as const, apply(ctx) {} }',
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('plain JavaScript, not TypeScript')
+  })
+
+  it('surfaces the offending line + caret and the bracket-balance hint on a syntax error', async () => {
+    const ctx = await setup()
+    // The canonical model mistake: closing the returned object with `});` as
+    // if it were a callback argument. The word "as" in a STRING elsewhere must
+    // not trigger the TypeScript hint — the heuristic reads the failing line.
+    const result = await call(ctx, 'cordis_mount', {
+      code: 'const note = \'treat pattern as regex\'\nreturn {\n  name: \'oops\',\n  apply(ctx) {}\n});',
+    })
+    expect(result.isError).toBe(true)
+    const message = text(result)
+    expect(message).toContain('failed to parse')
+    expect(message).toContain('});')
+    expect(message).toContain('^')
+    expect(message).toContain('BODY of an async function')
+    expect(message).not.toContain('TypeScript')
+  })
+
+  it('syntaxErrorContext falls back to String(error) when the stack has no vm prelude', () => {
+    const doctored = new SyntaxError('boom')
+    delete (doctored as { stack?: string }).stack
+    expect(syntaxErrorContext(doctored)).toBe('SyntaxError: boom')
+    const plain = new SyntaxError('bang')
+    plain.stack = 'not-a-vm-stack'
+    expect(syntaxErrorContext(plain)).toBe('SyntaxError: bang')
+  })
+
+  it('handles a runtime-thrown SyntaxError (no source-line prelude) with the generic hint', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', { code: 'throw new SyntaxError(\'user-crafted\')' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('failed to parse')
+    expect(text(result)).toContain('user-crafted')
+  })
+
+  it('honors the configured vmTimeoutMs for the synchronous portion', async () => {
+    const ctx = await setup({ vmTimeoutMs: 50 })
+    const result = await call(ctx, 'cordis_mount', { code: 'while (true) {}' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toMatch(/timed? ?out/i)
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+  })
+
+  it('makes instanceof inside the sandbox see BOTH realms (patched vm constructors, host untouched)', async () => {
+    // The args a tool's execute receives are HOST-realm objects; without the
+    // dual-realm Symbol.hasInstance prelude, `args.items instanceof Array` in
+    // sandbox code is silently false. The patch lives on the vm realm's own
+    // constructors only — the host realm's must stay pristine.
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'probe-instanceof',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'probe_instanceof',
+              description: 'report instanceof checks across realms',
+              parameters: { items: { type: 'array', required: true, items: { type: 'string' } } },
+              async execute(args) {
+                const checks = {
+                  hostArray: args.items instanceof Array,
+                  hostObject: args instanceof Object,
+                  vmArray: [] instanceof Array,
+                  vmObject: ({}) instanceof Object,
+                }
+                return [{ type: 'text', text: JSON.stringify(checks) }]
+              },
+            }))
+          },
+        }
+      `,
+    })
+    const probed = await call(ctx, 'probe_instanceof', { items: ['a'] })
+    expect(probed.isError).toBe(false)
+    expect(JSON.parse(text(probed))).toEqual({ hostArray: true, hostObject: true, vmArray: true, vmObject: true })
+    // The host realm's constructors keep their default instanceof: no own
+    // Symbol.hasInstance was added to them.
+    expect(Object.getOwnPropertySymbols(Object)).not.toContain(Symbol.hasInstance)
+    expect(Object.getOwnPropertySymbols(Array)).not.toContain(Symbol.hasInstance)
+  })
+})

packages/cordis/tool-cordis/tests/present.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { presentInspectCall, presentMountCall, presentUnmountCall } from '../src/present.ts'
+import { setup } from './helpers.ts'
+
+/**
+ * Render-intent presenters: pure functions of the call args (no I/O, no
+ * session state — they run on replay too), wired onto the registered tools.
+ */
+
+describe('presenters', () => {
+  it('cordis_inspect renders a generic read card titled with the section', () => {
+    expect(presentInspectCall({})).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime' })
+    expect(presentInspectCall({ what: 'api' })).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime: api' })
+  })
+
+  it('cordis_mount renders a generic execute card carrying the code as raw input', () => {
+    expect(presentMountCall({ code: 'return (ctx) => {}' })).toEqual({
+      card: 'generic',
+      kind: 'execute',
+      title: 'Mount plugin into live cordis runtime',
+      rawInput: { code: 'return (ctx) => {}' },
+    })
+  })
+
+  it('cordis_unmount renders a generic delete card titled with the id', () => {
+    expect(presentUnmountCall({ id: 'dyn-1' })).toEqual({ card: 'generic', kind: 'delete', title: 'Unmount dyn-1' })
+  })
+
+  it('is wired onto the registered definitions through the defineTool soft-validation path', async () => {
+    const ctx = await setup()
+    expect(ctx.tools.get('cordis_inspect')!.presentCall!({ what: 'tools' })).toEqual({
+      card: 'generic',
+      kind: 'read',
+      title: 'Inspect cordis runtime: tools',
+    })
+    expect(ctx.tools.get('cordis_mount')!.presentCall!({ code: 'return 1' })).toMatchObject({ kind: 'execute' })
+    expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 'dyn-2' })).toMatchObject({ title: 'Unmount dyn-2' })
+    // Soft validation: presenter args that fail the schema render as no card, never a throw.
+    expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 42 })).toBeUndefined()
+  })
+})

packages/cordis/tool-cordis/tests/sandbox-context.spec.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it } from 'vitest'
+import { call, setup, text } from './helpers.ts'
+
+/**
+ * The sandbox context façade is a whitelist, not a pass-through proxy: mount
+ * code reaches only the registration/eventing verbs, the timer helpers, a
+ * guarded `tools`, and its injected services. Every framework-plumbing member
+ * that could hand back an UNGUARDED context — through which a plugin could
+ * `ctx.<escape>.tools.register({…})` to bypass the marker check and host-realm
+ * normalization — is denied. These are the regression guards for that escape
+ * class (the review finding on the original pass-through proxy).
+ */
+
+/** Mount a plugin whose `apply` touches one framework member, and report the error text. */
+async function mountTouching(ctx: Awaited<ReturnType<typeof setup>>, expr: string): Promise<string> {
+  const result = await call(ctx, 'cordis_mount', {
+    code: `return { name: 'probe', inject: ['tools'], apply(ctx) { ${expr} } }`,
+  })
+  expect(result.isError).toBe(true)
+  return text(result)
+}
+
+describe('sandbox context façade — escape surface is closed', () => {
+  it.each([
+    ['ctx.root', 'const c = ctx.root'],
+    ['ctx.parent', 'const c = ctx.parent'],
+    ['ctx.scope', 'const c = ctx.scope'],
+    ['ctx.fiber', 'const f = ctx.fiber'],
+    ['ctx.reflect', 'const r = ctx.reflect'],
+    ['ctx.registry', 'const r = ctx.registry'],
+    ['ctx.events', 'const e = ctx.events'],
+    ['ctx.extend()', 'ctx.extend({})'],
+    ['ctx.isolate()', 'ctx.isolate("x")'],
+    ['ctx.intercept()', 'ctx.intercept("x", {})'],
+    ['ctx.plugin()', 'ctx.plugin({ apply() {} })'],
+    ['ctx.set()', 'ctx.set("tools", 1)'],
+    ['ctx.mixin()', 'ctx.mixin("x", [])'],
+  ])('denies %s with a teaching error', async (_label, expr) => {
+    const ctx = await setup()
+    const message = await mountTouching(ctx, expr)
+    expect(message).toContain('sandbox ctx does not expose')
+    expect(message).toContain('withheld by design')
+  })
+
+  it('the classic ctx.root.tools.register bypass registers nothing and fails loud', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'root-bypass',
+          inject: ['tools'],
+          apply(ctx) {
+            ctx.root.tools.register({
+              name: 'smuggled',
+              description: 'raw, unguarded',
+              parameters: { type: 'object', properties: {} },
+              async execute() { return [] },
+            })
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('sandbox ctx does not expose "root"')
+    // The whole point: the bypass never reaches the registry.
+    expect(ctx.tools.get('smuggled')).toBeUndefined()
+  })
+
+  it('rejects assignment to the façade rather than silently dropping it', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: 'return { name: \'writer\', apply(ctx) { ctx.stash = 1 } }',
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('sandbox ctx is read-only')
+  })
+
+  it('denies a service whose method returns a Context (the .ctx escape), registering nothing', async () => {
+    // A cordis Service instance carries `.ctx` (a real Context), so
+    // `ctx.systemPrompt.ctx.root.tools.register(…)` would be a fresh unguarded
+    // handle. The service wrapper's return-value guard rejects any Context on
+    // the way back to sandbox code, so the escape never lands. (`systemPrompt`
+    // is in the setup harness, so the plugin activates and its apply runs.)
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'svc-ctx-escape',
+          inject: ['systemPrompt', 'tools'],
+          apply(ctx) {
+            ctx.systemPrompt.ctx.root.tools.register({
+              name: 'smuggled_via_service',
+              description: 'raw, unguarded',
+              parameters: { type: 'object', properties: {} },
+              async execute() { return [] },
+            })
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('returned a cordis Context, which the sandbox does not expose')
+    expect(ctx.tools.get('smuggled_via_service')).toBeUndefined()
+  })
+
+  it('guards an async injected-service method: a host-realm Promise resolves through the guard', async () => {
+    // The return guard's Promise arm only fires for a HOST-realm Promise
+    // (a vm-realm one is not `instanceof` the host `Promise`). Provide a
+    // host-realm service from the test, then inject + await it from a mount:
+    // the resolved value is non-Context data and passes through.
+    const ctx = await setup()
+    ctx.plugin({
+      name: 'host-async-svc',
+      apply(c) { c.provide('hostAsync', { grab: async () => 'host-fetched' }) },
+    })
+    await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'async-consumer',
+          inject: ['hostAsync', 'tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'do_fetch',
+              description: 'awaits the host async service',
+              parameters: {},
+              async execute() {
+                const value = await ctx.hostAsync.grab()
+                return [{ type: 'text', text: value }]
+              },
+            }))
+          },
+        }
+      `,
+    })
+    const result = await call(ctx, 'do_fetch', {})
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe('host-fetched')
+  })
+
+  it('reads a symbol property as undefined and answers the `in` operator without throwing', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'introspector',
+          inject: ['tools'],
+          apply(ctx) {
+            const sym = ctx[Symbol.iterator]
+            console.log('probe', sym === undefined, 'tools' in ctx, 'on' in ctx, 'root' in ctx)
+          },
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+  })
+})
+
+describe('sandbox context façade — inject gate on services', () => {
+  it('denies an undeclared live service (property access), naming the inject fix', async () => {
+    // `systemPrompt` is a live global service in the setup harness, but this
+    // mount does not declare it — reaching it would let the mount depend on a
+    // provider cordis does not know about, so it is refused.
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: 'return { name: \'undeclared\', inject: [\'tools\'], apply(ctx) { const s = ctx.systemPrompt } }',
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('service "systemPrompt" is not injected')
+    expect(text(result)).toContain('inject: [\'systemPrompt\', …]')
+  })
+
+  it('denies an undeclared live service reached through ctx.get too', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: 'return { name: \'undeclared-get\', inject: [\'tools\'], apply(ctx) { ctx.get(\'systemPrompt\') } }',
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('service "systemPrompt" is not injected')
+  })
+
+  it('allows a service the mount DID declare in inject', async () => {
+    const ctx = await setup()
+    const result = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'declared',
+          inject: ['systemPrompt', 'tools'],
+          apply(ctx) { console.log('has systemPrompt:', typeof ctx.systemPrompt) }
+        }
+      `,
+    })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('state: active')
+  })
+
+  it('a cross-mount consumer must declare the provider — the undeclared path is refused, not left as a zombie tool', async () => {
+    // The finding's scenario: a consumer registers a tool built on a provider's
+    // service WITHOUT declaring inject. cordis would then never park the
+    // consumer when the provider unmounts, leaving a tool that fails only at
+    // execution. The gate refuses the undeclared access up front, so the
+    // dependency is always visible to cordis.
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', {
+      code: 'return { name: \'greeter-provider\', apply(ctx) { ctx.provide(\'greeter\', { greet: (n) => \'hi \' + n }) } }',
+    })
+    const undeclared = await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'sloppy-consumer',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'greet_undeclared',
+              description: 'uses greeter without declaring it',
+              parameters: { n: { type: 'string', required: true } },
+              async execute(args) { return [{ type: 'text', text: ctx.greeter.greet(args.n) }] },
+            }))
+          },
+        }
+      `,
+    })
+    // The tool registers (its execute is lazy), but calling it hits the gate:
+    // `ctx.greeter` is undeclared, so it fails with the teaching error rather
+    // than silently working and later stranding.
+    expect(undeclared.isError).toBe(false)
+    const called = await call(ctx, 'greet_undeclared', { n: 'x' })
+    expect(called.isError).toBe(true)
+    expect(text(called)).toContain('service "greeter" is not injected')
+  })
+})
+
+describe('sandbox tools façade — get is a read-only schema view', () => {
+  it('ctx.tools.get returns a schema, not the live ToolDefinition with execute', async () => {
+    // The finding: returning the raw ToolDefinition hands mount code the
+    // tool's execute function, letting it bypass ToolRegistry.execute (and its
+    // pre/post hooks). get now returns the same name/description/parameters
+    // view as schemas(), with no execute. Asserted via a self-made tool that
+    // reports the shape it saw — world-checked, not self-reported.
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'reporter',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'report_view',
+              description: 'reports the shape of a tool view',
+              parameters: {},
+              async execute() {
+                const view = ctx.tools.get('cordis_mount')
+                return [{ type: 'text', text: JSON.stringify({
+                  hasExecute: 'execute' in view,
+                  hasPresentCall: 'presentCall' in view,
+                  name: view.name,
+                  keys: Object.keys(view).sort(),
+                }) }]
+              },
+            }))
+          },
+        }
+      `,
+    })
+    const reported = await call(ctx, 'report_view', {})
+    expect(reported.isError).toBe(false)
+    const shape = JSON.parse(text(reported)) as { hasExecute: boolean; hasPresentCall: boolean; name: string; keys: string[] }
+    expect(shape.hasExecute).toBe(false)
+    expect(shape.hasPresentCall).toBe(false)
+    expect(shape.name).toBe('cordis_mount')
+    expect(shape.keys).toEqual(['description', 'name', 'parameters'])
+  })
+
+  it('ctx.tools.get returns undefined for an unknown tool', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', {
+      code: `
+        return {
+          name: 'unknown-probe',
+          inject: ['tools'],
+          apply(ctx) {
+            harness.registerTool(ctx, harness.defineTool({
+              name: 'probe_unknown',
+              description: 'reports whether an unknown tool resolves',
+              parameters: {},
+              async execute() {
+                return [{ type: 'text', text: String(ctx.tools.get('no_such_tool') === undefined) }]
+              },
+            }))
+          },
+        }
+      `,
+    })
+    expect(text(await call(ctx, 'probe_unknown', {}))).toBe('true')
+  })
+})

packages/cordis/tool-cordis/tests/tool-cordis.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import Loader from '@cordisjs/plugin-loader'
+import * as tool from '../src/index.ts'
+import { setup } from './helpers.ts'
+
+/**
+ * Export-shape and registration surface: the namespace-plugin contract the
+ * real Loader path depends on, the registered tool set, and the Config
+ * validator's defaults and rejections.
+ */
+
+describe('export shape', () => {
+  it('has no default export, and survives the real Loader unwrapExports', () => {
+    // A stray `export default` would make `unwrapExports` (`exports.default ??
+    // exports`) collapse the module to the bare function and DROP `inject`,
+    // crashing at real load (docs/postmortem/0001). Assert directly AND through
+    // the real unwrap so adding `export default apply` fails here.
+    expect('default' in tool).toBe(false)
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(tool) as Record<string, unknown>
+    expect(unwrapped).toBe(tool)
+    expect(unwrapped.name).toBe('tool-cordis')
+    expect(unwrapped.inject).toEqual(['tools'])
+    expect(typeof unwrapped.apply).toBe('function')
+    expect(typeof unwrapped.Config).toBe('function')
+  })
+})
+
+describe('tool registration', () => {
+  it('registers the three cordis tools with the documented schemas', async () => {
+    const ctx = await setup()
+    const names = ctx.tools.schemas().map(schema => schema.name)
+    expect(names).toEqual(expect.arrayContaining(['cordis_inspect', 'cordis_mount', 'cordis_unmount']))
+    const inspect = ctx.tools.schemas().find(schema => schema.name === 'cordis_inspect')!
+    const props = (inspect.parameters as { properties: Record<string, { enum?: string[] }> }).properties
+    expect(props.what?.enum).toEqual(['services', 'plugins', 'tools', 'dynamic', 'api', 'events'])
+  })
+})
+
+describe('Config', () => {
+  it('defaults vmTimeoutMs to 5000', () => {
+    expect(new tool.Config()).toEqual({ vmTimeoutMs: 5000 })
+  })
+
+  it('rejects a non-positive vmTimeoutMs at validation time (misconfiguration fails loud)', () => {
+    expect(() => new tool.Config({ vmTimeoutMs: 0 })).toThrow()
+    expect(() => new tool.Config({ vmTimeoutMs: -1 })).toThrow()
+  })
+})

packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import * as tool from '../src/index.ts'
+import { call, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts'
+
+/**
+ * Disposal semantics: `cordis_unmount` reaches quiescence before returning,
+ * and disposing the tool-cordis fiber itself (the HMR path) cascades over the
+ * whole dynamic subtree through the ordinary parent→child fiber lifecycle.
+ */
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('cordis_unmount', () => {
+  it('disposes the mount and its registrations have stopped by the time it returns (quiescence)', async () => {
+    const ctx = await setup()
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
+
+    ctx.tools.register(dummyTool('trigger_before'))
+    expect(log).toHaveBeenCalledTimes(1)
+
+    const result = await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toContain('unmounted dyn-1')
+
+    // Immediately after the awaited unmount, the listener must be gone — no
+    // grace period, no eventual consistency.
+    ctx.tools.register(dummyTool('trigger_after'))
+    expect(log).toHaveBeenCalledTimes(1)
+    expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)')
+  })
+
+  it('unregisters a self-made tool on unmount', async () => {
+    const ctx = await setup()
+    await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE })
+    expect(ctx.tools.get('reverse_text')).toBeDefined()
+
+    await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
+    expect(ctx.tools.get('reverse_text')).toBeUndefined()
+  })
+
+  it('rejects an unknown id, and a second unmount of the same id', async () => {
+    const ctx = await setup()
+    const unknown = await call(ctx, 'cordis_unmount', { id: 'dyn-99' })
+    expect(unknown.isError).toBe(true)
+    expect(text(unknown)).toContain('no dynamic plugin with id "dyn-99"')
+
+    await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
+    await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
+    const again = await call(ctx, 'cordis_unmount', { id: 'dyn-1' })
+    expect(again.isError).toBe(true)
+  })
+})
+
+describe('HMR safety', () => {
+  it('disposing the tool-cordis fiber cascades over the dynamic subtree and its registrations', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    const fiber = await ctx.plugin(tool)
+
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    await call(ctx, 'cordis_mount', { code: LISTENER_CODE })
+    await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE })
+    expect(ctx.tools.get('reverse_text')).toBeDefined()
+
+    await fiber.dispose()
+
+    // The whole subtree is gone: the self-made tool, the cordis tools, and the
+    // mounted listener (no log on a fresh tools/change).
+    expect(ctx.tools.get('reverse_text')).toBeUndefined()
+    expect(ctx.tools.get('cordis_mount')).toBeUndefined()
+    const calls = log.mock.calls.length
+    ctx.tools.register(dummyTool('trigger_post_dispose'))
+    expect(log).toHaveBeenCalledTimes(calls)
+  })
+})

packages/cordis/tool-cordis/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/timer"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/tools"
+    }
+  ]
+}

packages/core/agent-core/src/index.ts

@@ -48,7 +48,7 @@ import z from 'schemastery'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import * as invariants from '@deepseek-ai/dsh-invariants'
 import * as toolBash from '@deepseek-ai/dsh-tool-bash'
@@ -61,10 +61,12 @@ export const name = 'agent-core'
  * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
  * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
  * plugin (the deployment's persona section and the explicit model-facing tool
- * order). Every field is optional INPUT here because each owner's schema
- * supplies the default (`[]` / `''` / absent — lexicographic); the schema is
- * the INTERSECTION of the owners' own schemas, so validation and defaulting
- * can never drift from them.
+ * order), the `tools` object to the tool registry (its presentation `mode`).
+ * Every field is optional INPUT here because each owner's schema
+ * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
+ * schema is the INTERSECTION of the owners' own schemas (the registry's
+ * nested under its `tools` key), so validation and defaulting can never
+ * drift from them.
  */
 export interface Config {
   /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -73,10 +75,12 @@ export interface Config {
   persona?: SystemPromptConfig['persona']
   /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
   toolOrder?: SystemPromptConfig['toolOrder']
+  /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */
+  tools?: ToolsConfig
 }
 
-/** Intersect the owners' schemas so validation + defaulting stay identical. */
-export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config]) as unknown as z<Config>
+/** Intersect the owners' schemas so validation + defaulting stay identical (the registry's nested under `tools`). */
+export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config, z.object({ tools: ToolRegistry.Config })]) as unknown as z<Config>
 
 /**
  * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber;
@@ -101,7 +105,7 @@ export function apply(ctx: Context, config: Config): void {
     persona: config.persona ?? '',
     ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
   })
-  ctx.plugin(ToolRegistry)
+  ctx.plugin(ToolRegistry, config.tools ?? {})
   ctx.plugin(AgentRegistry)
   ctx.plugin(invariants)
   ctx.plugin(toolBash)

packages/core/agent-loop/README.md

@@ -55,12 +55,15 @@ forever:
     STEP loop:
       drain steering
       assembly = systemPrompt.assemble({agent})  ⟵ renderPrompt(assembly) IS the full prompt
-      await serial agent/pre-step        ⟵ surface mutation (compaction) outside the step
+      prefix ??= waterfall agent/session-prefix   ⟵ once per instance (first step): frozen
+                                                session prefix; on the header, never history
+      await serial agent/pre-step(…, prefix)  ⟵ surface mutation (compaction) outside the step;
+                                                pressure gates see the prefix the request carries
       boundary = session.deriveMessages()   ⟵ reconstruction boundary: same sync frame,
       session('step/start')                     strictly before step/start
       config = waterfall agent/request       ⟵ frozen seed; return a replacement to switch
       session('request/header'[-delta])      ⟵ the header event this request owes the log
-      stream llm.stream(freeze({header..., messages: boundary})) → session('assistant/chunk')
+      stream llm.stream(freeze({header..., messages: prefix+boundary})) → session('assistant/chunk')
       message = waterfall agent/step-result
       session('assistant/message')
       each tool-call: session('tool/call')
@@ -84,7 +87,7 @@ Cancellation: `agent.cancel()` is the single public stop primitive — it clears
 ### What is NOT here
 
 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:
-- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation`
+- Hooks: `agent/session-start`, `agent/prompt-submit`, `agent/pre-step`, `agent/request`, `agent/session-prefix`, `agent/step-result`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-continuation`
 - Compaction: `agent/pre-step`
 - Sandbox, permission, plan mode: `tools/pre-execute` (deny/ask gate), `tools/post-execute`
 - Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred.

packages/core/agent-loop/src/loop.ts

@@ -157,13 +157,17 @@ export interface LoopHandle {
  *       drain steering → session('steering/message')  ⟵ catches late steering
  *       assembly = ctx.systemPrompt.assemble({agent}) ⟵ waterfall system-prompt/assemble; renderPrompt
  *                                                        (persona section + {{variables}}) IS the full prompt
- *       await ctx.serial('agent/pre-step')            ⟵ surface mutation (compaction) OUTSIDE the step
+ *       prefix ??= waterfall agent/session-prefix     ⟵ once per loop instance (first step): frozen
+ *                                                        session prefix; logged on the header, never
+ *                                                        session history
+ *       await ctx.serial('agent/pre-step', …, prefix) ⟵ surface mutation (compaction) OUTSIDE the step;
+ *                                                        pressure gates see the prefix the request carries
  *       boundary = session.deriveMessages()           ⟵ the reconstruction boundary: snapshot in the
  *       session('step/start')                            same sync frame, strictly before step/start
  *       config = waterfall agent/request(config)      ⟵ frozen seed; a returned replacement switches
  *       session('request/header'|'request/header-delta')  ⟵ the header event this request owes the
  *                                                        log (initial/resume anchor, delta, fallback)
- *       req = freeze({header..., messages: boundary, sessionId, signal})
+ *       req = freeze({header..., messages: prefix+boundary, sessionId, signal})
  *       stream ctx.llm.stream(req)                    ⟵ waterfall llm/stream (raw chunks, frozen req)
  *         session('assistant/chunk')
  *       msg = waterfall agent/step-result             ⟵ BEFORE the log append, so the
@@ -472,6 +476,50 @@ async function runTurn(
         break
       }
 
+      // Compose the session prefix ONCE per loop instance, lazily before the
+      // instance's first pre-step: request-only messages placed in front of
+      // the ENTIRE derived history on every request this instance sends. It
+      // MUST precede the pre-step seam so compaction gates on THIS instance's
+      // prefix — reading a previous instance's logged prefix would let a
+      // resumed/forked instance whose contributor grew skip compaction and
+      // ship an over-window first request. The result is deep-cloned
+      // (decoupled from listener-held references), deep-frozen, and cached on
+      // the transmission bookkeeping, so reuse is structural — the prefix
+      // cannot change mid-session and the provider prefix cache holds by
+      // construction (resume = a new instance = a recompose, anchored by its
+      // 'resume' snapshot). The prefix is not session history — the header
+      // event in runStep is its only durable record
+      // (EpochHeader.messagePrefix). The frozen empty seed serves both the
+      // listener chain and the no-listener fallback: a contribution is a
+      // RETURNED extension of `await next()`, never an in-place push. This
+      // runs OUTSIDE the step, before the boundary snapshot: a composing
+      // listener's session append lands before the boundary and joins the
+      // CURRENT request.
+      if (transmission.sessionPrefix === undefined) {
+        const emptyPrefix: Message[] = deepFreeze([])
+        const composed = await ctx.waterfall(
+          'agent/session-prefix', agent, emptyPrefix, abort.signal,
+          () => Promise.resolve(emptyPrefix),
+        )
+
+        // Interruption landing during prefix composition: mirror the assembly
+        // window above — drop the about-to-start step without running the
+        // seam, and DISCARD the composition instead of caching it. An
+        // abort-aware listener may have returned a degraded fallback under
+        // the firing signal; committing it would ship a prefix no request
+        // ever used (and no header ever logged) on this instance's next real
+        // request. The next turn recomposes under a live signal — the cache
+        // only ever holds a fully composed prefix. The cache-hit path needs
+        // no such check: nothing awaits between the assembly check above and
+        // the pre-step seam.
+        if (handle.isCancelled() || handle.isDisposed()) {
+          handle.setAbort(undefined)
+          reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() }
+          break
+        }
+        transmission.sessionPrefix = deepFreeze(structuredClone(composed))
+      }
+
       // Pre-step surface-mutation checkpoint (compaction), fired OUTSIDE the
       // step: after `turn/start` (and the prior step's close) but before
       // `step/start`, so a compaction's log-only `compact/*` records and its
@@ -482,8 +530,10 @@ async function runTurn(
       // concurrent listeners cannot interleave their `session.append`s. A
       // throwing listener escapes to the outer catch, which closes the (not-yet-
       // open) step as a no-op and ends the turn via failTurn — a broken
-      // pre-step plugin ends the turn, not the loop.
-      await ctx.serial('agent/pre-step', agent, turn, step, fullSystemPrompt, abort.signal)
+      // pre-step plugin ends the turn, not the loop. The composed session
+      // prefix rides along so token-pressure listeners count everything the
+      // request will actually carry.
+      await ctx.serial('agent/pre-step', agent, turn, step, fullSystemPrompt, transmission.sessionPrefix, abort.signal)
 
       // Interruption landing during the pre-step seam: do not open an empty step.
       if (handle.isCancelled() || handle.isDisposed()) {
@@ -674,11 +724,12 @@ function drainSteering(agent: ReactLoopAgent, turn: number): boolean {
 }
 
 /** One step: build the request from the boundary snapshot + the step's
- * header → log the header event the request owes → stream model → record →
- * execute tools. The caller assembles the system prompt, fires the
- * `agent/pre-step` seam, snapshots the derivation, and opens the step BEFORE
- * calling this, so `boundaryMessages` is exactly the surface prefix at
- * step/start and already reflects any compaction. */
+ * header → compose the session prefix if this instance has none yet → log
+ * the header event the request owes → stream model → record → execute
+ * tools. The caller assembles the
+ * system prompt, fires the `agent/pre-step` seam, snapshots the derivation,
+ * and opens the step BEFORE calling this, so `boundaryMessages` is exactly
+ * the surface prefix at step/start and already reflects any compaction. */
 async function runStep(
   ctx: Context,
   agent: ReactLoopAgent,
@@ -718,22 +769,30 @@ async function runStep(
     throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`)
   }
 
+  // The session prefix was composed (once per instance) before this step's
+  // pre-step seam — the caller guarantees it, so the cache is always set here.
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- runTurn composes the prefix before every runStep call
+  const sessionPrefix = transmission.sessionPrefix!
+
   // The request header (the log's request/header* vocabulary): canonical form,
-  // recorded before dispatch so the log always explains the request.
+  // recorded before dispatch so the log always explains the request —
+  // including the session prefix, which no other event carries.
   const header = canonicalHeader({
     config,
     ...system ? { system } : {},
     ...assembly.tools.length > 0 ? { tools: assembly.tools } : {},
+    ...sessionPrefix.length > 0 ? { messagePrefix: sessionPrefix } : {},
   })
   recordRequestHeader(session, transmission, header)
 
   // Build and freeze: the request is a pure function of (boundary snapshot,
   // logged header) — llm/stream listeners and adapters read it, mutation
   // throws. sessionId + frozen is the loop-built marker the dev invariant
-  // keys on.
+  // keys on. Message order: header.messagePrefix, then the boundary
+  // snapshot — the reconstruction equation the invariant recomputes.
   const request: GenerateOptions = deepFreeze({
     model: header.config.model,
-    messages: boundaryMessages,
+    messages: [...header.messagePrefix ?? [], ...boundaryMessages],
     ...header.system !== undefined ? { system: header.system } : {},
     ...header.tools !== undefined ? { tools: header.tools } : {},
     ...header.config.temperature !== undefined ? { temperature: header.config.temperature } : {},

packages/core/agent-loop/src/request-log.ts

@@ -12,11 +12,20 @@
 
 import { diffHeader, headerEquals, applyHeaderDelta } from '@deepseek-ai/dsh-session'
 import type { EpochHeader, Session } from '@deepseek-ai/dsh-session'
+import type { Message } from '@deepseek-ai/dsh-llm'
 
 /** Per-loop-instance bookkeeping: whether THIS instance has logged a header yet. */
 export interface TransmissionLog {
   /** True once this loop instance appended its anchoring `request/header` snapshot. */
   loggedHeader: boolean
+  /**
+   * The instance's composed session prefix (the `agent/session-prefix`
+   * waterfall's deep-frozen product), cached on the instance's first
+   * request-building step and reused verbatim for every request it sends —
+   * the structural guarantee that the prefix never changes mid-session.
+   * `undefined` until composed.
+   */
+  sessionPrefix?: Message[]
 }
 
 /**
@@ -61,7 +70,7 @@ export function recordRequestHeader(session: Session, state: TransmissionLog, he
   const baseline = session.requestHeader()!
   if (headerEquals(baseline, header)) return
   const delta = diffHeader(baseline, header)
-  /* v8 ignore next -- headerEquals false ⟹ diffHeader defined: both compare the same three parts */
+  /* v8 ignore next -- headerEquals false ⟹ diffHeader defined: both compare the same four parts */
   if (delta === undefined) return
   if (headerEquals(applyHeaderDelta(baseline, delta), header)) {
     session.append('request/header-delta', delta)

packages/core/agent-loop/tests/cancel.spec.ts

@@ -12,7 +12,7 @@
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import LlmService from '@deepseek-ai/dsh-llm'
+import LlmService, { type Message } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -166,6 +166,103 @@ describe('Agent.cancel()', () => {
     expect(reasons.length).toBe(2)
   })
 
+  it('cancel from inside the agent/session-prefix waterfall drops the step (prefix-composition window)', async () => {
+    const adapter = new MockAdapter([textResponse('should not stream')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    // Prefix composition runs before the pre-step seam on the instance's first
+    // step; a cancel landing inside it must drop the about-to-start step
+    // without running the seam or the model.
+    let streamed = false
+    ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => {
+      agent.cancel('from prefix composition')
+      return next()
+    })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(streamed).toBe(false)
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'from prefix composition' }])
+  })
+
+  it('disposal from inside the agent/session-prefix waterfall ends the turn disposed (prefix-composition window)', async () => {
+    const adapter = new MockAdapter([textResponse('should not stream')])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    ctx.llm.registerAdapter(['mock'], adapter)
+
+    const handle = ctx.agents.create({
+      agentId: AgentId('a-dispose-prefix'),
+      sessionId: SessionId('dispose-prefix-session'),
+      agentOptions: { model: 'mock' },
+    })
+    const agent = handle.agent as ReactLoopAgent
+
+    let disposalDone: Promise<void> | undefined
+    let streamed = false
+    ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => {
+      disposalDone = handle.dispose()
+      return next()
+    })
+
+    send(agent, 'go')
+    await new Promise(resolve => setTimeout(resolve, 0))
+    await disposalDone
+    await agent.done
+
+    // No step opened, no model call ran, and the turn closed disposed.
+    expect(streamed).toBe(false)
+    expect(adapter.requests).toHaveLength(0)
+    const turnEnd = agent.session.events.findLast(e => e.type === 'turn/end')
+    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' })
+  })
+
+  it('a cancel-interrupted prefix composition is discarded: the next send recomposes and ships the fresh prefix (stale-cache guard)', async () => {
+    const adapter = new MockAdapter([textResponse('reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    // The first composition is interrupted mid-waterfall and — like an
+    // abort-aware listener bailing on a firing signal — contributes nothing.
+    // Caching that degraded result would silently strip the prefix from every
+    // later request of this instance; the loop must discard it and recompose
+    // on the next send, and the SECOND composition's value must be what the
+    // wire and the header log carry.
+    const opener: Message = { role: 'user', content: [{ type: 'text', text: 'fresh opener' }] }
+    let compositions = 0
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
+      compositions += 1
+      if (compositions === 1) {
+        agent.cancel('mid-composition')
+        return next()
+      }
+      return [opener, ...await next()]
+    })
+
+    send(agent, 'dropped')
+    await waitForIdle(ctx, agent)
+    send(agent, 'real prompt')
+    await waitForIdle(ctx, agent)
+
+    expect(compositions).toBe(2)
+    expect(adapter.requests).toHaveLength(1)
+    expect(adapter.requests[0]?.messages[0]).toEqual(opener)
+    const headerEvent = agent.session.events.find(e => e.type === 'request/header')
+    expect(headerEvent?.type === 'request/header' && headerEvent.data.header.messagePrefix).toEqual([opener])
+  })
+
   it('cancel from a synchronous turn/start session-event listener drops the step (step-start window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)

packages/core/agent-loop/tests/interception.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import LlmService, { CallId } from '@deepseek-ai/dsh-llm'
+import LlmService, { CallId, type Message } from '@deepseek-ai/dsh-llm'
 import SessionStore, { type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
@@ -310,6 +310,162 @@ describe('agent/session-start', () => {
   })
 })
 
+describe('agent/session-prefix', () => {
+  it('composes once per loop instance and fronts every request; the header records it; history stays untouched', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'echo', { text: 'ping' }),
+      textResponse('done'),
+      textResponse('again'),
+    ])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
+      async execute(args) { return [{ type: 'text', text: String(args.text) }] },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    const reminder: Message = { role: 'user', content: [{ type: 'text', text: '<system-reminder>catalog</system-reminder>' }] }
+    let composed = 0
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
+      composed += 1
+      return [...await next(), reminder]
+    })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+    send(agent, 'next turn')
+    await waitForIdle(ctx, agent)
+
+    // Three requests (two turns), ONE composition: the frozen product is
+    // reused verbatim, so the prefix cannot drift mid-session.
+    expect(adapter.requests).toHaveLength(3)
+    expect(composed).toBe(1)
+    for (const request of adapter.requests) {
+      expect(request.messages[0]).toEqual(reminder)
+    }
+    // The anchoring snapshot is the prefix's durable record — and the ONLY
+    // header event: reuse means no request/header-delta ever.
+    const headerEvents = events(agent).filter(e => e.type === 'request/header' || e.type === 'request/header-delta')
+    expect(headerEvents).toHaveLength(1)
+    expect(headerEvents[0]?.type === 'request/header' && headerEvents[0].data.header.messagePrefix).toEqual([reminder])
+    // Never session history: the derivation starts at the real user prompt.
+    expect(agent.session.deriveMessages()[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'go' }] })
+  })
+
+  it('composes before the first pre-step and hands the prefix to the seam (pressure gates see the real value)', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'opener' }] }
+    const order: string[] = []
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
+      order.push('compose')
+      return [reminder, ...await next()]
+    })
+    const seen: (readonly Message[])[] = []
+    ctx.on('agent/pre-step', (_agent, _turn, _step, _system, sessionPrefix) => {
+      order.push('pre-step')
+      seen.push(sessionPrefix)
+    })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    // Composition precedes the pre-step seam, and the seam receives THIS
+    // instance's composed prefix — a token-pressure gate (compaction) counts
+    // what the request will actually carry, never a stale logged prefix.
+    expect(order).toEqual(['compose', 'pre-step'])
+    expect(seen[0]).toEqual([reminder])
+  })
+
+  it('the canonical prepend pattern composes contributions in registration order', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    // Both listeners use the canonical `[mine, ...await next()]` prepend: the
+    // waterfall unwinds innermost-first (the second listener's array is built
+    // first), so prepending puts the FIRST-registered contribution first.
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
+      return [{ role: 'user', content: [{ type: 'text', text: 'first' }] }, ...await next()]
+    })
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
+      return [{ role: 'user', content: [{ type: 'text', text: 'second' }] }, ...await next()]
+    })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    const texts = adapter.requests[0]!.messages.map(m => m.content[0]?.type === 'text' ? m.content[0].text : '')
+    expect(texts).toEqual(['first', 'second', 'hi'])
+  })
+
+  it('with no contributions the header omits messagePrefix and the request is the bare derivation', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    // A listener that delegates without contributing — the canonical no-op.
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => next())
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    const headerEvent = events(agent).find(e => e.type === 'request/header')
+    expect(headerEvent?.type === 'request/header' && 'messagePrefix' in headerEvent.data.header).toBe(false)
+    expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }])
+  })
+
+  it('the frozen seed rejects in-place mutation — a contribution is a returned extension', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    let mutationError: unknown
+    ctx.on('agent/session-prefix', async (_agent, prefix, _signal, next): Promise<Message[]> => {
+      try {
+        prefix.push({ role: 'user', content: [{ type: 'text', text: 'smuggled' }] })
+      } catch (error: unknown) {
+        mutationError = error
+      }
+      return next()
+    })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(mutationError).toBeInstanceOf(TypeError)
+    expect(adapter.requests[0]!.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }])
+  })
+
+  it('mutating a listener-held reference after composition cannot alter later requests (the cache is a frozen clone)', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'echo', { text: 'ping' }),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
+      async execute(args) { return [{ type: 'text', text: String(args.text) }] },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    const held: Message = { role: 'user', content: [{ type: 'text', text: 'v1' }] }
+    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => [...await next(), held])
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    // The listener mutates the object it contributed AFTER composition; the
+    // cached prefix is a deep-frozen clone, so step 2's request is unchanged.
+    held.content = [{ type: 'text', text: 'v2' }]
+    expect(adapter.requests[1]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'v1' }] })
+    expect(events(agent).filter(e => e.type === 'request/header-delta')).toHaveLength(0)
+  })
+})
+
+
 describe('agent/turn-continuation (ContinuationDecision)', () => {
   it('a continue decision with a reason records next-step steering in the same turn', async () => {
     const adapter = new MockAdapter([textResponse('step 1 no tools'), textResponse('step 2')])

packages/core/agent/README.md

@@ -43,8 +43,9 @@ Turn and step boundaries are NOT mirrored as `agent/*` emits: a consumer that ne
 
 - `agent/session-start` (emit) — fired once before the first turn; a listener seeds context via `agent.inject()` (it cannot veto startup).
 - `agent/prompt-submit` — decide what happens to one drained queued message before it becomes a `user/message`: `PromptDecision` = `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (drop it; a batch whose every prompt is blocked opens a zero-step turn that ends `rejected`). Maps onto Claude Code's `UserPromptSubmit`.
-- `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step.
+- `agent/pre-step` (serial) — mutate the session surface before the step opens and history is derived (compaction). Fires after `turn/start` and before `step/start`, so a listener's appended events land outside the step; carries the assembled system prompt and the instance's composed session prefix so a token-pressure gate counts everything the request will carry.
 - `agent/request` — shape the call config before the model call: a frozen `LlmCallConfig` seed in, a replacement out (model switching, sampling overrides). Content is not shapeable here — every request is a pure function of the session log ([reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)); the loop logs whatever config the request actually uses as a `request/header*` event
+- `agent/session-prefix` — compose the session prefix: request-only messages placed in front of the ENTIRE derived history on every request. Fired ONCE per loop instance, lazily before its first pre-step (so pressure gates see this instance's real prefix, never a previous instance's logged one); the composed result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the anchoring `request/header` snapshot, and reused verbatim afterwards — the prefix cannot change mid-session, so the provider prefix cache holds by construction (resume = a new instance = a recompose, attributably anchored by its `'resume'` snapshot). The home for session-stable openers that must not become durable history (a skills catalog, an AGENTS.md digest); `deriveMessages()` never returns it. Content that CHANGES mid-session belongs in the append-only history channels instead — `agent.inject()`, `tools/post-execute` `additionalContext`, prompt-submit `additionalContext` — each a durable `context/message` paid once and prefix-cached thereafter
 - `agent/step-result` — post-process the assembled assistant message before tool dispatch (validates what the log records)
 - `agent/turn-continuation` — override the continue/stop decision via `ContinuationDecision` = `{action:'stop'}` or `{action:'continue', reason?}` (a `continue` `reason` is recorded as next-step steering in the same turn — the typed `/goal` pattern). Force-continue `/loop`, force-stop budget guard.
 

packages/core/agent/src/types.ts

@@ -17,7 +17,8 @@
  *   consumer that wants the live transcript subscribes here.
  * - **`agent/*`** (this module) — the LIVE runtime surface. Always carries the
  *   live `Agent`. Two shapes: INTERCEPTION seams (the `agent/prompt-submit`/
- *   `agent/request`/`agent/step-result`/`agent/turn-continuation` waterfalls and
+ *   `agent/request`/`agent/session-prefix`/`agent/step-result`/
+ *   `agent/turn-continuation` waterfalls and
  *   the serial `agent/pre-step`) that mutate/veto, and TRANSIENT emits
  *   (`agent/status`, `agent/error`, `agent/created`/
  *   `agent/disposed`, `agent/queued`, `agent/session-start`)
@@ -332,21 +333,28 @@ declare module 'cordis' {
      * value; this event is typed and documented as `void`, so listeners must not
      * return a semantic veto value. `fullSystemPrompt` is the assembled prompt a
      * listener needs to measure pressure (the system prompt counts toward the
-     * budget). `signal` cancels any in-flight work a listener starts (e.g. a
+     * budget), and `sessionPrefix` is the instance's composed
+     * {@link agent/session-prefix} product for the same reason — every request
+     * carries it in front of the derived history, and it is composed BEFORE
+     * this seam fires precisely so a pressure gate counts the prefix the
+     * request will actually send (never a stale logged one). `signal` cancels
+     * any in-flight work a listener starts (e.g. a
      * summarization model call).
      * @param agent - the agent about to open the step.
      * @param turn - the already-open turn this step belongs to.
      * @param step - the number of the step about to start.
      * @param fullSystemPrompt - the assembled prompt, for measuring token pressure.
+     * @param sessionPrefix - the instance's frozen session prefix, for the same measurement.
      * @param signal - aborts in-flight listener work when the turn is torn down.
      * @mode serial
      */
-    // TODO: `fullSystemPrompt` is a smell on a generic per-step seam — compaction
-    // is its only consumer, so a wide event carries a string just one listener
+    // TODO: `fullSystemPrompt`/`sessionPrefix` are a smell on a generic
+    // per-step seam — compaction
+    // is their only consumer, so a wide event carries payloads just one listener
     // reads. Revisit if no second consumer appears: e.g. hand listeners a lazy
     // prompt provider, or move token-pressure measurement behind a
     // compaction-specific seam instead of the shared pre-step checkpoint.
-    'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal): Promise<void> | void
+    'agent/pre-step'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
     /**
      * Waterfall: decide what happens to ONE drained queued message before it
      * becomes a `user/message` — allow (optionally rewriting the prompt bytes or
@@ -367,8 +375,9 @@ declare module 'cordis' {
      * ALL a listener shapes here: every request is a pure function of the
      * session log (the reconstructability RFC), so model-visible content
      * flows through the log channels — `inject()`, steering, prompt-submit
-     * `additionalContext`, prompt sections via `system-prompt/assemble` —
-     * never through request mutation, and the loop records whatever config
+     * `additionalContext`, prompt sections via `system-prompt/assemble`, or
+     * the header-logged session prefix via {@link agent/session-prefix}
+     * — never through request mutation, and the loop records whatever config
      * the request actually uses as a `request/header*` event before dispatch.
      * The step's messages are already snapshotted when this fires (the
      * `step/start` boundary): an `inject()` from a listener here lands in the
@@ -383,6 +392,53 @@ declare module 'cordis' {
      * @mode waterfall
      */
     'agent/request'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+    /**
+     * Waterfall: compose the SESSION PREFIX — request-only messages placed in
+     * front of the ENTIRE derived history (directly after the provider's
+     * system slot) on every request this loop instance sends. Fired ONCE per
+     * loop instance, lazily before its first step's {@link agent/pre-step}
+     * seam — BEFORE the pre-step so a token-pressure gate (compaction) counts
+     * the prefix this instance will actually send, never a previous
+     * instance's logged one. The composed
+     * result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the
+     * instance's anchoring `'initial'`/`'resume'` header snapshot, and reused
+     * verbatim for every subsequent request — never recomputed mid-session,
+     * so the provider prefix cache holds by construction (a process restart
+     * or `ctx.agents.resume()` is a new instance: it recomposes, and any
+     * drift lands attributably on the `'resume'` snapshot). Composition runs
+     * outside the step, before the boundary snapshot: a composing listener's
+     * session append joins the CURRENT request's derived history. A
+     * composition interrupted by a cancel/dispose landing inside the
+     * waterfall is discarded — never cached, logged, or sent — and the next
+     * turn recomposes under a live signal, so an abort-aware listener's
+     * degraded fallback cannot leak into later requests.
+     *
+     * This is the home for session-stable openers the model must always see
+     * but that must NOT become durable history — a skills catalog, an
+     * AGENTS.md digest, a workspace baseline: `Session.deriveMessages()`
+     * never returns the prefix, and the header events are its only durable
+     * record, so the request stays reconstructable from the log. Content
+     * that CHANGES mid-session belongs in the append-only history channels
+     * instead — `agent.inject()`, a `tools/post-execute` decision's
+     * `additionalContext`, prompt-submit `additionalContext` — each a
+     * durable `context/message` paid once and prefix-cached thereafter.
+     *
+     * The seed is a frozen empty list; a contributing listener returns a NEW
+     * array — never an in-place push. The canonical contribution is a
+     * PREPEND, `[mine, ...await next()]`: the waterfall unwinds
+     * innermost-first (the LAST-registered listener's `next()` resolves
+     * first), so prepending yields registration order on the wire, and every
+     * plugin using it composes deterministically. The append form
+     * `[...await next(), mine]` is legal but places a contribution AFTER
+     * every later-registered plugin's — reverse registration order when all
+     * contributors append. Call `next()` to
+     * delegate, or return a list without it to short-circuit.
+     * @param agent - the agent whose session prefix is being composed.
+     * @param prefix - the frozen empty seed; return an extended replacement to contribute.
+     * @param signal - aborts in-flight listener work (e.g. a discovery scan) when the step is torn down.
+     * @mode waterfall
+     */
+    'agent/session-prefix'(agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>
     /**
      * Waterfall: post-process the assembled assistant {@link Message} before
      * tool dispatch (validation, content rewriting, …).

packages/core/session/README.md

@@ -51,7 +51,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
 ### Request-header reconstruction (`request-header.ts`)
 
-The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools ≡ absent fields).
+The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config / whole session prefix) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools/messagePrefix ≡ absent fields; a delta's EMPTY prefix array encodes the transition back to absence). `EpochHeader.messagePrefix` is the durable record of the `agent/session-prefix` waterfall's product — composed once per loop instance, the request is `messagePrefix + derived history`, and `deriveMessages()` never returns it.
 
 ### Session event vocabulary (`types.ts`)
 

packages/core/session/src/request-header.ts

@@ -13,15 +13,23 @@
  */
 
 import { callConfigEquals } from '@deepseek-ai/dsh-llm'
-import type { LlmCallConfig, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { LlmCallConfig, Message, ToolSchema } from '@deepseek-ai/dsh-llm'
 import type { EpochHeader, SessionEvent, SystemDelta, ToolsDelta } from './types.ts'
 
+/** The `request/header-delta` payload shape: each present field amends the folded header. */
+type HeaderDelta = {
+  system?: SystemDelta
+  tools?: ToolsDelta
+  config?: LlmCallConfig
+  messagePrefix?: Message[]
+}
+
 /**
- * Normalize a header to canonical form: an empty system prompt and an empty
- * tool list become ABSENT fields, matching how requests are built (both
- * request-build spreads skip empty values). Diff, fold, and comparison all
- * operate on canonical headers, so "no system prompt" has exactly one
- * representation.
+ * Normalize a header to canonical form: an empty system prompt, an empty
+ * tool list, and an empty session prefix become ABSENT fields, matching how
+ * requests are built (the request-build spreads skip empty values). Diff,
+ * fold, and comparison all operate on canonical headers, so "no system
+ * prompt" (and "no session prefix") has exactly one representation.
  * @param header - the header to normalize (not mutated).
  * @returns the canonical header.
  */
@@ -30,6 +38,7 @@ export function canonicalHeader(header: EpochHeader): EpochHeader {
     config: header.config,
     ...header.system !== undefined && header.system.length > 0 ? { system: header.system } : {},
     ...header.tools !== undefined && header.tools.length > 0 ? { tools: header.tools } : {},
+    ...header.messagePrefix !== undefined && header.messagePrefix.length > 0 ? { messagePrefix: header.messagePrefix } : {},
   }
 }
 
@@ -109,37 +118,46 @@ function applyTools(prev: readonly ToolSchema[], delta: ToolsDelta): ToolSchema[
  * writer's round-trip guard runs (`applyHeaderDelta(prev, delta)` must equal
  * the intended header) and the loop runs to skip logging an unchanged header.
  * Tools compare per-schema IN ORDER (canonical JSON), so a pure reordering is
- * correctly unequal.
+ * correctly unequal; the session prefix compares as canonical JSON (both
+ * sides come from the same build path, so key order matches when the values
+ * do).
  * @param a - one canonical header.
  * @param b - the other.
- * @returns whether config, system, and tools (in order) all match.
+ * @returns whether config, system, tools (in order), and the session prefix all match.
  */
 export function headerEquals(a: EpochHeader, b: EpochHeader): boolean {
   if (!callConfigEquals(a.config, b.config) || a.system !== b.system) return false
+  if (!sameMessages(a.messagePrefix, b.messagePrefix)) return false
   const at = a.tools ?? []
   const bt = b.tools ?? []
   return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema))
 }
 
+/** Canonical JSON equality over session-prefix arrays; absence equals the empty array. */
+function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean {
+  return JSON.stringify(a ?? []) === JSON.stringify(b ?? [])
+}
+
 /**
  * Compute the `request/header-delta` payload between two canonical headers,
  * or undefined when they are equal. The caller MUST round-trip the result
  * ({@link applyHeaderDelta} on `prev` deep-equals `next`) before logging it —
  * the encoding cannot express every change (a pure tool reordering) — and
  * fall back to a full `request/header` snapshot when the check fails.
+ * The session prefix is replaced whole (small advisory content, not worth
+ * diffing); an empty replacement array encodes the transition to "none".
  * @param prev - the folded header the log currently implies.
  * @param next - the header the next request will actually use.
  * @returns the delta payload, or undefined when nothing changed.
  */
-export function diffHeader(
-  prev: EpochHeader, next: EpochHeader,
-): { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } | undefined {
-  const delta: { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } = {}
+export function diffHeader(prev: EpochHeader, next: EpochHeader): HeaderDelta | undefined {
+  const delta: HeaderDelta = {}
   if (prev.system !== next.system) delta.system = diffSystem(prev.system, next.system)
   const prevTools = prev.tools ?? []
   const nextTools = next.tools ?? []
   if (JSON.stringify(prevTools) !== JSON.stringify(nextTools)) delta.tools = diffTools(prevTools, nextTools)
   if (!callConfigEquals(prev.config, next.config)) delta.config = next.config
+  if (!sameMessages(prev.messagePrefix, next.messagePrefix)) delta.messagePrefix = next.messagePrefix ?? []
   return Object.keys(delta).length > 0 ? delta : undefined
 }
 
@@ -151,15 +169,15 @@ export function diffHeader(
  * @param delta - the logged delta payload.
  * @returns the canonical header after the delta.
  */
-export function applyHeaderDelta(
-  prev: EpochHeader, delta: { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig },
-): EpochHeader {
+export function applyHeaderDelta(prev: EpochHeader, delta: HeaderDelta): EpochHeader {
   const system = delta.system !== undefined ? applySystem(prev.system, delta.system) : prev.system
   const tools = delta.tools !== undefined ? applyTools(prev.tools ?? [], delta.tools) : prev.tools
+  const messagePrefix = delta.messagePrefix ?? prev.messagePrefix
   return canonicalHeader({
     config: delta.config ?? prev.config,
     ...system !== undefined ? { system } : {},
     ...tools !== undefined ? { tools } : {},
+    ...messagePrefix !== undefined ? { messagePrefix } : {},
   })
 }
 

packages/core/session/src/types.ts

@@ -1,5 +1,5 @@
 import type { Branded } from '@deepseek-ai/dsh-brand'
-import type { CallId, ContentBlock, LlmCallConfig, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { CallId, ContentBlock, LlmCallConfig, Message, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm'
 
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>
@@ -183,14 +183,15 @@ export interface TodoItem {
 }
 
 /**
- * The request header: everything about an LLM request besides its message
- * content — the call configuration plus the rendered system prompt and tool
- * schemas. Logged session state (the reconstructability RFC): a
+ * The request header: everything about an LLM request besides its derived
+ * message history — the call configuration plus the rendered system prompt,
+ * tool schemas, and the session prefix. Logged session state (the
+ * reconstructability RFC): a
  * {@link SessionEventMap} `request/header` snapshot installs one, a
  * `request/header-delta` amends it, and folding those events over the log
  * (`foldRequestHeader`) reconstructs the header any request was built under.
- * Canonical form: an empty system prompt and an empty tool list are ABSENT
- * fields, matching how requests are built.
+ * Canonical form: an empty system prompt, an empty tool list, and an empty
+ * prefix are ABSENT fields, matching how requests are built.
  */
 export interface EpochHeader {
   /** The conversation's call configuration (model + sampling scalars). */
@@ -199,6 +200,14 @@ export interface EpochHeader {
   system?: string
   /** Assembled tool schemas; absent for a tool-less request. */
   tools?: ToolSchema[]
+  /**
+   * The session prefix: request-only messages sent BEFORE the entire derived
+   * history (the `agent/session-prefix` waterfall's product, composed once
+   * per loop instance and reused for every request it sends). Not session
+   * history — `deriveMessages()` never returns it — so the header is its
+   * only durable record; absent when the instance composed none.
+   */
+  messagePrefix?: Message[]
 }
 
 /**
@@ -356,15 +365,21 @@ export interface SessionEventMap {
   'request/header': { header: EpochHeader; reason: RequestHeaderReason }
   /**
    * Amendment to the folded {@link EpochHeader}: at least one of a
-   * {@link SystemDelta}, a {@link ToolsDelta}, or a whole replacement
-   * {@link LlmCallConfig} (four scalars — not worth diffing). Appended by the
+   * {@link SystemDelta}, a {@link ToolsDelta}, a whole replacement
+   * {@link LlmCallConfig} (four scalars — not worth diffing), or a whole
+   * replacement session prefix (`messagePrefix` — small advisory content,
+   * replaced whole; an EMPTY array encodes the transition to "none",
+   * mirroring the canonical form's absent field — the loop never produces
+   * one in practice: the prefix is composed once per instance and anchored
+   * by that instance's snapshot, so this arm exists for codec totality).
+   * Appended by the
    * loop inside the step, before dispatch, when the header for this request
    * differs from the fold of the log so far; the writer verifies
    * `applyHeaderDelta(previous, delta)` reproduces the new header exactly and
    * falls back to a `'fallback'` `request/header` snapshot when it cannot, so
    * a logged delta ALWAYS round-trips. NOT a {@link SurfaceEventType}.
    */
-  'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
+  'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] }
 }
 
 /** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */

packages/core/session/tests/request-header.spec.ts

@@ -8,9 +8,9 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session'
 import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
-import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
 
 const CONFIG = { model: 'm' }
 
@@ -18,6 +18,10 @@ function tool(name: string, description = 'd'): ToolSchema {
   return { name, description, parameters: { type: 'object' } }
 }
 
+function msg(text: string): Message {
+  return { role: 'user', content: [{ type: 'text', text }] }
+}
+
 /** Round-trip helper: diff must reproduce `next` from `prev` exactly. */
 function roundTrip(prev: EpochHeader, next: EpochHeader): ReturnType<typeof diffHeader> {
   const delta = diffHeader(prev, next)
@@ -103,6 +107,48 @@ describe('diffHeader / applyHeaderDelta', () => {
   })
 })
 
+describe('the session prefix (messagePrefix)', () => {
+  it('canonicalHeader normalizes an empty prefix to an absent field', () => {
+    expect(canonicalHeader({ config: CONFIG, messagePrefix: [] })).toEqual({ config: CONFIG })
+    const full = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] })
+    expect(full.messagePrefix).toEqual([msg('p')])
+  })
+
+  it('headerEquals treats absence and empty as one representation, content differences as unequal', () => {
+    expect(headerEquals(canonicalHeader({ config: CONFIG }), { config: CONFIG, messagePrefix: [] })).toBe(true)
+    expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG, messagePrefix: [msg('b')] })).toBe(false)
+    expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG })).toBe(false)
+  })
+
+  it('replaces a changed prefix whole and leaves untouched parts alone', () => {
+    const prev = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('old')] })
+    const next = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('new'), msg('more')] })
+    const delta = roundTrip(prev, next)
+    expect(delta).toEqual({ messagePrefix: [msg('new'), msg('more')] })
+  })
+
+  it('round-trips a prefix gained from a bare header and lost back to one (empty array encodes absence)', () => {
+    const none = canonicalHeader({ config: CONFIG })
+    const some = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] })
+    const gained = roundTrip(none, some)
+    expect(gained).toEqual({ messagePrefix: [msg('p')] })
+    const lost = roundTrip(some, none)
+    expect(lost).toEqual({ messagePrefix: [] })
+  })
+
+  it('folds prefix deltas over the log like any other header amendment', () => {
+    const session = new Session(SessionId('fold-prefix'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const first = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v1')] })
+    session.append('request/header', { header: first, reason: 'initial' })
+    const second = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v2')] })
+    session.append('request/header-delta', diffHeader(first, second)!)
+    expect(foldRequestHeader(session.events)).toEqual(second)
+    session.append('request/header-delta', diffHeader(second, canonicalHeader({ config: CONFIG }))!)
+    expect(foldRequestHeader(session.events)).toEqual({ config: CONFIG })
+  })
+})
+
 describe('foldRequestHeader', () => {
   function headerEvents(session: Session): readonly SessionEvent[] {
     return session.events

packages/core/tools/README.md

@@ -1,9 +1,18 @@
 # dsh-tools
 
-Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the allow/deny gate) → `tools/execute` (an around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the result, attach context).
+Tool registry and execution pipeline. Tool plugins register their schemas and executors; the agent loop executes each call through `tools/pre-execute` (the allow/deny gate) → `tools/execute` (an around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the result, attach context). The registry also owns HOW its tools are presented to the model — its `mode` config selects native function calling, [Code Mode](#code-mode), or both.
 
 ## Service: `ToolRegistry` (ctx key: `tools`)
 
+### Config
+
+```yaml
+tools:
+  mode: native   # native (default) | code | both
+```
+
+`native` contributes every registered tool as a wire function definition — the default, byte-for-byte the pre-config behavior. `code` contributes exactly ONE wire tool, `run_code`, plus the generated `tools:sdk` prompt section (see [Code Mode](#code-mode)). `both` contributes every native definition AND `run_code` + the SDK section. Non-native modes require a loaded `ctx.codeRuntime` with `language: 'typescript'`; a missing or mismatched runtime rejects every prompt assembly with an actionable error, and a `systemPrompt.toolOrder` naming tools the mode no longer contributes rejects the assembly the same way.
+
 ### Public API
 
 - `ctx.tools.register(definition: ToolDefinition): () => void` Register a tool. Disposed with the calling fiber.
@@ -119,6 +128,16 @@ const bash = defineTool({
 })
 ```
 
+### Code Mode
+
+Under `mode: code` (or `both`) the registry turns the tool surface into a programming API, per the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md): the model writes a TypeScript program (the body of an async function) and passes it to the ONE wire tool `run_code`; the program runs in `ctx.codeRuntime` (the [code-execution seam](../../code-runtime/README.md) — the shipped backend is a worker thread) with one async binding per registered tool (`await tools.bash({...})`), and ONLY what it prints or returns re-enters the model's context.
+
+- **The SDK section** (`tools:sdk`, order 150): a lazy prompt section regenerating, at each assembly, a `declare const tools: {...}` TypeScript declaration of every registered tool except `run_code` (exotic names via quoted keys), plus fixed usage instructions. Deterministic — lexicographic tool order, byte-identical text for an unchanged tool set (prefix-cache-friendly). The codegen (`jsonSchemaToTs`, exported) is TOTAL: constructs outside the `defineTool` subset degrade to `unknown`, never throw.
+- **The dispatch bridge** (`run_code`'s execute): every binding call is JSON-normalized BEFORE dispatch (a value that does not survive — `BigInt`, circulars — rejects that one call, so the dispatched form and the logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes the underlying `ctx.tools.execute()` calls one at a time in submission order — the tool contract carries no concurrency-safety metadata yet), gated by `tools/pre-execute`/`tools/post-execute` like any native call (a deny reaches the program as a binding rejection), and logged as one `tool/code-dispatch` session event (log-only: `deriveMessages()` never surfaces it) with the deterministic sub-id `<parent>:code:<n>`. A failed sub-call REJECTS the program-side promise with the tool's error text — real code error handling, no bespoke envelope. A sub-call's `additionalContext` is deliberately DROPPED (no safe outlet mid-run without breaking tool-call/result adjacency; deferred until a real hook needs it through Code Mode).
+- **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from.
+
+The wire collapse is the registry's own contribution (`systemPrompt.tools()` is mode-aware), so the logged `request/header` records it for free — under `code`, the assembled tool list is exactly `[run_code]`, pinned by tests and the snapshot goldens. Try it: `pnpm run demo:code-mode` ([the coding-agent example's Code Mode overlay](../../../examples/coding-agent/README.md#code-mode)); `pnpm run demo:code-mode acp` serves the same mode over ACP instead of the REPL.
+
 ### What is NOT here (TODO)
 
 - **Tool shapes review** — when real tools land (e.g. a concurrency-safety hint for parallel execution); phase 1 executes tool calls sequentially.

packages/core/tools/package.json

@@ -23,13 +23,20 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-code-runtime": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }

packages/core/tools/src/code-mode.ts

@@ -0,0 +1,318 @@
+/**
+ * Code Mode: the `run_code` tool and its dispatch bridge. The model writes a
+ * TypeScript program; the bridge hands it to `ctx.codeRuntime` with one
+ * async binding per registered tool, serializes every binding call through a
+ * per-run queue onto `ToolRegistry.execute()` (so `tools/pre-execute` /
+ * `tools/post-execute` gate sub-calls exactly like native ones), logs each
+ * sub-dispatch as a `tool/code-dispatch` session event, and returns only the
+ * program's curated output. The registry itself decides WHEN this tool
+ * exists (its `mode` config); this module owns only the tool and the bridge.
+ *
+ * @module @deepseek-ai/dsh-tools/src/code-mode
+ */
+
+import { inspect } from 'node:util'
+import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { CodeBindingFunction, CodeRunResult, CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
+import type {} from '@deepseek-ai/dsh-session'
+import { defineTool } from './schema.ts'
+import type { ToolDefinition, ToolRegistry } from './index.ts'
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /**
+     * One bridged sub-dispatch from a `run_code` program: the parent
+     * `run_code` call id, the deterministic sub-call id
+     * (`<parent>:code:<n>`), the tool `name` with its JSON-normalized
+     * `arguments` — the exact value dispatched, normalized BEFORE dispatch,
+     * so this append can never fail on payload shape — whether the sub-call
+     * errored, and a bounded `resultSummary` of its model-facing text.
+     * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
+     * model context; persistence and UIs get every call. Appended inside the
+     * parent `run_code`'s execution (the bridge drains its queue before
+     * returning), so the turn-enclosure invariant holds by construction.
+     */
+    'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; resultSummary: string }
+  }
+}
+
+/** The model-facing name of the Code Mode tool. */
+export const RUN_CODE_NAME = 'run_code'
+
+/** The `tools:sdk` section order: inside the 100–199 tool-guidance band, after per-tool guidance sections. */
+export const SDK_SECTION_ORDER = 150
+
+/**
+ * Thrown by `run_code` when the program run itself failed — a program
+ * exception, a budget expiry, an abort, or substrate death. Extends
+ * {@link HarnessError} (`code: 'CODE_RUN_FAILED'`); the registry's execution
+ * pipeline converts it into a structured `isError` result whose text carries
+ * the failure kind plus the captured logs, so the model can self-correct.
+ */
+export class CodeRunFailedError extends HarnessError {
+  constructor(message: string) {
+    super(message, 'CODE_RUN_FAILED')
+    this.name = 'CodeRunFailedError'
+  }
+}
+
+/**
+ * Cap for a `tool/code-dispatch` event's `resultSummary`. A log-ergonomics
+ * constant, not config: the full result already flows to the program; the
+ * summary exists so log readers see what a sub-call returned at a glance.
+ */
+const SUMMARY_MAX_CHARS = 200
+
+/** Bounded inspect for rendering a program's completion value into the model-facing text. */
+const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const
+
+/** Join a result's text blocks; a non-text block becomes a placeholder (an MVP limitation, stated in the SDK instructions). */
+function textOf(content: ContentBlock[]): string {
+  return content
+    .map((block) => {
+      switch (block.type) {
+        case 'text': return block.text
+        // ContentBlockMap is merge-extensible — future block kinds land here
+        // deliberately (no assertNever on merge-extensible unions).
+        default: return `[${block.type} content]`
+      }
+    })
+    .join('\n')
+}
+
+/** Bound a sub-call's model-facing text for the log event's `resultSummary`. */
+function summarize(text: string): string {
+  return text.length > SUMMARY_MAX_CHARS ? `${text.slice(0, SUMMARY_MAX_CHARS)}…` : text
+}
+
+/**
+ * JSON-normalize one binding call's argument into TWO independent parses of
+ * the same canonical text: `dispatched` goes to the tool, `logged` to the
+ * `tool/code-dispatch` event — identical by construction (the runtime's
+ * structured-clone boundary is wider than JSON; the session log accepts only
+ * JSON), and separate objects, so a tool mutating its args can neither
+ * desync the log from what was dispatched nor re-poison the append. A value
+ * that does not survive the round-trip (`undefined` — the log rejects it as
+ * event data — `BigInt`, a circular structure, a bare function) rejects that
+ * one call BEFORE dispatch with a model-correctable error: nothing ever
+ * executes unlogged.
+ */
+function jsonNormalizeArgs(value: unknown): { dispatched: unknown; logged: unknown } {
+  if (value === undefined) {
+    throw new Error('tool arguments must be JSON-serializable (call the tool with an arguments object, e.g. `{}`)')
+  }
+  let text: string | undefined
+  try {
+    text = JSON.stringify(value)
+  } catch (error: unknown) {
+    throw new Error(`tool arguments must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  // JSON.stringify's lib type claims `string`, but a bare function or symbol
+  // root really yields `undefined` at runtime — the guard is live.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (text === undefined) throw new Error('tool arguments must be JSON-serializable (got a value JSON cannot represent)')
+  return { dispatched: JSON.parse(text) as unknown, logged: JSON.parse(text) as unknown }
+}
+
+/** Render the program's completion value for the model-facing result text (`''` when the program returned nothing). */
+function renderValue(value: unknown): string {
+  if (value === undefined) return ''
+  return typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS)
+}
+
+/** The run_code result's `meta` payload (JSON-serializable; `presentResult` narrows it back). */
+interface RunCodeMeta {
+  logs: CodeRunResult['logs']
+  dispatches: number
+}
+
+/** Soft-narrow a result `meta` back to {@link RunCodeMeta} (replay may carry older shapes; presentation must not throw). */
+function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined {
+  if (typeof meta !== 'object' || meta === null) return undefined
+  const m = meta as Record<string, unknown>
+  if (!Array.isArray(m.logs) || typeof m.dispatches !== 'number') return undefined
+  return m as unknown as RunCodeMeta
+}
+
+/**
+ * Build the `run_code` {@link ToolDefinition}: one required `code` parameter,
+ * executed through the dispatch bridge described in the module doc. The
+ * registry registers it under non-native modes.
+ * @param registry - the owning registry (sub-calls go through its `execute`,
+ *   bindings cover its registered tools).
+ * @param requireRuntime - resolves `ctx.codeRuntime` or throws the loud
+ *   misconfiguration error (shared with the registry's assembly-time checks).
+ * @returns the registry-ready definition.
+ */
+export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () => CodeRuntime): ToolDefinition {
+  return defineTool({
+    name: RUN_CODE_NAME,
+    description:
+      'Execute a TypeScript program against the available tools. Write the BODY of an '
+      + 'async function (erasable syntax only; top-level `await` and `return` work) and '
+      + 'call tools as `await tools.name(args)` per the declarations in the system prompt. '
+      + 'Only what you print or return comes back — curate it.',
+    parameters: {
+      code: { type: 'string', required: true, description: 'The program: the body of an async TypeScript function.' },
+    },
+    async execute(args, exec) {
+      const runtime = requireRuntime()
+
+      // The run-scoped abort: follows the outer signal in, and fires when the
+      // run settles for ANY reason, so an in-flight sub-dispatch is aborted
+      // (its executor kills on this signal) instead of orphaned, and
+      // queued-unstarted dispatches are abandoned.
+      const runController = new AbortController()
+      const onOuterAbort = (): void => { runController.abort(exec.signal?.reason) }
+      if (exec.signal?.aborted) onOuterAbort()
+      exec.signal?.addEventListener('abort', onOuterAbort, { once: true })
+
+      let dispatches = 0
+      // The per-run serialization queue: every binding call chains onto the
+      // tail, so even `Promise.all` executes the underlying tool calls one at
+      // a time in submission order (the tool contract carries no
+      // concurrency-safety metadata yet). The fold keeps the tail non-rejecting
+      // so one failed dispatch never poisons the chain.
+      let queue: Promise<void> = Promise.resolve()
+      const enqueue = <T>(task: () => Promise<T>): Promise<T> => {
+        const turn = queue.then(() => {
+          if (runController.signal.aborted) {
+            throw new Error(`run_code run is over (${String(runController.signal.reason)}); tool call abandoned`)
+          }
+          return task()
+        })
+        queue = turn.then(() => undefined, () => undefined)
+        return turn
+      }
+
+      // Read through a call, not a bare property: the abort state genuinely
+      // changes across awaits, and a direct `.aborted` re-check after one
+      // would be narrowed away by control flow analysis.
+      const runOver = (): boolean => runController.signal.aborted
+
+      const binding = (name: string): CodeBindingFunction => async (rawArgs: unknown): Promise<unknown> => {
+        if (runOver()) {
+          throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`)
+        }
+        const normalized = jsonNormalizeArgs(rawArgs)
+        const outcome = await enqueue(async () => {
+          const n = ++dispatches
+          const subCallId = CallId(`${String(exec.callId)}:code:${n}`)
+          const result = await registry.execute({
+            callId: subCallId,
+            name,
+            arguments: normalized.dispatched,
+            ...exec.agent ? { agent: exec.agent } : {},
+            signal: runController.signal,
+          })
+          const text = textOf(result.content)
+          // Sub-call `additionalContext` is deliberately DROPPED here: the
+          // loop's buffering (append after the step's tool/results) has no
+          // safe analogue from inside a running run_code — injecting now
+          // would break tool-call/result adjacency. Deferred until a real
+          // hook needs it through Code Mode.
+          exec.agent?.session.append('tool/code-dispatch', {
+            parentCallId: exec.callId,
+            subCallId,
+            name,
+            // The SIBLING parse of the dispatched value: byte-identical JSON,
+            // but a separate object — a tool mutating its args cannot desync
+            // this record from what it actually received.
+            arguments: normalized.logged,
+            isError: result.isError,
+            resultSummary: summarize(text),
+          })
+          return { text, isError: result.isError }
+        })
+        // A budget expiry or outer cancel that lands while this call was in
+        // flight already aborted the dispatch; stop the program now rather
+        // than hand it a result from a run that is over.
+        if (runOver()) {
+          throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`)
+        }
+        // A failed tool call REJECTS — real code signals failure by throwing,
+        // so try/catch and Promise.all short-circuiting behave as models
+        // expect (the error text is the tool's model-facing result text).
+        if (outcome.isError) throw new Error(outcome.text)
+        return outcome.text
+      }
+
+      // Null-prototype + defineProperty, mirroring the worker-side namespace
+      // build: a registered tool named `__proto__` must become an ordinary
+      // own key (a plain-object assignment would hit the prototype setter,
+      // silently dropping the binding), and the runtime host resolves
+      // binding names as own properties only.
+      const functions: Record<string, CodeBindingFunction> = Object.create(null) as Record<string, CodeBindingFunction>
+      for (const schema of registry.schemas()) {
+        if (schema.name === RUN_CODE_NAME) continue
+        Object.defineProperty(functions, schema.name, { enumerable: true, value: binding(schema.name) })
+      }
+
+      try {
+        let result: CodeRunResult
+        try {
+          result = await runtime.run({
+            program: args.code,
+            bindings: [{ global: 'tools', functions }],
+            signal: runController.signal,
+          })
+        } finally {
+          // Quiescence before returning, whether the runtime fulfilled or
+          // REJECTED (a backend that starts a binding call and then throws
+          // must not leak a live sub-dispatch past this settlement): fire
+          // the run-scoped abort (cancelling an in-flight sub-dispatch,
+          // abandoning queued ones), then await the queue's drain — an
+          // aborted sub-call still settles and logs its event INSIDE the
+          // open turn; nothing can append after we return. `queue` is the
+          // FOLDED tail (every link swallows its rejection into undefined),
+          // so this await cannot itself reject — an abandoned queued call
+          // can never mask the runtime's own failure, returned or thrown;
+          // rejections surface only on the per-call promises the program
+          // holds.
+          runController.abort('run_code settled')
+          await queue
+        }
+
+        if (result.error) {
+          const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.map(entry => entry.text).join('\n')}` : ''
+          throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`)
+        }
+        const rendered = renderValue(result.value)
+        const parts = [result.logs.map(entry => entry.text).join('\n'), rendered].filter(part => part.length > 0)
+        const meta: RunCodeMeta = { logs: result.logs, dispatches }
+        return {
+          content: [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }],
+          meta,
+        }
+      } finally {
+        exec.signal?.removeEventListener('abort', onOuterAbort)
+      }
+    },
+    // The program IS the title, the way command tools title their cards with
+    // the command: an execute-card's title is the one slot an ACP client
+    // always shows (Zed's execute cards render no body content and no raw
+    // input without a real terminal attached), so anywhere else the code
+    // would be invisible. Multi-line titles are the execute-card idiom —
+    // capable clients render them whole; others truncate to the first line
+    // and still hold the full program in rawInput.
+    presentCall: args => ({
+      card: 'generic',
+      title: args.code,
+      kind: 'execute',
+      rawInput: args.code,
+    }),
+    // Title omitted on the result: an update replaces only the fields it
+    // carries, so the pending card's program title persists through
+    // completion; the captured output rides as body content.
+    presentResult: (_args, result) => {
+      const meta = asRunCodeMeta(result.meta)
+      if (!meta) return undefined
+      const output = meta.logs.map(entry => entry.text).join('\n')
+      return {
+        card: 'generic',
+        ...output.length > 0 ? { content: [{ type: 'text' as const, text: output }] } : {},
+      }
+    },
+  })
+}

packages/core/tools/src/index.ts

@@ -6,15 +6,26 @@
  * (inspect/replace the result, attach context) for sandbox, permission, and hook
  * plugins to gate or transform a call.
  *
+ * The registry also owns HOW its tools are presented to the model — its
+ * `mode` config: `'native'` (every tool as a wire function definition,
+ * today's behavior and the default), `'code'` (the wire carries exactly one
+ * tool, `run_code`, plus a generated TypeScript SDK prompt section), or
+ * `'both'`. See `code-mode.ts` (the tool + dispatch bridge) and
+ * `ts-types.ts` (the SDK codegen); design in the Code Mode RFC.
+ *
  * @module @deepseek-ai/dsh-tools
  */
 
 import { Context, Service } from 'cordis'
+import z from 'schemastery'
 import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-system-prompt'
+import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
+import { createRunCodeTool, RUN_CODE_NAME, SDK_SECTION_ORDER } from './code-mode.ts'
+import { renderToolsSdk } from './ts-types.ts'
 
 export {
   defineTool,
@@ -39,6 +50,9 @@ export {
   type StructuredScalar,
 } from './json-schema.ts'
 
+export { CodeRunFailedError, RUN_CODE_NAME } from './code-mode.ts'
+export { jsonSchemaToTs, renderToolsSdk } from './ts-types.ts'
+
 // The render-intent vocabulary a tool declares via `presentCall`/`presentResult`
 // lives in its own UI-facing module; re-export it so `@deepseek-ai/dsh-tools`
 // stays the single public surface for consumers (producers + the ACP bridge).
@@ -298,20 +312,100 @@ function errorInfo(error: unknown): ToolErrorInfo | undefined {
   return error instanceof HarnessError ? { name: error.name, code: error.code } : undefined
 }
 
+/** How the registry presents its tools to the model (see {@link Config.mode}). */
+export type ToolPresentationMode = 'native' | 'code' | 'both'
+
+/** Plugin config: how the registered tools are presented to the model. */
+export interface Config {
+  /**
+   * The presentation mode. `'native'` (the default) contributes every
+   * registered tool as a wire function definition — byte-for-byte today's
+   * behavior. `'code'` contributes exactly ONE wire tool, `run_code`, plus
+   * the generated `tools:sdk` prompt section declaring every other tool as a
+   * TypeScript API the program calls. `'both'` contributes every native
+   * definition AND `run_code` + the SDK section. Non-native modes require a
+   * loaded `ctx.codeRuntime` whose `language` is `'typescript'` — a missing
+   * or mismatched runtime rejects every prompt assembly with an actionable
+   * error (misconfiguration fails loud, before any model request). A
+   * configured `systemPrompt.toolOrder` naming native tools likewise rejects
+   * every assembly under `'code'` (those names are no longer contributed) —
+   * a deployment switching modes updates its order config or drops it.
+   */
+  mode?: ToolPresentationMode
+}
+
 /**
  * Tool registry (`ctx.tools`): tool plugins register definitions; the agent
  * loop executes calls through the `tools/pre-execute` → `tools/execute` →
  * `tools/post-execute` pipeline. The registry contributes its schemas into the
- * system-prompt assembly.
+ * system-prompt assembly — WHICH schemas is governed by its `mode` config
+ * (see {@link Config.mode}); under a non-native mode it also registers the
+ * `run_code` tool and the `tools:sdk` prompt section itself.
  */
 export class ToolRegistry extends Service {
   static inject = ['systemPrompt']
 
-  private store = new Map<string, ToolDefinition>()
+  static Config: z<Config> = z.object({
+    mode: z.union(['native', 'code', 'both'] as const).default('native'),
+  })
 
-  constructor(ctx: Context) {
+  private store = new Map<string, ToolDefinition>()
+  private readonly mode: ToolPresentationMode
+
+  constructor(ctx: Context, config: Config = {}) {
     super(ctx, 'tools')
-    ctx.systemPrompt.tools(() => this.schemas())
+    // The schema already defaulted an omitted mode; the ?? narrows the
+    // optional-input type for direct (non-Loader) construction in tests.
+    this.mode = config.mode ?? 'native'
+    ctx.systemPrompt.tools(() => this.wireSchemas())
+    if (this.mode !== 'native') {
+      this.register(createRunCodeTool(this, () => this.requireCodeRuntime()))
+      ctx.systemPrompt.section({
+        name: 'tools:sdk',
+        order: SDK_SECTION_ORDER,
+        // A lazy thunk over the live store: regenerated at each assembly, in
+        // lexicographic tool order, so an unchanged tool set renders
+        // byte-identical text (prefix-cache-friendly) and a mid-session
+        // registration surfaces exactly like a native-mode tool change.
+        text: () => {
+          this.requireCodeRuntime()
+          return renderToolsSdk(this.schemas().filter(schema => schema.name !== RUN_CODE_NAME))
+        },
+      })
+    }
+  }
+
+  /**
+   * The registry's contribution to the wire tool list, per {@link Config.mode}.
+   * Because `PromptAssembly.tools` is what the loop's request header
+   * snapshots, the mode's collapse is logged and reconstructable for free.
+   * Under a non-native mode this is also the loud misconfiguration gate: no
+   * usable code runtime → every assembly rejects before any model request.
+   */
+  private wireSchemas(): ToolSchema[] {
+    if (this.mode === 'native') return this.schemas()
+    this.requireCodeRuntime()
+    const all = this.schemas()
+    return this.mode === 'code' ? all.filter(schema => schema.name === RUN_CODE_NAME) : all
+  }
+
+  /**
+   * Resolve the code runtime or throw the actionable misconfiguration error.
+   * Read at use time (assembly / run_code execution), NOT via static
+   * `inject`: an inject entry would hold `ctx.tools` — and every tool plugin
+   * behind it — hostage to a code runtime existing even under `mode:
+   * 'native'` (the loop's optional-backend idiom, same as
+   * `sessionPersistence`).
+   */
+  private requireCodeRuntime(): CodeRuntime {
+    const runtime = this.ctx.get('codeRuntime')
+    if (!runtime) {
+      throw new Error(`dsh-tools: mode "${this.mode}" requires a code runtime — load a ctx.codeRuntime implementation (e.g. @deepseek-ai/dsh-code-runtime-worker) or set tools mode to "native"`)
+    }
+    if (runtime.language !== 'typescript') {
+      throw new Error(`dsh-tools: mode "${this.mode}" generates a TypeScript SDK, but the loaded code runtime's language is "${runtime.language}"`)
+    }
+    return runtime
   }
 
   /**

packages/core/tools/src/ts-types.ts

@@ -0,0 +1,121 @@
+/**
+ * Code Mode codegen: the pure projection from registered tool schemas to the
+ * TypeScript SDK text the model programs against (the `tools:sdk` prompt
+ * section). Sibling of `json-schema.ts` — `schemas()` (native function
+ * calling) and this module (the generated `declare const tools` surface) are
+ * two projections of the same store.
+ *
+ * TOTAL by design: {@link jsonSchemaToTs} maps the JSON-Schema subset the
+ * `defineTool` DSL emits and degrades every construct outside it (`$ref`,
+ * `oneOf`, `integer`, future MCP shapes, …) to `unknown` without ever
+ * throwing — codegen must never be the thing that fails an assembly.
+ * Deterministic: a fixed tool set renders byte-identical text (tools in
+ * lexicographic name order), so the section is prefix-cache-friendly.
+ *
+ * @module @deepseek-ai/dsh-tools/src/ts-types
+ */
+
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+
+/** Property names that are valid bare TS identifiers; anything else is quoted. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/** Render an object key: bare when it is a valid identifier, quoted otherwise (every name stays reachable, no aliasing). */
+function renderKey(name: string): string {
+  return IDENTIFIER.test(name) ? name : JSON.stringify(name)
+}
+
+/** One `indent`-deep line prefix (two spaces per level). */
+function pad(indent: number): string {
+  return '  '.repeat(indent)
+}
+
+/** A one-line JSDoc block for a schema `description`, or no lines when there is none. */
+function docLines(description: unknown, indent: number): string[] {
+  if (typeof description !== 'string' || description.length === 0) return []
+  // Keep the doc a single-line comment per property: descriptions are prose
+  // (possibly with newlines); collapse whitespace so the rendered SDK stays
+  // stable and compact. A comment-closer inside the description is escaped so
+  // it cannot terminate the generated JSDoc early.
+  const collapsed = description.replace(/\s+/g, ' ').trim()
+  return [`${pad(indent)}/** ${collapsed.replaceAll('*/', String.raw`*\/`)} */`]
+}
+
+/**
+ * Map one JSON-Schema node to a TypeScript type literal. Handles exactly the
+ * subset the `defineTool` DSL emits — `object` (`properties` + `required`),
+ * `string` (with `enum` → a literal union), `number`, `boolean`, `array`
+ * (`items`) — and returns `unknown` for anything else, without throwing.
+ * @param schema - the JSON-Schema node (any shape; hostile inputs degrade).
+ * @param indent - the indentation level for nested object members.
+ * @returns the TS type text (multi-line for objects with properties).
+ */
+export function jsonSchemaToTs(schema: unknown, indent = 0): string {
+  if (typeof schema !== 'object' || schema === null) return 'unknown'
+  const node = schema as Record<string, unknown>
+  switch (node.type) {
+    case 'string': {
+      if (Array.isArray(node.enum) && node.enum.length > 0 && node.enum.every(value => typeof value === 'string')) {
+        return node.enum.map(value => JSON.stringify(value)).join(' | ')
+      }
+      return 'string'
+    }
+    case 'number': return 'number'
+    case 'boolean': return 'boolean'
+    case 'array': {
+      const item = jsonSchemaToTs(node.items, indent)
+      // Parenthesize a union item type so `('a' | 'b')[]` parses as intended.
+      return item.includes('|') ? `(${item})[]` : `${item}[]`
+    }
+    case 'object': {
+      const properties = node.properties
+      if (typeof properties !== 'object' || properties === null) return 'Record<string, unknown>'
+      const entries = Object.entries(properties as Record<string, unknown>)
+      if (entries.length === 0) return 'Record<string, unknown>'
+      const required = new Set(Array.isArray(node.required) ? node.required.filter(name => typeof name === 'string') : [])
+      const lines: string[] = ['{']
+      for (const [name, prop] of entries) {
+        const description = typeof prop === 'object' && prop !== null ? (prop as Record<string, unknown>).description : undefined
+        lines.push(...docLines(description, indent + 1))
+        lines.push(`${pad(indent + 1)}${renderKey(name)}${required.has(name) ? '' : '?'}: ${jsonSchemaToTs(prop, indent + 1)};`)
+      }
+      lines.push(`${pad(indent)}}`)
+      return lines.join('\n')
+    }
+    default: return 'unknown'
+  }
+}
+
+/** The fixed model-facing usage contract rendered above the declarations (see the Code Mode RFC's "What the model sees"). */
+const SDK_INSTRUCTIONS = `## Writing code for run_code
+
+Pass \`run_code\` the body of an async TypeScript function (erasable syntax only — no \`enum\` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:
+
+- Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
+- A FAILED tool call rejects with an \`Error\` carrying the tool's error text — \`try/catch\` it to handle and continue.
+- Calls execute sequentially, even under \`Promise.all\`.
+- Emit results with \`return\` and/or \`console.log(...)\`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.
+
+The available tools:`
+
+/**
+ * Render the full `tools:sdk` prompt section: the fixed usage instructions
+ * plus one `declare const tools` interface covering every given tool.
+ * Deterministic — tools are emitted in lexicographic name order, so an
+ * unchanged tool set produces byte-identical text across assemblies.
+ * @param schemas - the tool schemas to declare (the caller excludes
+ *   `run_code` itself).
+ * @returns the complete section text.
+ */
+export function renderToolsSdk(schemas: ToolSchema[]): string {
+  const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+  const members: string[] = []
+  for (const schema of sorted) {
+    members.push(...docLines(schema.description, 1))
+    members.push(`${pad(1)}${renderKey(schema.name)}(args: ${jsonSchemaToTs(schema.parameters, 1)}): Promise<string>;`)
+  }
+  const declaration = members.length > 0
+    ? `declare const tools: {\n${members.join('\n')}\n}`
+    : 'declare const tools: {}'
+  return `${SDK_INSTRUCTIONS}\n\n\`\`\`ts\n${declaration}\n\`\`\``
+}

packages/core/tools/tests/code-mode.spec.ts

@@ -0,0 +1,640 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
+import type { CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
+import ToolRegistry, { CodeRunFailedError, RUN_CODE_NAME, defineTool } from '@deepseek-ai/dsh-tools'
+import type { Config, PostToolDecision, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEventMap } from '@deepseek-ai/dsh-session'
+
+/**
+ * Code Mode unit tier (per the RFC's plan): provider contribution per mode,
+ * misconfiguration rejections, the run_code dispatch bridge (serialization,
+ * abort, JSON normalization, error mapping, events, quiescence), and HMR
+ * safety — all against an in-repo fake runtime, exactly the
+ * interface/implementation/consumer shape the seam promises.
+ */
+
+/** A scriptable in-repo CodeRuntime: each test sets `behavior` to drive the bindings however it needs. */
+class FakeRuntime extends CodeRuntime {
+  readonly language: string
+  readonly isolation = 'fake'
+  behavior: (request: CodeRunRequest) => Promise<CodeRunResult> = () => Promise.resolve({ logs: [] })
+  lastRequest?: CodeRunRequest
+
+  constructor(ctx: Context, config: { language?: string } = {}) {
+    super(ctx)
+    this.language = config.language ?? 'typescript'
+  }
+
+  run(request: CodeRunRequest): Promise<CodeRunResult> {
+    this.lastRequest = request
+    return this.behavior(request)
+  }
+}
+
+interface SetupOptions {
+  mode?: Config['mode']
+  runtime?: false | { language?: string }
+  toolOrder?: string[]
+}
+
+async function setup(options: SetupOptions = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt, { ...options.toolOrder ? { toolOrder: options.toolOrder } : {} })
+  await ctx.plugin(ToolRegistry, { mode: options.mode ?? 'code' })
+  let runtime: FakeRuntime | undefined
+  if (options.runtime !== false) {
+    await ctx.plugin(FakeRuntime, options.runtime ?? {})
+    runtime = ctx.codeRuntime as FakeRuntime
+  }
+  return { ctx, tools: ctx.tools, systemPrompt: ctx.systemPrompt, runtime: runtime! }
+}
+
+/** Register a trivial echo tool; returns the calls it received. */
+function registerEcho(ctx: Context, name = 'echo'): unknown[] {
+  const calls: unknown[] = []
+  ctx.tools.register(defineTool({
+    name,
+    description: `Echo tool ${name}.`,
+    parameters: { value: { type: 'string', required: true } },
+    execute(args) {
+      calls.push(args)
+      return Promise.resolve([{ type: 'text' as const, text: `${name}:${args.value}` }])
+    },
+  }))
+  return calls
+}
+
+/** A structural fake of the owning agent: captures session appends. */
+function fakeAgent(): { agent: Agent; events: { type: string; data: unknown }[] } {
+  const events: { type: string; data: unknown }[] = []
+  const agent = {
+    session: {
+      append: (type: string, data: unknown) => { events.push({ type, data }) },
+    },
+  } as unknown as Agent
+  return { agent, events }
+}
+
+/** Dispatch run_code through the registry pipeline, as the loop would. */
+async function runCode(ctx: Context, code: string, extras: { agent?: Agent; signal?: AbortSignal } = {}): Promise<ToolExecutionResult> {
+  return ctx.tools.execute({
+    callId: CallId('call-1'),
+    name: RUN_CODE_NAME,
+    arguments: { code },
+    ...extras.agent ? { agent: extras.agent } : {},
+    ...extras.signal ? { signal: extras.signal } : {},
+  })
+}
+
+describe('mode-aware wire contribution', () => {
+  it("mode 'native' contributes every schema, no run_code, no SDK section — and needs no runtime", async () => {
+    const { ctx, systemPrompt } = await setup({ mode: 'native', runtime: false })
+    registerEcho(ctx)
+    const assembly = await systemPrompt.assemble()
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['echo'])
+    expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(false)
+  })
+
+  it("mode 'code' contributes exactly [run_code] plus the SDK section declaring the other tools", async () => {
+    const { ctx, systemPrompt } = await setup({ mode: 'code' })
+    registerEcho(ctx)
+    const assembly = await systemPrompt.assemble()
+    expect(assembly.tools.map(tool => tool.name)).toEqual([RUN_CODE_NAME])
+    const sdk = assembly.sections.find(section => section.name === 'tools:sdk')
+    expect(sdk?.text).toContain('declare const tools: {')
+    expect(sdk?.text).toContain('echo(args:')
+    expect(sdk?.text).not.toContain('run_code(args:')
+  })
+
+  it("mode 'both' contributes every native schema plus run_code, and the SDK section", async () => {
+    const { ctx, systemPrompt } = await setup({ mode: 'both' })
+    registerEcho(ctx)
+    const assembly = await systemPrompt.assemble()
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['echo', RUN_CODE_NAME])
+    expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(true)
+  })
+
+  it("never exposes run_code to programs, even under mode 'both' (no recursive dispatch path)", async () => {
+    const { ctx, runtime } = await setup({ mode: 'both' })
+    registerEcho(ctx)
+    runtime.behavior = (request) => {
+      const functions = request.bindings[0]!.functions
+      return Promise.resolve({
+        logs: [],
+        value: JSON.stringify({
+          names: Object.keys(functions).sort(),
+          // Own-property AND prototype-chain reads both come back empty —
+          // there is no handle a program could re-enter run_code through.
+          runCode: String(functions[RUN_CODE_NAME]),
+        }),
+      })
+    }
+    const result = await runCode(ctx, 'program')
+    expect(result.isError).toBe(false)
+    expect(JSON.parse((result.content[0] as { text: string }).text)).toEqual({ names: ['echo'], runCode: 'undefined' })
+  })
+
+  it('renders byte-identical SDK text across consecutive assemblies of an unchanged tool set', async () => {
+    const { ctx, systemPrompt } = await setup({ mode: 'code' })
+    registerEcho(ctx)
+    const first = await systemPrompt.assemble()
+    const second = await systemPrompt.assemble()
+    const text = (assembly: typeof first) => assembly.sections.find(section => section.name === 'tools:sdk')?.text
+    expect(text(first)).toBe(text(second))
+  })
+
+  it('rejects every assembly when a non-native mode has no code runtime', async () => {
+    const { systemPrompt } = await setup({ mode: 'code', runtime: false })
+    await expect(systemPrompt.assemble()).rejects.toThrow(/requires a code runtime/)
+  })
+
+  it("rejects every assembly when the runtime's language is not typescript", async () => {
+    const { systemPrompt } = await setup({ mode: 'code', runtime: { language: 'python' } })
+    await expect(systemPrompt.assemble()).rejects.toThrow(/language is "python"/)
+  })
+
+  it("rejects the assembly when toolOrder names a native tool that mode 'code' no longer contributes", async () => {
+    const { ctx, systemPrompt } = await setup({ mode: 'code', toolOrder: ['echo', '<unlisted-tools>'] })
+    registerEcho(ctx)
+    await expect(systemPrompt.assemble()).rejects.toThrow(/toolOrder lists unregistered tool "echo"/)
+  })
+
+  it('removes run_code and the SDK section when the registry fiber disposes (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt, {})
+    await ctx.plugin(FakeRuntime, {})
+    const fiber = await ctx.plugin(ToolRegistry, { mode: 'code' })
+    expect(ctx.tools.get(RUN_CODE_NAME)).toBeDefined()
+    await fiber.dispose()
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.tools).toEqual([])
+    expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(false)
+  })
+})
+
+describe('the run_code dispatch bridge', () => {
+  it('bridges tool calls, returns only the curated output, and logs one event per dispatch', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const calls = registerEcho(ctx)
+    const { agent, events } = fakeAgent()
+    runtime.behavior = async (request) => {
+      const tools = request.bindings[0]!.functions
+      const first = await tools.echo!({ value: 'one' })
+      const second = await tools.echo!({ value: 'two' })
+      return { logs: [{ source: 'console', level: 'log', text: `saw ${String(first)}` }], value: second }
+    }
+    const result = await runCode(ctx, 'const …: string = …', { agent })
+    expect(result.isError).toBe(false)
+    expect(result.content).toEqual([{ type: 'text', text: 'saw echo:one\necho:two' }])
+    expect(calls).toEqual([{ value: 'one' }, { value: 'two' }])
+    const dispatches = events.filter(event => event.type === 'tool/code-dispatch')
+    expect(dispatches.map(event => event.data)).toEqual([
+      { parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo', arguments: { value: 'one' }, isError: false, resultSummary: 'echo:one' },
+      { parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo', arguments: { value: 'two' }, isError: false, resultSummary: 'echo:two' },
+    ])
+    expect(result.meta).toEqual({ logs: [{ source: 'console', level: 'log', text: 'saw echo:one' }], dispatches: 2 })
+  })
+
+  it('serializes Promise.all dispatches: tool executions never overlap, in submission order', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const intervals: [string, string][] = []
+    let active = 0
+    ctx.tools.register(defineTool({
+      name: 'probe',
+      description: 'Records execution overlap.',
+      parameters: { id: { type: 'string', required: true } },
+      async execute(args) {
+        active++
+        expect(active, 'probe executions overlapped').toBe(1)
+        intervals.push(['enter', args.id])
+        await new Promise(resolve => setTimeout(resolve, 20))
+        intervals.push(['exit', args.id])
+        active--
+        return [{ type: 'text' as const, text: args.id }]
+      },
+    }))
+    runtime.behavior = async (request) => {
+      const tools = request.bindings[0]!.functions
+      const values = await Promise.all([tools.probe!({ id: 'a' }), tools.probe!({ id: 'b' }), tools.probe!({ id: 'c' })])
+      return { logs: [], value: values.join(',') }
+    }
+    const result = await runCode(ctx, 'program')
+    expect(result.isError).toBe(false)
+    expect(intervals).toEqual([
+      ['enter', 'a'], ['exit', 'a'],
+      ['enter', 'b'], ['exit', 'b'],
+      ['enter', 'c'], ['exit', 'c'],
+    ])
+    expect(result.content[0]).toEqual({ type: 'text', text: 'a,b,c' })
+  })
+
+  it('rejects the program-side call when the tool errors, with the tool error text', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    ctx.tools.register(defineTool({
+      name: 'fail',
+      description: 'Always fails.',
+      parameters: {},
+      execute(): Promise<never> { return Promise.reject(new Error('deliberate failure')) },
+    }))
+    runtime.behavior = async (request) => {
+      try {
+        await request.bindings[0]!.functions.fail!({})
+        return { logs: [], value: 'unreachable' }
+      } catch (error: unknown) {
+        return { logs: [], value: `caught: ${error instanceof Error ? error.message : String(error)}` }
+      }
+    }
+    const result = await runCode(ctx, 'program')
+    expect(result.content[0]).toEqual({ type: 'text', text: 'caught: Error: deliberate failure' })
+  })
+
+  it('a tools/pre-execute deny reaches the program as a binding rejection', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    registerEcho(ctx)
+    ctx.on('tools/pre-execute', (exec, next) => {
+      if (exec.name === 'echo') return Promise.resolve({ kind: 'deny' as const, reason: 'not on my watch' })
+      return next()
+    })
+    runtime.behavior = async (request) => {
+      try {
+        await request.bindings[0]!.functions.echo!({ value: 'x' })
+        return { logs: [], value: 'unreachable' }
+      } catch (error: unknown) {
+        return { logs: [], value: `denied: ${error instanceof Error ? error.message : String(error)}` }
+      }
+    }
+    const result = await runCode(ctx, 'program')
+    expect(result.content[0]?.type).toBe('text')
+    expect((result.content[0] as { text: string }).text).toContain('not on my watch')
+  })
+
+  it('rejects a binding argument that does not survive JSON normalization, dispatching nothing', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const calls = registerEcho(ctx)
+    const { agent, events } = fakeAgent()
+    runtime.behavior = async (request) => {
+      try {
+        await request.bindings[0]!.functions.echo!({ value: 'x', big: 1n })
+        return { logs: [], value: 'unreachable' }
+      } catch (error: unknown) {
+        return { logs: [], value: error instanceof Error ? error.message : String(error) }
+      }
+    }
+    const result = await runCode(ctx, 'program', { agent })
+    expect((result.content[0] as { text: string }).text).toContain('JSON-serializable')
+    expect(calls).toEqual([])
+    expect(events.filter(event => event.type === 'tool/code-dispatch')).toEqual([])
+  })
+
+  it('dispatches the JSON-normalized value: what the tool sees is what the event logs', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const calls = registerEcho(ctx)
+    const { agent, events } = fakeAgent()
+    runtime.behavior = async (request) => {
+      // A Date survives structured clone but is not JSON; the bridge
+      // normalizes it to its JSON form (an ISO string) BEFORE dispatch.
+      await request.bindings[0]!.functions.echo!({ value: 'x', when: new Date(0) }).catch(() => undefined)
+      return { logs: [] }
+    }
+    await runCode(ctx, 'program', { agent })
+    expect(calls).toEqual([{ value: 'x', when: '1970-01-01T00:00:00.000Z' }])
+    const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch']
+    expect(dispatch.arguments).toEqual({ value: 'x', when: '1970-01-01T00:00:00.000Z' })
+  })
+
+  it('suppresses sub-call additionalContext (deliberately; pinned)', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    registerEcho(ctx)
+    ctx.on('tools/post-execute', (exec, _result, next): Promise<PostToolDecision> => {
+      if (exec.name === 'echo') {
+        return Promise.resolve({
+          kind: 'accept' as const,
+          additionalContext: { content: [{ type: 'text' as const, text: 'context for the next request' }], source: { kind: 'plugin' as const, plugin: 'test' } },
+        })
+      }
+      return next()
+    })
+    runtime.behavior = async (request) => {
+      await request.bindings[0]!.functions.echo!({ value: 'x' })
+      return { logs: [], value: 'done' }
+    }
+    const result = await runCode(ctx, 'program')
+    expect(result.isError).toBe(false)
+    // The sub-call's context has no safe outlet mid-run; the parent result
+    // must not carry it either.
+    expect(result.additionalContext).toBeUndefined()
+  })
+
+  it('converts a failed run into a structured isError result carrying kind, message, and captured logs', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    runtime.behavior = () => Promise.resolve({
+      logs: [{ source: 'console', level: 'log', text: 'got this far' }],
+      error: { kind: 'timeout', message: 'compute budget exhausted (300ms busy)' },
+    })
+    const result = await runCode(ctx, 'program')
+    expect(result.isError).toBe(true)
+    expect(result.error).toEqual({ name: 'CodeRunFailedError', code: 'CODE_RUN_FAILED' })
+    const text = (result.content[0] as { text: string }).text
+    expect(text).toContain('code run failed (timeout)')
+    expect(text).toContain('compute budget exhausted')
+    expect(text).toContain('got this far')
+  })
+
+  it('CodeRunFailedError is a HarnessError with the CODE_RUN_FAILED code', () => {
+    const error = new CodeRunFailedError('boom')
+    expect(error.code).toBe('CODE_RUN_FAILED')
+    expect(error.name).toBe('CodeRunFailedError')
+  })
+
+  it('aborting the outer signal aborts the in-flight sub-dispatch and abandons queued ones', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const seen: string[] = []
+    let sawAbort = false
+    ctx.tools.register(defineTool({
+      name: 'slow',
+      description: 'Slow tool observing its signal.',
+      parameters: { id: { type: 'string', required: true } },
+      async execute(args, exec) {
+        seen.push(args.id)
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(resolve, 500)
+          exec.signal?.addEventListener('abort', () => { sawAbort = true; clearTimeout(timer); resolve() }, { once: true })
+        })
+        return [{ type: 'text' as const, text: args.id }]
+      },
+    }))
+    const controller = new AbortController()
+    runtime.behavior = async (request) => {
+      const tools = request.bindings[0]!.functions
+      const calls = [tools.slow!({ id: 'first' }).catch(() => 'rejected'), tools.slow!({ id: 'second' }).catch(() => 'rejected')]
+      setTimeout(() => { controller.abort('user-cancel') }, 50)
+      await Promise.all(calls)
+      // A real runtime would be terminated by the abort; the fake honors the
+      // contract by reporting the abort as the run failure.
+      return { logs: [], error: { kind: 'abort', message: 'user-cancel' } }
+    }
+    const result = await runCode(ctx, 'program', { signal: controller.signal })
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('code run failed (abort)')
+    expect(seen).toEqual(['first'])
+    expect(sawAbort).toBe(true)
+  })
+
+  it('a runtime that starts a binding call and then REJECTS still reaches quiescence before returning', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const { agent, events } = fakeAgent()
+    let sawAbort = false
+    let started!: () => void
+    const inFlight = new Promise<void>((resolve) => { started = resolve })
+    ctx.tools.register(defineTool({
+      name: 'slow',
+      description: 'Slow tool observing its signal.',
+      parameters: { id: { type: 'string', required: true } },
+      async execute(args, exec) {
+        started()
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(resolve, 500)
+          exec.signal?.addEventListener('abort', () => { sawAbort = true; clearTimeout(timer); resolve() }, { once: true })
+        })
+        return [{ type: 'text' as const, text: args.id }]
+      },
+    }))
+    runtime.behavior = async (request) => {
+      // Start a sub-dispatch, keep its rejection held, and fail the run once
+      // the tool is genuinely in flight — a seam error AFTER work has begun.
+      // The bridge's settlement still owes quiescence: without the finally,
+      // run_code would return now and the slow tool would finish (and log)
+      // afterwards.
+      request.bindings[0]!.functions.slow!({ id: 'orphan' }).catch(() => 'held')
+      await inFlight
+      throw new Error('backend exploded')
+    }
+    const result = await runCode(ctx, 'program', { agent })
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('backend exploded')
+    // Quiescence held: the in-flight sub-dispatch was aborted and its event
+    // logged INSIDE the run_code execution, not after it returned.
+    expect(sawAbort).toBe(true)
+    expect(events.filter(event => event.type === 'tool/code-dispatch').map(event => (event.data as { name: string }).name)).toEqual(['slow'])
+  })
+
+  it('runs without an owning agent: dispatches work, event logging is skipped', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const calls = registerEcho(ctx)
+    runtime.behavior = async (request) => {
+      await request.bindings[0]!.functions.echo!({ value: 'x' })
+      return { logs: [], value: 'ok' }
+    }
+    const result = await runCode(ctx, 'program')
+    expect(result.isError).toBe(false)
+    expect(calls).toEqual([{ value: 'x' }])
+  })
+
+  it('executing run_code under a missing runtime is a structured isError, not a crash', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt, {})
+    await ctx.plugin(ToolRegistry, { mode: 'code' })
+    const result = await runCode(ctx, 'program')
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('requires a code runtime')
+  })
+
+  it('presents the PROGRAM as the execute-card title on both call and result (the one slot execute cards always show)', async () => {
+    const { ctx } = await setup({ mode: 'code' })
+    const tool = ctx.tools.get(RUN_CODE_NAME)!
+    // The program IS the title, mirroring how command tools title their cards
+    // with the command: an ACP client's execute-card header is the only
+    // always-visible slot (Zed renders no body content and no raw input for
+    // execute-kind cards without a real terminal).
+    expect(tool.presentCall?.({ code: 'return 1' })).toEqual({
+      card: 'generic',
+      title: 'return 1',
+      kind: 'execute',
+      rawInput: 'return 1',
+    })
+    const view = tool.presentResult?.({ code: 'return 1' }, {
+      content: [{ type: 'text', text: 'model-facing' }],
+      isError: false,
+      meta: { logs: [{ source: 'console', level: 'log', text: 'printed' }], dispatches: 1 },
+    })
+    // The result omits the title — an update replaces only provided fields,
+    // so the pending card's program title persists through completion.
+    expect(view).toEqual({
+      card: 'generic',
+      content: [{ type: 'text', text: 'printed' }],
+    })
+    // No captured output → no content either; everything pending persists.
+    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [], dispatches: 2 } }))
+      .toEqual({ card: 'generic' })
+    // Replay with an unrecognizable meta falls back to the generic rendering.
+    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { other: true } })).toBeUndefined()
+    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false })).toBeUndefined()
+  })
+
+  it('renders non-text sub-result blocks as placeholders and truncates long event summaries', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const { agent, events } = fakeAgent()
+    const long = 'x'.repeat(300)
+    ctx.tools.register(defineTool({
+      name: 'mixed',
+      description: 'Returns mixed content.',
+      parameters: {},
+      execute() {
+        return Promise.resolve([
+          { type: 'text' as const, text: long },
+          { type: 'reasoning' as const, text: 'hidden' },
+        ])
+      },
+    }))
+    runtime.behavior = async (request) => {
+      const value = await request.bindings[0]!.functions.mixed!({})
+      return { logs: [], value }
+    }
+    const result = await runCode(ctx, 'program', { agent })
+    expect(result.isError).toBe(false)
+    expect((result.content[0] as { text: string }).text).toBe(`${long}\n[reasoning content]`)
+    const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch']
+    expect(dispatch.resultSummary.length).toBe(201)
+    expect(dispatch.resultSummary.endsWith('…')).toBe(true)
+  })
+
+  it('rejects undefined, JSON-throwing, and JSON-unrepresentable binding arguments BEFORE dispatch', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const calls = registerEcho(ctx)
+    const { agent, events } = fakeAgent()
+    runtime.behavior = async (request) => {
+      const echo = request.bindings[0]!.functions.echo!
+      const catchMessage = (promise: Promise<unknown>) => promise.then(() => 'resolved', (error: unknown) => error instanceof Error ? error.message : String(error))
+      return {
+        logs: [],
+        value: [
+          // Root undefined must reject up front: the event log rejects it as
+          // data, and nothing may execute unlogged.
+          await catchMessage(echo(undefined)),
+          // A toJSON that throws a NON-Error propagates out of JSON.stringify.
+          await catchMessage(echo({ toJSON() { throw 'raw-throw' } })),
+          // A bare function is a value JSON cannot represent at all.
+          await catchMessage(echo(() => 1)),
+        ].join(' | '),
+      }
+    }
+    const result = await runCode(ctx, 'program', { agent })
+    const text = (result.content[0] as { text: string }).text
+    expect(text).toContain('call the tool with an arguments object')
+    expect(text).toContain('JSON-serializable: raw-throw')
+    expect(text).toContain('a value JSON cannot represent')
+    // None of the three dispatched, none logged.
+    expect(calls).toEqual([])
+    expect(events.filter(event => event.type === 'tool/code-dispatch')).toEqual([])
+  })
+
+  it('logs the value the tool RECEIVED even when the tool mutates its arguments', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const { agent, events } = fakeAgent()
+    ctx.tools.register(defineTool({
+      name: 'mutator',
+      description: 'Mutates its own args object.',
+      parameters: { list: { type: 'array', required: true } },
+      execute(args) {
+        args.list.push('injected-by-tool')
+        return Promise.resolve([{ type: 'text' as const, text: 'mutated' }])
+      },
+    }))
+    runtime.behavior = async (request) => {
+      await request.bindings[0]!.functions.mutator!({ list: ['original'] })
+      return { logs: [] }
+    }
+    const result = await runCode(ctx, 'program', { agent })
+    expect(result.isError).toBe(false)
+    const dispatch = events.find(event => event.type === 'tool/code-dispatch')?.data as SessionEventMap['tool/code-dispatch']
+    expect(dispatch.arguments).toEqual({ list: ['original'] })
+  })
+
+  it('exposes a tool named __proto__ as an ordinary own binding', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    ctx.tools.register(defineTool({
+      name: '__proto__',
+      description: 'A prototype-colliding tool name.',
+      parameters: {},
+      execute() { return Promise.resolve([{ type: 'text' as const, text: 'proto-tool-ok' }]) },
+    }))
+    runtime.behavior = async (request) => {
+      const functions = request.bindings[0]!.functions
+      expect(Object.getPrototypeOf(functions)).toBeNull()
+      const value = await functions['__proto__']!({})
+      return { logs: [], value }
+    }
+    const result = await runCode(ctx, 'program')
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'proto-tool-ok' })
+  })
+
+  it('renders a non-string completion value inspect-style', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    runtime.behavior = () => Promise.resolve({ logs: [], value: { n: 42 } })
+    const result = await runCode(ctx, 'program')
+    expect((result.content[0] as { text: string }).text).toBe('{ n: 42 }')
+  })
+
+  it('reports a pre-aborted outer signal as the run failure without dispatching anything', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const calls = registerEcho(ctx)
+    runtime.behavior = (request) => {
+      // The fake honors the seam contract for an already-aborted signal.
+      if (request.signal?.aborted) return Promise.resolve({ logs: [], error: { kind: 'abort' as const, message: String(request.signal.reason) } })
+      return Promise.resolve({ logs: [], value: 'unreachable' })
+    }
+    const controller = new AbortController()
+    controller.abort('too-late')
+    const result = await runCode(ctx, 'program', { signal: controller.signal })
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('code run failed (abort)')
+    expect(calls).toEqual([])
+  })
+
+  it('rejects a binding invoked after the run is over without dispatching it', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    const calls = registerEcho(ctx)
+    const controller = new AbortController()
+    runtime.behavior = async (request) => {
+      controller.abort('cancelled-mid-run')
+      const message = await request.bindings[0]!.functions.echo!({ value: 'x' })
+        .then(() => 'resolved', (error: unknown) => error instanceof Error ? error.message : String(error))
+      return { logs: [], value: message }
+    }
+    const result = await runCode(ctx, 'program', { signal: controller.signal })
+    expect(result.isError).toBe(false)
+    expect((result.content[0] as { text: string }).text).toContain('not dispatched')
+    expect(calls).toEqual([])
+  })
+
+  it('a tool/code-dispatch event never derives a model message', () => {
+    const session = new Session(SessionId('code-mode-derive'))
+    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    session.append('tool/code-dispatch', {
+      parentCallId: CallId('p1'),
+      subCallId: CallId('p1:code:1'),
+      name: 'echo',
+      arguments: { value: 'x' },
+      isError: false,
+      resultSummary: 'echo:x',
+    })
+    const derived = session.deriveMessages()
+    expect(derived).toHaveLength(1)
+    expect(derived[0]?.role).toBe('user')
+  })
+
+  it('defaults to native mode under direct construction with no config', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt, {})
+    const registry = new ToolRegistry(ctx)
+    expect(registry.get(RUN_CODE_NAME)).toBeUndefined()
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections.some(section => section.name === 'tools:sdk')).toBe(false)
+  })
+})

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {

packages/core/tools/tests/ts-types.spec.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+import { jsonSchemaToTs, renderToolsSdk } from '@deepseek-ai/dsh-tools/src/ts-types.ts'
+import { schemaSpecToJsonSchema } from '@deepseek-ai/dsh-tools'
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+
+describe('jsonSchemaToTs', () => {
+  it('maps the defineTool DSL subset', () => {
+    const cases: [unknown, string][] = [
+      [{ type: 'string' }, 'string'],
+      [{ type: 'number' }, 'number'],
+      [{ type: 'boolean' }, 'boolean'],
+      [{ type: 'string', enum: ['a', 'b'] }, '"a" | "b"'],
+      [{ type: 'array', items: { type: 'number' } }, 'number[]'],
+      [{ type: 'array', items: { type: 'string', enum: ['x', 'y'] } }, '("x" | "y")[]'],
+      [{ type: 'array' }, 'unknown[]'],
+      [{ type: 'object' }, 'Record<string, unknown>'],
+      [{ type: 'object', properties: {} }, 'Record<string, unknown>'],
+    ]
+    for (const [schema, expected] of cases) {
+      expect(jsonSchemaToTs(schema), JSON.stringify(schema)).toBe(expected)
+    }
+  })
+
+  it('renders objects with required/optional keys, nested shapes, and per-property docs', () => {
+    const schema = schemaSpecToJsonSchema({
+      path: { type: 'string', required: true, description: 'Absolute file path' },
+      limit: { type: 'number' },
+      opts: {
+        type: 'object',
+        properties: { deep: { type: 'boolean', required: true } },
+      },
+    })
+    expect(jsonSchemaToTs(schema)).toBe([
+      '{',
+      '  /** Absolute file path */',
+      '  path: string;',
+      '  limit?: number;',
+      '  opts?: {',
+      '    deep: boolean;',
+      '  };',
+      '}',
+    ].join('\n'))
+  })
+
+  it('is total: unsupported or hostile constructs degrade to unknown, never throw', () => {
+    const cases: unknown[] = [
+      undefined,
+      null,
+      42,
+      'string-schema',
+      {},
+      { type: 'integer' },
+      { type: 'null' },
+      { oneOf: [{ type: 'string' }] },
+      { $ref: '#/defs/x' },
+      { type: 'object', properties: 7 },
+      { type: 'object', properties: { bad: { $ref: 'x' } } },
+      { type: 'string', enum: [1, 2] },
+      { type: 'string', enum: [] },
+    ]
+    for (const schema of cases) {
+      expect(() => jsonSchemaToTs(schema), JSON.stringify(schema)).not.toThrow()
+    }
+    expect(jsonSchemaToTs({ type: 'integer' })).toBe('unknown')
+    expect(jsonSchemaToTs({ oneOf: [] })).toBe('unknown')
+    expect(jsonSchemaToTs({ type: 'object', properties: 7 })).toBe('Record<string, unknown>')
+    expect(jsonSchemaToTs({ type: 'object', properties: { bad: { $ref: 'x' } }, required: ['bad'] })).toContain('bad: unknown;')
+    // A non-string-only enum degrades to plain string; an empty one too.
+    expect(jsonSchemaToTs({ type: 'string', enum: [1, 2] })).toBe('string')
+    expect(jsonSchemaToTs({ type: 'string', enum: [] })).toBe('string')
+    // A hostile required list only accepts string members.
+    expect(jsonSchemaToTs({ type: 'object', properties: { a: { type: 'string' } }, required: [7] })).toContain('a?: string;')
+    // A property VALUE that is not an object degrades to unknown (and can
+    // carry no description).
+    expect(jsonSchemaToTs({ type: 'object', properties: { weird: 42 } })).toContain('weird?: unknown;')
+  })
+
+  it('escapes a comment-closer inside a description so the generated JSDoc cannot end early', () => {
+    const rendered = jsonSchemaToTs({
+      type: 'object',
+      properties: { glob: { type: 'string', description: 'a pattern like packages/*/tool-*/ over here' } },
+    })
+    expect(rendered).not.toContain('tool-*/ over')
+    expect(rendered).toContain(String.raw`tool-*\/ over`)
+  })
+})
+
+describe('renderToolsSdk', () => {
+  const bash: ToolSchema = {
+    name: 'bash',
+    description: 'Run a shell command.',
+    parameters: schemaSpecToJsonSchema({ command: { type: 'string', required: true } }) as unknown as Record<string, unknown>,
+  }
+  const exotic: ToolSchema = {
+    name: 'my-mcp.tool',
+    description: 'Exotic name.',
+    parameters: schemaSpecToJsonSchema({}) as unknown as Record<string, unknown>,
+  }
+
+  it('declares every tool in lexicographic order with quoted keys for exotic names', () => {
+    const text = renderToolsSdk([exotic, bash])
+    expect(text).toContain('declare const tools: {')
+    expect(text.indexOf('bash(args:')).toBeGreaterThan(0)
+    expect(text).toContain('"my-mcp.tool"(args:')
+    expect(text.indexOf('bash(args:')).toBeLessThan(text.indexOf('"my-mcp.tool"(args:'))
+    expect(text).toContain('): Promise<string>;')
+    expect(text).toContain('/** Run a shell command. */')
+    // The fixed instruction lines the model relies on.
+    expect(text).toContain('erasable syntax only')
+    expect(text).toContain('rejects with an `Error`')
+    expect(text).toContain('sequentially, even under `Promise.all`')
+    expect(text).toContain('JSON-serializable')
+  })
+
+  it('is deterministic: same tool set, byte-identical text regardless of input order', () => {
+    expect(renderToolsSdk([bash, exotic])).toBe(renderToolsSdk([exotic, bash]))
+    // Equal names sort stably (the comparator's equal arm).
+    expect(renderToolsSdk([bash, bash])).toBe(renderToolsSdk([bash, bash]))
+  })
+
+  it('renders an empty declaration for an empty tool set', () => {
+    expect(renderToolsSdk([])).toContain('declare const tools: {}')
+  })
+})

packages/core/tools/tsconfig.json

@@ -8,6 +8,12 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../code-runtime/code-runtime"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },

packages/hooks/hooks-claude/README.md

@@ -37,7 +37,7 @@ The hooks **themselves** run in the agent's session workspace: for the agent-sco
 | `SessionStart` | `agent/session-start` (emit) | additionalContext → `agent.inject()` into the new session (cannot block) |
 | `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `deny` → `PromptDecision.block`; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a later listener can still block/rewrite) |
 | `PreToolUse` | `tools/pre-execute` (waterfall) | `deny` → `PreToolDecision.deny`; `ask` → `PreToolDecision.ask` |
-| `PostToolUse` | `tools/post-execute` (waterfall) | `deny` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision |
+| `PostToolUse` | `tools/post-execute` (waterfall) | `deny` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a Code Mode sub-call’s context is dropped by the run_code bridge — see [the pipeline doc](../../../docs/tool-execution-pipeline.md)) |
 | `Stop` | `agent/turn-continuation` (waterfall) | a blocking Stop hook forces `continue`, feeding its reason as next-step steering |
 | `SubagentStart` | `subagent/start` (emit) | additionalContext → `agent.inject()` into the live child |
 | `SubagentStop` | `subagent/end` (emit) | observe-only |

packages/hooks/hooks-codex/README.md

@@ -43,7 +43,7 @@ The hooks themselves run in the agent's session workspace: for the agent-scoped
 | `SessionStart` | `agent/session-start` (emit) | a plain-stdout hook's output → additionalContext → `agent.inject()` |
 | `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `block` (exit 2) → `PromptDecision.block`; additionalContext-only → delegate via `next()` then fold context onto the downstream decision |
 | `PreToolUse` | `tools/pre-execute` (waterfall) | `block` → `PreToolDecision.deny` (no `allow`/`ask`) |
-| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision |
+| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a Code Mode sub-call’s context is dropped by the run_code bridge — see [the pipeline doc](../../../docs/tool-execution-pipeline.md)) |
 | `Stop` | `agent/turn-continuation` (waterfall) | a blocking Stop hook forces `continue` with the reason as next-step steering |
 
 A tool call's payload carries the real `tool_name` (the same value the matcher tests) and Codex's `tool_input: { command }` shape (the `command` arg when present, else `''`). The matcher subject is the tool name (`PreToolUse`/`PostToolUse`) or the session source (`SessionStart`); `UserPromptSubmit`/`Stop` ignore matchers.

packages/llm/llm/src/types.ts

@@ -172,6 +172,12 @@ export interface ToolSchema {
 /** A single model request, fully assembled. */
 export interface GenerateOptions {
   model: string
+  /**
+   * Ordered conversation messages, exactly as the provider sees them (after
+   * the `system` slot). A loop-built request assembles them as
+   * `EpochHeader.messagePrefix` + the derived history (dsh-agent-loop); a
+   * hand-built one-shot passes any list.
+   */
   messages: Message[]
   /** System prompt text (adapters map to the provider's system slot). */
   system?: string

packages/support/acp-snapshot/README.md

@@ -6,7 +6,7 @@ Three layers, importable separately:
 
 - **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden + purity check, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo).
 - **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), and the composable `scrubRequestHeaders` (header bulk → `{{system}}`/`{{tools}}`, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
-- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record-mode fixture write-back, the per-suite header pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin, non-pinning fixtures header-scrubbed). Must be called at vitest collection time.
+- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record-mode fixture write-back, the per-header-class pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, pinning fixtures well-formed, non-pinning fixtures header-scrubbed). Must be called at vitest collection time.
 
 A consuming `*.snapshot.ts` is the scenario table plus one factory call:
 
@@ -26,11 +26,13 @@ defineAcpSnapshotSuite({
     tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)),
   },
   snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'),
-  scenarios: SCENARIOS, // exactly one entry sets pinsHeader
+  scenarios: SCENARIOS, // exactly one entry per header class sets pinsHeader
   mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay',
 })
 ```
 
+A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode scenarios are the template.
+
 The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config RFC](../../../docs/rfc/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. Fixture roles, record/replay semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).
 
 Constraints: `suite.ts` imports vitest, so the package is importable only inside a vitest run (the harness and normalizers have no such dependency but ship from the same entry). ACP-specific by design — the harness speaks the SDK's `ClientSideConnection`. Permission round-trips are scriptable: `InputScript.permissionAnswers` is a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) the client maps to the agent-issued `optionId` at answer time; an absent or exhausted queue answers `cancelled`, and a kind the request never offered rejects the run (the agent is answered `cancelled`, so a tolerant agent cannot absorb the scenario bug).

packages/support/acp-snapshot/src/harness.ts

@@ -166,6 +166,15 @@ export interface RunOptions {
    * start from an empty workspace.
    */
   workspaceDir?: string
+  /**
+   * Alternate LIVE config path for the boot (absolute), overriding
+   * {@link AgentUnderTest.configPath} for this run. A scenario needing a
+   * differently-composed tree (the Code Mode scenarios) ships an overlay
+   * whose basename still ends in `cordis.yml`, so the bin's replay swap
+   * resolves the sibling `*cordis.snapshot.yml` the same way it does for
+   * the default.
+   */
+  configPath?: string
 }
 
 /**
@@ -209,7 +218,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
 
     child = spawn(
       process.execPath,
-      ['--import', tsxLoader, opts.agent.binScript, opts.agent.configPath],
+      ['--import', tsxLoader, opts.agent.binScript, opts.configPath ?? opts.agent.configPath],
       { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] },
     )
 

packages/support/acp-snapshot/src/normalize.ts

@@ -13,8 +13,9 @@
  * (deterministic — `seq = log.length`, part of the event-log contract).
  *
  * A separate, composable normalizer — {@link scrubRequestHeaders} — replaces
- * the bulky request-header CONTENT (the composed system prompt and the tool
- * schema list) with `{{system}}`/`{{tools}}` tokens. It is deliberately NOT
+ * the bulky request-header CONTENT (the composed system prompt, the tool
+ * schema list, and the session prefix) with
+ * `{{system}}`/`{{tools}}`/`{{messagePrefix}}` tokens. It is deliberately NOT
  * folded into {@link normalizeSessionLog}: each suite's one header-pinning
  * scenario compares that content verbatim, every other scenario composes the
  * scrub in (the `pinsHeader` flag on the scenario table, consumed by the suite
@@ -30,6 +31,7 @@ const SESSION_ID = '{{sessionId}}'
 const CWD = '{{cwd}}'
 const SYSTEM = '{{system}}'
 const TOOLS = '{{tools}}'
+const MESSAGE_PREFIX = '{{messagePrefix}}'
 
 /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */
 const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
@@ -135,15 +137,22 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri
 /**
  * Replace request-header CONTENT in a session JSONL with stable tokens,
  * keeping its structure: a `request/header` event's `data.header.system` →
- * `{{system}}` and `data.header.tools` → `{{tools}}`; a
+ * `{{system}}`, `data.header.tools` → `{{tools}}`, and
+ * `data.header.messagePrefix` → one `{{messagePrefix}}` token per message
+ * (the session prefix is model-visible bulk — an AGENTS digest, a skills
+ * catalog — so its COUNT stays a structural fact while its text never lands
+ * in a fixture); a
  * `request/header-delta` event keeps every structural fact — the system
  * delta's `keepStart`/`keepEnd` line positions and inserted-line COUNT (one
  * `{{system}}` token per inserted line), the tools delta's
- * added/removed/changed tool NAMES — and tokenizes only the bulk (prompt
- * text; each added/changed schema's fields other than `name` → `{{tools}}`),
+ * added/removed/changed tool NAMES, the prefix replacement's message COUNT —
+ * and tokenizes only the bulk (prompt
+ * text; each added/changed schema's fields other than `name` → `{{tools}}`;
+ * each replacement prefix message → `{{messagePrefix}}`),
  * so two different deltas still compare different.
- * Absent fields stay absent — WHETHER a header carried a system prompt or
- * tools is behavior and stays visible; `config` and `reason` are small and
+ * Absent fields stay absent — WHETHER a header carried a system prompt,
+ * tools, or a prefix is behavior and stays visible; `config` and `reason`
+ * are small and
  * stable, so they stay verbatim (a model swap churns every fixture by design
  * — it invalidates the recorded responses; a prompt/schema edit churns none —
  * replay never reads this content, see dsh-llm-replay).
@@ -166,9 +175,10 @@ export function scrubRequestHeaders(rawLog: string): string {
     if (record.type === 'request/header') {
       const header = data.header as Record<string, unknown> | null | undefined
       if (header === null || typeof header !== 'object') return line
-      if (!('system' in header) && !('tools' in header)) return line
+      if (!('system' in header) && !('tools' in header) && !('messagePrefix' in header)) return line
       if ('system' in header) header.system = SYSTEM
       if ('tools' in header) header.tools = TOOLS
+      if (Array.isArray(header.messagePrefix)) header.messagePrefix = header.messagePrefix.map(() => MESSAGE_PREFIX)
       return JSON.stringify(record)
     }
     if (record.type === 'request/header-delta') {
@@ -183,6 +193,10 @@ export function scrubRequestHeaders(rawLog: string): string {
         if (Array.isArray(tools.added)) { tools.added = tools.added.map(scrubToolSchema); touched = true }
         if (Array.isArray(tools.changed)) { tools.changed = tools.changed.map(scrubToolSchema); touched = true }
       }
+      if (Array.isArray(data.messagePrefix)) {
+        data.messagePrefix = data.messagePrefix.map(() => MESSAGE_PREFIX)
+        touched = true
+      }
       return touched ? JSON.stringify(record) : line
     }
     return line

packages/support/acp-snapshot/src/suite.ts

@@ -11,13 +11,14 @@
  * before comparing).
  *
  * Request-header content (the composed system prompt + tool schemas riding on
- * `request/header` events) is pinned by exactly ONE scenario per suite — the
- * one with `pinsHeader` — and scrubbed to `{{system}}`/`{{tools}}` tokens in
- * every other fixture and compare, so a prompt or tool-schema edit churns one
- * committed line instead of every fixture. A per-run uniformity guard keeps
- * the single pin sound: every live header must equal the pinned one, and no
- * header-delta may appear outside the pinning scenario (see the
- * pinned-header RFC,
+ * `request/header` events) is pinned by exactly ONE scenario per HEADER CLASS
+ * — scenarios that boot the same config compose the same header; each class's
+ * `pinsHeader` scenario commits it verbatim — and scrubbed to
+ * `{{system}}`/`{{tools}}` tokens in every other fixture and compare, so a
+ * prompt or tool-schema edit churns one committed line per class instead of
+ * every fixture. A per-run uniformity guard keeps each pin sound: every live
+ * header must equal its class's pinned one, and no header-delta may appear
+ * outside a pinning scenario (see the pinned-header RFC,
  * docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md).
  *
  * `pnpm run test:snapshot:record` (DSH_SNAPSHOT=record + -u) re-records the
@@ -80,18 +81,38 @@ export interface Scenario {
    * Whether THIS scenario's fixtures keep the full request-header content (the
    * composed system prompt and tool schema list on `request/header` /
    * `request/header-delta` events) and compare it verbatim. Exactly one
-   * scenario per suite pins it; every other scenario stores and compares that
-   * content as `{{system}}`/`{{tools}}` tokens ({@link scrubRequestHeaders}),
+   * scenario per HEADER CLASS ({@link headerClass}) pins it; every other
+   * scenario of that class stores and compares that content as
+   * `{{system}}`/`{{tools}}` tokens ({@link scrubRequestHeaders}),
    * so a system prompt or tool-schema change shows up as ONE committed-fixture
-   * diff, not one per scenario. One pin suffices because header composition is
-   * suite-uniform (parent, spawn child, and fork child all compose the same
-   * prompt-modulo-cwd and the same tools) — and that premise is ASSERTED, not
-   * assumed: every non-pinning run's live headers must equal the pinned
-   * fixture's (normalized), so a session-dependent header (say, a restricted
-   * subagent toolset) fails loud until it gets its own pinning scenario.
+   * diff per class, not one per scenario. One pin per class suffices because
+   * header composition is class-uniform (parent, spawn child, and fork child
+   * all compose the same prompt-modulo-cwd and the same tools) — and that
+   * premise is ASSERTED, not assumed: every non-pinning run's live headers
+   * must equal its class's pinned fixture's (normalized), so a
+   * session-dependent header (say, a restricted subagent toolset) fails loud
+   * until it gets its own pinning scenario.
    * Defaults to false.
    */
   pinsHeader?: boolean
+  /**
+   * Which header-composition class this scenario belongs to. Scenarios that
+   * boot the same config compose the same header; each class has exactly one
+   * {@link pinsHeader} scenario, and the uniformity guard compares every
+   * other member against ITS class's pin. Defaults to `'default'`; a
+   * scenario booting an alternate config ({@link configPath}) whose tool
+   * list or prompt sections differ by construction carries its own class.
+   */
+  headerClass?: string
+  /**
+   * Alternate LIVE config path (absolute) this scenario boots instead of
+   * {@link AgentUnderTest.configPath} — an overlay composing a different
+   * tree (its basename must still end in `cordis.yml` so the bin's replay
+   * swap finds the sibling `*cordis.snapshot.yml`). A scenario whose
+   * overlay changes the composed header also needs its own
+   * {@link headerClass}.
+   */
+  configPath?: string
 }
 
 /** One suite's inputs: the agent to boot, where its fixtures live, and its scenario table. */
@@ -183,10 +204,11 @@ export function headerDeltaCount(rawLog: string): number {
 /**
  * Register the suite: one `describe` per scenario (the golden/log compares and
  * the header-uniformity guard) plus the fixture guard block (no orphan
- * scenario dirs, required files present, exactly one pin, non-pinning fixtures
- * header-scrubbed). Must run at vitest collection time — it calls
- * `describe`/`it`. Throws immediately if no scenario pins the header (the
- * uniformity guard would have nothing to compare against).
+ * scenario dirs, required files present, exactly one pin per header class,
+ * pinning fixtures well-formed, non-pinning fixtures header-scrubbed). Must
+ * run at vitest collection time — it calls `describe`/`it`. Throws
+ * immediately if any header class lacks a pinning scenario or carries two
+ * (the uniformity guard needs exactly one comparison anchor per class).
  *
  * @param options The agent, snapshots directory, scenario table, and mode.
  */
@@ -194,9 +216,23 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
   const { agent, snapshotsDir, scenarios, mode } = options
   const RECORDING = mode === 'record'
 
-  /** The suite's single header-pinning scenario. Guarded here (and by a meta-test) so the pin cannot silently vanish. */
-  const pinningScenario = scenarios.find(s => s.pinsHeader === true)
-  if (pinningScenario === undefined) throw new Error('acp-snapshot: no scenario pins the request-header content')
+  /** The class a scenario's header composition belongs to (see {@link Scenario.headerClass}). */
+  const classOf = (scenario: Scenario): string => scenario.headerClass ?? 'default'
+
+  /** Each header class's single pinning scenario. Guarded here (and by meta-tests) so a pin cannot silently vanish or split. */
+  const pinningByClass = new Map<string, Scenario>()
+  for (const scenario of scenarios) {
+    if (scenario.pinsHeader !== true) continue
+    const cls = classOf(scenario)
+    const existing = pinningByClass.get(cls)
+    if (existing) throw new Error(`acp-snapshot: header class "${cls}" pinned by both ${existing.name} and ${scenario.name}`)
+    pinningByClass.set(cls, scenario)
+  }
+  for (const scenario of scenarios) {
+    if (!pinningByClass.has(classOf(scenario))) {
+      throw new Error(`acp-snapshot: no scenario pins the request-header content of class "${classOf(scenario)}" (needed by ${scenario.name})`)
+    }
+  }
 
   for (const scenario of scenarios) {
     describe(`snapshot: ${scenario.name}`, () => {
@@ -217,6 +253,9 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
           // replays from its own script. In RECORD they are harvested, not read.
           ...!RECORDING && childSessions > 0 ? { childFiles: childFixturePaths(dir, childSessions) } : {},
           ...existsSync(workspaceDir) ? { workspaceDir } : {},
+          // A scenario booting an overlay tree passes its own live config; the
+          // bin's replay swap derives the sibling `*cordis.snapshot.yml` from it.
+          ...scenario.configPath !== undefined ? { configPath: scenario.configPath } : {},
         })
 
         // Scrub every volatile id the run produced: the ACP server-issued session
@@ -277,19 +316,22 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
           }
         }
 
-        // Header-uniformity guard: the single pin is sound only while every
-        // session in the suite composes the SAME header and keeps it for the
-        // whole run. Assert both halves live. (1) Every request/header the run
-        // produced (parent, spawn child, fork child, initial or resume) must
-        // equal the pinned fixture's header after each side is normalized
-        // against its own volatile values. (2) No request/header-delta may
-        // appear at all — a mid-run header change diverges from the pin by
-        // construction, and its content would be invisible under the scrub. If
-        // either fails, either the header changed (update the pin: re-record or
-        // hand-edit the pinning scenario's fixture) or composition became
-        // session-dependent by design (give the divergent shape its own
-        // pinning scenario).
+        // Header-uniformity guard: a class's single pin is sound only while
+        // every session in that class composes the SAME header and keeps it
+        // for the whole run. Assert both halves live. (1) Every
+        // request/header the run produced (parent, spawn child, fork child,
+        // initial or resume) must equal the CLASS's pinned fixture's header
+        // after each side is normalized against its own volatile values.
+        // (2) No request/header-delta may appear at all — a mid-run header
+        // change diverges from the pin by construction, and its content
+        // would be invisible under the scrub. If either fails, either the
+        // header changed (update the pin: re-record or hand-edit the pinning
+        // scenario's fixture) or composition became session-dependent by
+        // design (give the divergent shape its own pinning scenario and
+        // class).
         if (scenario.pinsHeader !== true) {
+          /* v8 ignore next -- construction guarantees the pin exists; a miss would fail the one-header assertion loudly. */
+          const pinningScenario = pinningByClass.get(classOf(scenario)) ?? scenario
           const pinnedFixture = await readFile(join(snapshotsDir, pinningScenario.name, 'session.jsonl'), 'utf8')
           const pinned = normalizedHeaders(pinnedFixture, fixtureContext(pinnedFixture))
           expect(pinned.length, `the pinning fixture (${pinningScenario.name}) must carry exactly one request/header`)
@@ -347,11 +389,35 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
       }
     })
 
-    it('exactly one scenario pins the request-header content', () => {
-      // Zero pins would drop the prompt/schema surface from the suite entirely;
-      // two would split it. One pin per suite is the design (pinned-header RFC);
-      // WHICH scenario pins is the scenario table's reviewable choice.
-      expect(scenarios.filter(s => s.pinsHeader === true).map(s => s.name)).toEqual([pinningScenario.name])
+    it('exactly one scenario pins the request-header content of each header class', () => {
+      // Zero pins would drop a class's prompt/schema surface from the suite
+      // entirely; two would split it. One pin per class is the design
+      // (pinned-header RFC); WHICH scenario pins is the scenario table's
+      // reviewable choice.
+      const pins = new Map<string, string[]>()
+      for (const scenario of scenarios.filter(s => s.pinsHeader === true)) {
+        const cls = classOf(scenario)
+        pins.set(cls, [...pins.get(cls) ?? [], scenario.name])
+      }
+      expect(Object.fromEntries([...pins].map(([cls, names]) => [cls, names.length]))).toEqual(
+        Object.fromEntries([...pinningByClass.keys()].map(cls => [cls, 1])))
+      for (const scenario of scenarios) {
+        expect(pinningByClass.has(classOf(scenario)), `class "${classOf(scenario)}" (scenario ${scenario.name}) has a pin`).toBe(true)
+      }
+    })
+
+    it('every pinning fixture carries exactly one request/header and no deltas', async () => {
+      // The live uniformity guard runs only in NON-pinning scenarios, so a
+      // class made of just its pinning scenario would otherwise accept a
+      // re-recorded pin with several headers or a mid-run header-delta —
+      // shapes the pin design cannot represent. Assert the committed pins
+      // directly.
+      for (const scenario of pinningByClass.values()) {
+        const fixture = await readFile(join(snapshotsDir, scenario.name, 'session.jsonl'), 'utf8')
+        const headers = normalizedHeaders(fixture, fixtureContext(fixture))
+        expect(headers.length, `${scenario.name}: a pinning fixture must carry exactly one request/header`).toBe(1)
+        expect(headerDeltaCount(fixture), `${scenario.name}: a pinning fixture must carry no request/header-delta`).toBe(0)
+      }
     })
 
     it('committed fixtures carry request-header content ONLY in the pinning scenario', async () => {

packages/support/acp-snapshot/tests/normalize.spec.ts

@@ -155,6 +155,38 @@ describe('scrubRequestHeaders', () => {
     expect(toolsOnly).not.toContain('{{system}}')
   })
 
+  it('scrubs the header session prefix to one token per message, keeping the count', () => {
+    const ev = headerEvent({
+      config: { model: 'm' },
+      messagePrefix: [
+        { role: 'user', content: [{ type: 'text', text: 'workspace AGENTS digest' }] },
+        { role: 'user', content: [{ type: 'text', text: 'skills catalog' }] },
+      ],
+    })
+    const out = scrubRequestHeaders(`${headerLine}\n${ev}\n`)
+    expect(out).toContain('"messagePrefix":["{{messagePrefix}}","{{messagePrefix}}"]')
+    expect(out).not.toContain('AGENTS digest')
+    expect(out).not.toContain('skills catalog')
+    // Absence stays absent — a prefix-less header gains no token…
+    expect(scrubRequestHeaders(`${headerLine}\n${headerEvent({ system: 's' })}\n`)).not.toContain('{{messagePrefix}}')
+    // …and a non-array shape passes through untouched.
+    const odd = JSON.stringify({ type: 'request/header', seq: 4, time: 9, data: { header: { config: { model: 'm' }, messagePrefix: 'weird' }, reason: 'initial' } })
+    expect(scrubRequestHeaders(`${headerLine}\n${odd}\n`)).toContain('"messagePrefix":"weird"')
+  })
+
+  it('scrubs a header-delta prefix replacement to one token per message', () => {
+    const delta = JSON.stringify({
+      type: 'request/header-delta', seq: 8, time: 9,
+      data: { messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'leaked opener' }] }] },
+    })
+    const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`)
+    expect(out).toContain('"messagePrefix":["{{messagePrefix}}"]')
+    expect(out).not.toContain('leaked opener')
+    // The empty-array transition-to-absence stays a structural fact.
+    const toNone = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { messagePrefix: [] } })
+    expect(scrubRequestHeaders(`${headerLine}\n${toNone}\n`)).toContain('"messagePrefix":[]')
+  })
+
   it('leaves a delta with no scrubbable payload byte-identical (config-only, or non-array shapes)', () => {
     const configOnly = JSON.stringify({ type: 'request/header-delta', seq: 8, time: 9, data: { config: { model: 'm2' } } })
     const oddShapes = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { system: { insert: 'not-an-array' }, tools: null } })

packages/support/acp-snapshot/tests/suite.spec.ts

@@ -34,12 +34,18 @@ const AGENT = {
 const REPLAY_DIR = fileURLToPath(new URL('./fixtures/suite', import.meta.url))
 const RECORD_SRC = fileURLToPath(new URL('./fixtures/record-suite', import.meta.url))
 
+// The replay suite doubles as the header-CLASS coverage: every scenario names
+// the same explicit class (the record suite exercises the 'default' fallback),
+// and plain-turn boots through a per-scenario configPath override (the same
+// dummy path the agent default carries — the plumbing, not the composition,
+// is what this suite can exercise; the real overlay boot is the acp-agent
+// example's code-mode scenarios).
 const REPLAY_SCENARIOS: Scenario[] = [
-  { name: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true },
-  { name: 'plain-turn', hasModelTurn: true, recorded: true, childSessions: 1 },
-  { name: 'no-model', hasModelTurn: false, recorded: false },
-  { name: 'blocked-log', hasModelTurn: false, comparesLog: true, recorded: false },
-  { name: 'authored-error', hasModelTurn: true, recorded: false, overridden: true },
+  { name: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'main' },
+  { name: 'plain-turn', hasModelTurn: true, recorded: true, childSessions: 1, headerClass: 'main', configPath: AGENT.configPath },
+  { name: 'no-model', hasModelTurn: false, recorded: false, headerClass: 'main' },
+  { name: 'blocked-log', hasModelTurn: false, comparesLog: true, recorded: false, headerClass: 'main' },
+  { name: 'authored-error', hasModelTurn: true, recorded: false, overridden: true, headerClass: 'main' },
 ]
 
 const RECORD_SCENARIOS: Scenario[] = [
@@ -70,7 +76,7 @@ describe('defineAcpSnapshotSuite: record mode', () => {
 })
 
 describe('defineAcpSnapshotSuite: registration contract', () => {
-  it('throws when no scenario pins the request-header content', () => {
+  it("throws when a scenario's header class has no pinning scenario", () => {
     expect(() => {
       defineAcpSnapshotSuite({
         agent: AGENT,
@@ -78,7 +84,33 @@ describe('defineAcpSnapshotSuite: registration contract', () => {
         scenarios: [{ name: 'pinless', hasModelTurn: true, recorded: true }],
         mode: 'replay',
       })
-    }).toThrow(/no scenario pins/)
+    }).toThrow(/no scenario pins the request-header content of class "default"/)
+    // A pinned class does not cover a DIFFERENT class's members.
+    expect(() => {
+      defineAcpSnapshotSuite({
+        agent: AGENT,
+        snapshotsDir: REPLAY_DIR,
+        scenarios: [
+          { name: 'pinned', hasModelTurn: true, recorded: true, pinsHeader: true },
+          { name: 'classless-orphan', hasModelTurn: true, recorded: true, headerClass: 'other' },
+        ],
+        mode: 'replay',
+      })
+    }).toThrow(/class "other" \(needed by classless-orphan\)/)
+  })
+
+  it('throws when two scenarios pin the same header class', () => {
+    expect(() => {
+      defineAcpSnapshotSuite({
+        agent: AGENT,
+        snapshotsDir: REPLAY_DIR,
+        scenarios: [
+          { name: 'first-pin', hasModelTurn: true, recorded: true, pinsHeader: true },
+          { name: 'second-pin', hasModelTurn: true, recorded: true, pinsHeader: true },
+        ],
+        mode: 'replay',
+      })
+    }).toThrow(/header class "default" pinned by both first-pin and second-pin/)
   })
 })
 

packages/support/invariants/src/index.ts

@@ -367,8 +367,11 @@ export function apply(ctx: Context, config: Config = {}): void {
   // hand-built one-shot (compaction summarize) is unfrozen and skipped — must
   // be EXACTLY what the session log reconstructs:
   //
-  // - messages: the derivation over the log prefix strictly before the
-  //   in-flight step's `step/start` (the reconstruction boundary). Compared
+  // - messages: the folded header's session prefix (messagePrefix — the
+  //   `agent/session-prefix` product, logged on the header because no
+  //   session event carries it) followed by the
+  //   derivation over the log prefix strictly before the in-flight step's
+  //   `step/start` (the reconstruction boundary). The derivation is compared
   //   against a FRESH Session built over that prefix — the same projection
   //   code with zero shared state, so the live cache under test cannot vouch
   //   for itself. Boundary-correct by construction: content appended after
@@ -408,18 +411,22 @@ export function apply(ctx: Context, config: Config = {}): void {
     if (boundary === -1) {
       throw new InvariantError('a loop-built request with no step/start in its session log')
     }
-    const rebuilt = new Session(SessionId(`${String(session.id)}-invariant-rebuild`), structuredClone(events.slice(0, boundary)))
-    // JSON equality is sound here: both sides are structuredClones produced by
-    // the same projection code path, so key insertion order matches when the
-    // values do.
-    if (JSON.stringify(options.messages) !== JSON.stringify(rebuilt.deriveMessages())) {
-      throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`)
-    }
-
     const header = foldRequestHeader(events)
     if (header === undefined) {
       throw new InvariantError('a loop-built request with no request/header event in its session log')
     }
+    const rebuilt = new Session(SessionId(`${String(session.id)}-invariant-rebuild`), structuredClone(events.slice(0, boundary)))
+    // The reconstruction equation: the folded header's session prefix, then
+    // the boundary derivation — the loop
+    // logs the header event BEFORE dispatch, so the fold already covers this
+    // request's prefix. JSON equality is sound here: both sides are
+    // structuredClones produced by the same projection/build code path, so key
+    // insertion order matches when the values do.
+    const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages()]
+    if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
+      throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`)
+    }
+
     const headerMatches = options.model === header.config.model
       && options.system === header.system
       && options.temperature === header.config.temperature

packages/support/invariants/tests/invariants.spec.ts

@@ -707,6 +707,21 @@ describe('request-reconstruction cross-check (llm/stream)', () => {
     expect(() => { dispatch(ctx, options) }).not.toThrow()
   })
 
+  it('expects the folded header\'s session prefix ahead of the derivation (prefix + derived)', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: '<system-reminder>catalog</system-reminder>' }] }
+    session.append('request/header-delta', { messagePrefix: [prefix] })
+    // The prefixed request matches the fold…
+    const prefixed = Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id })
+    expect(() => { dispatch(ctx, prefixed) }).not.toThrow()
+    // …a request that DROPPED the logged prefix diverges…
+    const bare = Object.freeze({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id })
+    expect(() => { dispatch(ctx, bare) }).toThrow(/diverges from the boundary derivation/)
+    // …and so does one that misplaced it (prefix sent after the history).
+    const misplaced = Object.freeze({ model: 'm', messages: Object.freeze([...boundary, prefix]), sessionId: session.id })
+    expect(() => { dispatch(ctx, misplaced) }).toThrow(/diverges from the boundary derivation/)
+  })
+
   it('rejects a frozen request whose messages diverge from the boundary derivation', async () => {
     const { ctx, session, boundary } = await requestSetup()
     const messages = [...boundary, { role: 'user', content: [{ type: 'text', text: 'phantom' }] }]

packages/ui/acp-agent/package.json

@@ -36,6 +36,7 @@
     "@deepseek-ai/dsh-acp": "^0.0.1",
     "@deepseek-ai/dsh-agent-core": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-user-interaction": "^0.0.1",
     "cordis": "^4.0.0-rc.6",
     "schemastery": "^3.17.0"
@@ -46,6 +47,7 @@
     "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/dsh-acp": "workspace:^",
     "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",

packages/ui/acp-agent/src/index.ts

@@ -34,6 +34,7 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
 import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 
@@ -45,7 +46,8 @@ export const name = 'acp-agent'
  * pre-created agent — ACP creates agents at `session/new`); `persona` is the
  * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
  * the explicit model-facing tool order (forwarded to the system-prompt plugin);
- * `persistenceRoot` is the JSONL backend's directory.
+ * `tools` is the tool registry's config (its presentation `mode`, forwarded
+ * through agent-core); `persistenceRoot` is the JSONL backend's directory.
  */
 export interface Config {
   /** Model name for ACP-created agents (must have a registered adapter). */
@@ -54,6 +56,8 @@ export interface Config {
   persona?: string
   /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
   toolOrder?: string[]
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  tools?: ToolsConfig
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
 }
@@ -65,6 +69,7 @@ export const Config: z<Config> = z.object({
   // order" (the owning dsh-system-prompt schema does the same), while
   // schemastery's native [] default would read as an invalid configured list.
   toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
+  tools: ToolRegistry.Config,
   persistenceRoot: z.string().default('./.sessions'),
 })
 
@@ -79,6 +84,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.plugin(agentCore, {
     ...config.persona !== undefined ? { persona: config.persona } : {},
     ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
+    ...config.tools !== undefined ? { tools: config.tools } : {},
   })
   ctx.plugin(UserInteractionService)
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })

packages/ui/stdio-agent/package.json

@@ -38,6 +38,7 @@
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-agent-core": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-tool-ask-user": "^0.0.1",
     "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -54,6 +55,7 @@
     "@deepseek-ai/dsh-agent-core": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",

packages/ui/stdio-agent/src/index.ts

@@ -43,6 +43,7 @@ import ConsoleExporter from '@cordisjs/plugin-logger-console'
 import z from 'schemastery'
 import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import * as agentCore from '@deepseek-ai/dsh-agent-core'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -66,6 +67,8 @@ export interface Config {
   persona?: string
   /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
   toolOrder?: string[]
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  tools?: ToolsConfig
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
   /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
@@ -85,6 +88,7 @@ export const Config: z<Config> = z.object({
   // order" (the owning dsh-system-prompt schema does the same), while
   // schemastery's native [] default would read as an invalid configured list.
   toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
+  tools: ToolRegistry.Config,
   persistenceRoot: z.string().default('./.sessions'),
   welcome: z.string().default('ready.'),
   resumeSessionId: z.string(),
@@ -102,6 +106,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.plugin(agentCore, {
     ...config.persona !== undefined ? { persona: config.persona } : {},
     ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
+    ...config.tools !== undefined ? { tools: config.tools } : {},
     agents: [{
       id: AgentId('main'),
       model: config.model,

packages/workflow/README.md

@@ -0,0 +1,13 @@
+# workflow/ — dynamic-workflow capability family
+
+The workflow seam: a model-written JavaScript orchestration script that fans out subagents at scale (phases, structured per-agent results, concurrency caps), modeled on Claude Code's dynamic workflows. A capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)) in the bash shape: ONE engine implementation per context registers as `ctx.workflows`; the model-facing tool consumes it.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `workflow/` | Abstract workflow seam: service base class + run vocabulary + `workflow/*` events | `ctx.workflows` |
+| `workflow-workerthread/` | `node:worker_threads` engine: one worker per run; the script's vm context lives inside the worker, `agent()` bridges to `ctx.subagents` over the message port | (provides `ctx.workflows`) |
+| `tool-workflow/` | Model-facing `workflow` tool over `ctx.workflows` | (registers on `ctx.tools`) |
+
+The interface lives at `workflow/workflow/`. The engine's `agent()` hook rides the [subagent seam](../subagent/README.md) (any registered provider; the shipped examples use `spawn`), and `agent({ schema })` rides the structured-output support the in-process backends implement. The worker thread isolates the SCRIPT — the host never blocks on it, and a cancelled run's post-grace termination is real — but it is NOT a security boundary; an isolated-vm/separate-process engine (actual sandboxing) swaps in behind the same interface if that ever matters.
+
+The proposal, decisions, and deferred work: [docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md](../../docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md).

packages/workflow/tool-workflow/README.md

@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-tool-workflow
+
+The model-facing **`workflow` tool**: run a JavaScript orchestration script that fans out subagents, and return the script's final value. Pure schema + lifecycle shaping over [`ctx.workflows`](../workflow/README.md) — script parsing, execution, caps, and cancellation live behind the seam, so a hardened engine swaps in without touching what the model sees.
+
+## What the model sees
+
+Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest). The plugin also contributes a `tool:<toolName>` system-prompt section carrying the usage policy — use the tool only on an explicit user ask for a workflow / large orchestration; prefer plain subagent calls for one or two delegations — per the convention that tool guidance ships with the tool plugin, never in the deployment persona.
+
+## Lifecycle
+
+Collection is SYNCHRONOUS this cut (like [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)): `execute` starts a run and awaits `run.result` inside a `try/finally` that always disposes the run, so the script and its children reach quiescence on every path. `exec.signal` is bridged to `run.cancel()` (including the already-aborted-before-start case). A non-`completed` stop reason maps to an `isError` result reporting the reason — never partial output as success; a parse/meta failure thrown synchronously by `start()` becomes an `isError` the model can correct from. The completed result renders the meta name, the agent count, and the return value as JSON, truncated at `maxResultChars` with an explicit notice.
+
+## Render intent
+
+Decided up front (per the [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md)): a `generic` card titled `workflow: <meta.name>`, the name sniffed TEXTUALLY from `args.script` (presentation must be a pure function of args, so it cannot ask the engine to parse); the script text rides as `rawInput`. The result keeps the generic card.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `toolName` | `workflow` | The model-facing tool name to register. |
+| `maxResultChars` | `50000` | Rendered-result ceiling; longer JSON is truncated with a notice. |

packages/workflow/tool-workflow/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-tool-workflow",
+  "description": "Model-facing workflow tool: run a JavaScript orchestration script over ctx.workflows",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-workflow": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-workflow": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/workflow/tool-workflow/src/index.ts

@@ -0,0 +1,215 @@
+/**
+ * The model-facing `workflow` tool: run a JavaScript orchestration script that
+ * fans out subagents, and return the script's final value. Pure schema +
+ * lifecycle shaping — script parsing, execution, caps, and cancellation live
+ * behind `ctx.workflows` (`@deepseek-ai/dsh-workflow`), so a hardened engine
+ * swaps in without touching what the model sees.
+ *
+ * Collection is SYNCHRONOUS this cut (like `dsh-tool-subagent`): `execute`
+ * starts a run and awaits `run.result` inside a `try/finally` that always
+ * disposes the run, so the script and its children are torn down on every
+ * path. A non-`completed` stop reason maps to an `isError` tool result (by
+ * throwing) rather than returning partial output as success. Background
+ * collection is deferred to the cross-tool background redesign.
+ *
+ * Render intent (decided up front, per the render-intent RFC): a `generic`
+ * card whose title carries the workflow's `meta.name`, read directly from the
+ * call's `meta` parameter — presentation is a pure function of `args`.
+ *
+ * Usage policy ships with the tool as a `tool:<toolName>` system-prompt
+ * section (explicit-ask-only guidance) — tool guidance lives in tool plugins,
+ * never in the deployment persona.
+ *
+ * @module @deepseek-ai/dsh-tool-workflow
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { WorkflowResult, WorkflowRun } from '@deepseek-ai/dsh-workflow'
+// Declaration merge only: makes ctx.systemPrompt visible for the section registration.
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+export const name = 'tool-workflow'
+export const inject = ['tools', 'workflows', 'systemPrompt']
+
+/** Config: the model-facing tool name plus result rendering caps. */
+export interface Config {
+  /** The model-facing tool name to register (default `workflow`). */
+  toolName?: string
+  /** Rendered-result ceiling, in characters: a longer JSON value is truncated with a notice (default 50000). */
+  maxResultChars?: number
+}
+
+export const Config: z<Config> = z.object({
+  toolName: z.string().default('workflow'),
+  maxResultChars: z.natural().min(1).default(50_000),
+})
+
+type ResolvedConfig = Required<Config>
+
+/**
+ * The script-authoring contract, embedded in the tool description. This IS the
+ * model-facing spec: the meta block, the hooks and their exact semantics, and
+ * the supported schema subset.
+ */
+const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.
+
+The workflow's identity rides the \`meta\` parameter as JSON: required \`name\` (short kebab-case) and \`description\` strings, optional \`whenToUse\` string and \`phases\` array (\`{title, detail?, model?}\`). The \`script\` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO \`export const meta\` statement — meta is a parameter, not code), running with top-level await; end with \`return <value>\` — the value must be JSON-serializable and is this tool's result.
+
+Script-body hooks:
+- \`agent(prompt, opts?): Promise<any>\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), \`model\` (override). Anything else (\`effort\`/\`isolation\`/\`agentType\`) is rejected loudly.
+- \`pipeline(items, ...stages): Promise<any[]>\` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives \`(prev, item, index)\`. An ordinary stage throw drops that ITEM to \`null\` and skips its remaining stages.
+- \`parallel(thunks): Promise<any[]>\` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to \`null\`.
+- \`phase(title)\` — start a progress phase; \`log(message)\` — narrate progress; \`args\` — the tool call's \`args\` input, verbatim.
+
+Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`.
+
+Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.`
+
+type WorkflowCallArgs = {
+  script: string
+  meta: { name: string; description: string; whenToUse?: string; phases?: { title: string; detail?: string; model?: string }[] }
+  args?: Record<string, unknown>
+}
+
+/** The pending-state card: a generic card titled by the workflow's meta name. */
+function presentWorkflowCall(args: WorkflowCallArgs): ToolCallView {
+  return {
+    card: 'generic',
+    title: `workflow: ${args.meta.name}`,
+    rawInput: args.script,
+  }
+}
+
+/** The completed-state card: keep the pending title; render the result content as-is. */
+function presentWorkflowResult(args: WorkflowCallArgs, result: { content: ContentBlock[]; isError: boolean }): ToolResultView {
+  void args
+  void result
+  return { card: 'generic' }
+}
+
+/** A non-`completed` stop reason means the script did not finish cleanly. */
+function stopReasonError(result: WorkflowResult): string | undefined {
+  switch (result.stopReason) {
+    case 'completed':
+      return undefined
+    case 'cancelled':
+      return `workflow run was cancelled${result.error !== undefined ? ` (${result.error})` : ''}`
+    case 'error':
+      return `workflow run failed: ${result.error ?? 'unknown error'}`
+    /* v8 ignore start -- defensive: WorkflowStopReason is a closed union, exhaustive by construction; a future variant fails here loudly */
+    default:
+      return `workflow run ended abnormally (${String(result.stopReason satisfies never)})`
+    /* v8 ignore stop */
+  }
+}
+
+/** Render the run's outcome text: the meta name, agent count, and the JSON value (capped). */
+function renderResult(run: WorkflowRun, result: WorkflowResult, maxChars: number): string {
+  // The engine returns JSON data (null for a valueless script), so stringify never yields undefined.
+  const rendered = JSON.stringify(result.value, null, 2)
+  const clipped = rendered.length > maxChars
+    ? `${rendered.slice(0, maxChars)}\n… [truncated: ${rendered.length - maxChars} more characters]`
+    : rendered
+  return `workflow "${run.meta.name}" completed (${result.agentsStarted} agent${result.agentsStarted === 1 ? '' : 's'}).\nReturn value:\n${clipped}`
+}
+
+export function apply(ctx: Context, config: Config): void {
+  // schemastery (the exported Config schema) has already filled the defaulted
+  // fields; the assertion records that resolution, not a hidden fallback.
+  const { toolName, maxResultChars } = config as ResolvedConfig
+  // Usage policy ships with the tool (the master convention: tool guidance
+  // lives in tool plugins as prompt sections, not in the deployment persona).
+  ctx.systemPrompt.section({
+    name: `tool:${toolName}`,
+    order: 115,
+    text: `Use the ${toolName} tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.`,
+  })
+  ctx.tools.register(defineTool({
+    name: toolName,
+    description: DESCRIPTION,
+    parameters: {
+      script: {
+        type: 'string',
+        required: true,
+        description: 'The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`).',
+      },
+      meta: {
+        type: 'object',
+        required: true,
+        description: 'The workflow identity block (plain JSON — never code).',
+        properties: {
+          name: { type: 'string', required: true, description: 'Short kebab-case workflow name.' },
+          description: { type: 'string', required: true, description: 'One-line description of what the workflow does.' },
+          whenToUse: { type: 'string', description: 'Optional guidance on when this workflow applies.' },
+          phases: {
+            type: 'array',
+            description: 'Optional phase declarations matched by phase() calls.',
+            items: {
+              type: 'object',
+              properties: {
+                title: { type: 'string', required: true, description: 'The phase title phase() calls match by exact string.' },
+                detail: { type: 'string', description: 'Optional one-line description of the phase.' },
+                model: { type: 'string', description: 'Optional model override this phase is expected to use.' },
+              },
+            },
+          },
+        },
+      },
+      args: {
+        type: 'object',
+        description: 'Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}).',
+      },
+    },
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const parent = exec.agent
+      if (!parent) {
+        // The loop sets `exec.agent` for every model-driven call; its absence
+        // means a non-agent caller invoked the tool directly, which has no
+        // parent to attribute the children to. Fail loud rather than guess.
+        throw new Error('workflow tool requires a calling agent (exec.agent was undefined)')
+      }
+
+      // Meta/body validation failures (META_INVALID/SCRIPT_PARSE) throw
+      // synchronously here and become isError results via the registry — the
+      // model sees the violation list and can correct the call.
+      const run: WorkflowRun = ctx.workflows.start({
+        script: args.script,
+        meta: args.meta,
+        ...args.args !== undefined ? { args: args.args } : {},
+        parent,
+        ...exec.signal ? { signal: exec.signal } : {},
+      })
+
+      // Bridge the tool's abort signal to the run: if the parent step is
+      // aborted while the script is in flight, cancel the whole run. The
+      // engine also receives `signal` directly, but an explicit bridge keeps
+      // the tool's contract local (and covers an engine that ignores it).
+      const onAbort = (): void => { run.cancel('parent step aborted') }
+      exec.signal?.addEventListener('abort', onAbort, { once: true })
+      // `addEventListener` does NOT fire for a signal already aborted before
+      // this line — cancel explicitly in that case.
+      if (exec.signal?.aborted) run.cancel('parent step aborted')
+
+      try {
+        const result = await run.result
+        const error = stopReasonError(result)
+        if (error !== undefined) {
+          // Map a non-clean finish to an isError result (the registry turns a
+          // throw into an isError). Report the reason, not partial output.
+          throw new Error(error)
+        }
+        return [{ type: 'text', text: renderResult(run, result, maxResultChars) }]
+      } finally {
+        exec.signal?.removeEventListener('abort', onAbort)
+        // Always reach run quiescence — never leak a live script or children.
+        await run.dispose()
+      }
+    },
+    presentCall: args => presentWorkflowCall(args),
+    presentResult: (args, result) => presentWorkflowResult(args, result),
+  }))
+}

packages/workflow/tool-workflow/tests/tool-workflow.spec.ts

@@ -0,0 +1,254 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { WorkflowRunId, WorkflowService } from '@deepseek-ai/dsh-workflow'
+import type { WorkflowResult, WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread'
+import * as toolWorkflow from '../src/index.ts'
+
+/** A controllable engine standing in behind ctx.workflows (the tool's only seam). */
+class StubEngine extends WorkflowService {
+  requests: WorkflowStartRequest[] = []
+  cancels: string[] = []
+  disposed = 0
+  settle!: (result: WorkflowResult) => void
+  startError: Error | undefined
+
+  start(request: WorkflowStartRequest): WorkflowRun {
+    if (this.startError) throw this.startError
+    this.requests.push(request)
+    const result = new Promise<WorkflowResult>((resolve) => { this.settle = resolve })
+    request.signal?.addEventListener('abort', () => {
+      this.settle({ value: null, stopReason: 'cancelled', error: 'signal', agentsStarted: 0 })
+    }, { once: true })
+    return {
+      id: WorkflowRunId('run-1'),
+      meta: { name: 'stub-flow', description: 'd' },
+      result,
+      cancel: (reason?: string) => {
+        this.cancels.push(reason ?? 'cancelled')
+        this.settle({ value: null, stopReason: 'cancelled', ...reason !== undefined ? { error: reason } : {}, agentsStarted: 0 })
+      },
+      dispose: () => {
+        this.disposed += 1
+        return Promise.resolve()
+      },
+    }
+  }
+}
+
+async function setup(config?: { toolName?: string; maxResultChars?: number }) {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(StubEngine)
+  await ctx.plugin(toolWorkflow, config ?? {})
+  const engine = ctx.workflows as StubEngine
+  const parent = { id: AgentId('caller'), options: {} } as unknown as Agent
+  return { ctx, engine, parent }
+}
+
+const SCRIPT = 'return 1'
+const META = { name: 'audit', description: 'd' }
+
+function execute(ctx: Context, args: unknown, extra?: { agent?: Agent; signal?: AbortSignal }): Promise<ToolExecutionResult> {
+  return ctx.tools.execute({
+    callId: CallId('call-1'),
+    name: 'workflow',
+    arguments: args,
+    ...extra?.agent ? { agent: extra.agent } : {},
+    ...extra?.signal ? { signal: extra.signal } : {},
+  })
+}
+
+describe('dsh-tool-workflow', () => {
+  it('starts a run with the script/args/parent/signal and renders the completed value', async () => {
+    const { ctx, engine, parent } = await setup()
+    const controller = new AbortController()
+    const pending = execute(ctx, { script: SCRIPT, meta: META, args: { files: ['a.ts'] } }, { agent: parent, signal: controller.signal })
+    await vi.waitFor(() => { expect(engine.requests.length).toBe(1) })
+    expect(engine.requests[0]).toMatchObject({ script: SCRIPT, meta: META, args: { files: ['a.ts'] }, parent })
+    expect(engine.requests[0]!.signal).toBe(controller.signal)
+    engine.settle({ value: { findings: [1, 2] }, stopReason: 'completed', agentsStarted: 7 })
+    const result = await pending
+    expect(result.isError).toBe(false)
+    const rendered = (result.content[0] as { text: string }).text
+    expect(rendered).toContain('workflow "stub-flow" completed (7 agents)')
+    expect(rendered).toContain('"findings"')
+    expect(engine.disposed).toBe(1)
+  })
+
+  it('maps a non-completed stop reason to an isError result (and still disposes)', async () => {
+    const { ctx, engine, parent } = await setup()
+    const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent })
+    await vi.waitFor(() => { expect(engine.requests.length).toBe(1) })
+    engine.settle({ value: null, stopReason: 'error', error: 'script threw: boom', agentsStarted: 2 })
+    const result = await pending
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('workflow run failed: script threw: boom')
+    expect(engine.disposed).toBe(1)
+  })
+
+  it('reports a cancelled run distinctly (with and without a reason)', async () => {
+    const { ctx, engine, parent } = await setup()
+    const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent })
+    await vi.waitFor(() => { expect(engine.requests.length).toBe(1) })
+    engine.settle({ value: null, stopReason: 'cancelled', error: 'user', agentsStarted: 0 })
+    const result = await pending
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('workflow run was cancelled (user)')
+
+    const bare = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent })
+    await vi.waitFor(() => { expect(engine.requests.length).toBe(2) })
+    engine.settle({ value: null, stopReason: 'cancelled', agentsStarted: 0 })
+    expect(((await bare).content[0] as { text: string }).text.trim().endsWith('cancelled')).toBe(true)
+  })
+
+  it('an error result without a message renders the unknown-error fallback', async () => {
+    const { ctx, engine, parent } = await setup()
+    const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent })
+    await vi.waitFor(() => { expect(engine.requests.length).toBe(1) })
+    engine.settle({ value: null, stopReason: 'error', agentsStarted: 0 })
+    expect(((await pending).content[0] as { text: string }).text).toContain('unknown error')
+  })
+
+  it('cancels the run when exec.signal aborts MID-FLIGHT (the abort bridge)', async () => {
+    const { ctx, engine, parent } = await setup()
+    const controller = new AbortController()
+    const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent, signal: controller.signal })
+    await vi.waitFor(() => { expect(engine.requests.length).toBe(1) })
+    controller.abort()
+    const result = await pending
+    expect(result.isError).toBe(true)
+    expect(engine.cancels).toContain('parent step aborted')
+    expect(engine.disposed).toBe(1)
+  })
+
+  it('a synchronous engine start throw (meta/parse failure) becomes an isError result', async () => {
+    const { ctx, engine, parent } = await setup()
+    engine.startError = new Error('invalid meta: meta.name must be a non-empty string')
+    const result = await execute(ctx, { script: 'nope', meta: { name: '', description: 'd' } }, { agent: parent })
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('meta.name must be a non-empty string')
+  })
+
+  it('requires a calling agent (fails loud without exec.agent)', async () => {
+    const { ctx, engine } = await setup()
+    const result = await execute(ctx, { script: SCRIPT, meta: META })
+    expect(result.isError).toBe(true)
+    expect((result.content[0] as { text: string }).text).toContain('requires a calling agent')
+    expect(engine.requests.length).toBe(0)
+  })
+
+  it('validates its own arguments via the schema DSL (missing script)', async () => {
+    const { ctx, parent } = await setup()
+    const result = await execute(ctx, {}, { agent: parent })
+    expect(result.isError).toBe(true)
+    expect(result.error?.code).toBe('INVALID_ARGS')
+  })
+
+  it('cancels the run when exec.signal is ALREADY aborted at call time', async () => {
+    const { ctx, engine, parent } = await setup()
+    const controller = new AbortController()
+    controller.abort()
+    const result = await execute(ctx, { script: SCRIPT, meta: META }, { agent: parent, signal: controller.signal })
+    expect(result.isError).toBe(true)
+    expect(engine.cancels).toContain('parent step aborted')
+    expect(engine.disposed).toBe(1)
+  })
+
+  it('truncates an oversized rendered value with a notice (maxResultChars)', async () => {
+    const { ctx, engine, parent } = await setup({ maxResultChars: 40 })
+    const pending = execute(ctx, { script: SCRIPT, meta: META }, { agent: parent })
+    await vi.waitFor(() => { expect(engine.requests.length).toBe(1) })
+    engine.settle({ value: { blob: 'x'.repeat(500) }, stopReason: 'completed', agentsStarted: 1 })
+    const rendered = ((await pending).content[0] as { text: string }).text
+    expect(rendered).toContain('[truncated:')
+    expect(rendered.length).toBeLessThan(400)
+  })
+
+  it('registers under a configured toolName and unregisters on fiber dispose (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(StubEngine)
+    const fiber = await ctx.plugin(toolWorkflow, { toolName: 'orchestrate' })
+    expect(ctx.tools.get('orchestrate')).toBeDefined()
+    expect(ctx.tools.get('workflow')).toBeUndefined()
+    // The usage-policy prompt section rides the same registration: present
+    // under the CONFIGURED name (its guidance names the tool it describes)…
+    const sections = (await ctx.systemPrompt.assemble()).sections
+    const section = sections.find(s => s.name === 'tool:orchestrate')
+    expect(section?.text).toContain('orchestrate')
+    expect(sections.some(s => s.name === 'tool:workflow')).toBe(false)
+    await fiber.dispose()
+    expect(ctx.tools.get('orchestrate')).toBeUndefined()
+    // …and gone with the fiber — a reload must not leak a stale section.
+    expect((await ctx.systemPrompt.assemble()).sections.some(s => s.name === 'tool:orchestrate')).toBe(false)
+  })
+
+  it('presents a generic pending card titled by the meta name, with the script as rawInput', async () => {
+    const { ctx } = await setup()
+    const tool = ctx.tools.get('workflow')!
+    const view = tool.presentCall!({ script: SCRIPT, meta: META })
+    expect(view).toMatchObject({ card: 'generic', title: 'workflow: audit', rawInput: SCRIPT })
+  })
+
+  it('presentResult keeps the generic card; presentation is pure and replay-safe on malformed args', async () => {
+    const { ctx } = await setup()
+    const tool = ctx.tools.get('workflow')!
+    expect(tool.presentResult!({ script: SCRIPT, meta: META }, { content: [], isError: false })).toEqual({ card: 'generic' })
+    // defineTool soft-validates presentation args: a malformed logged shape
+    // (wrong fields entirely, or a call missing its meta) falls back to
+    // undefined instead of throwing mid-replay.
+    expect(tool.presentCall!({ not: 'the schema' })).toBeUndefined()
+    expect(tool.presentCall!({ script: SCRIPT })).toBeUndefined()
+  })
+
+  it('has the namespace-plugin export shape (no stray default)', () => {
+    expect('default' in toolWorkflow).toBe(false)
+    expect(toolWorkflow.name).toBe('tool-workflow')
+    expect(toolWorkflow.inject).toEqual(['tools', 'workflows', 'systemPrompt'])
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(toolWorkflow) as Record<string, unknown>
+    expect(unwrapped).toBe(toolWorkflow)
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+
+  describe('composition with the REAL worker-thread engine (the mock above must stay honest)', () => {
+    it('an abort releases the tool even when the script parks on a promise no hook owns', async () => {
+      // Regression for the review-found turn wedge: the tool awaits
+      // run.result BEFORE its disposing finally, the registry and the loop
+      // await the tool — so if cancellation could not settle result (a script
+      // parked on `await new Promise(() => {})`), an aborted turn stayed
+      // wedged forever. The seam now guarantees result settles within the
+      // grace of cancel(); this drives that guarantee through the real
+      // registry + real tool + real engine.
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      await ctx.plugin(ToolRegistry)
+      await ctx.plugin(SubagentService)
+      await ctx.plugin(WorkerWorkflowEngine, { disposeGraceMs: 30 })
+      await ctx.plugin(toolWorkflow, {})
+      const parent = { id: AgentId('caller'), options: {} } as unknown as Agent
+      const controller = new AbortController()
+      const pending = execute(ctx, {
+        script: 'await new Promise(() => {})\nreturn 1',
+        meta: { name: 'stuck', description: 'parks forever' },
+      }, { agent: parent, signal: controller.signal })
+      // Give the run a beat to start (past its synchronous slice), then abort.
+      await new Promise(resolve => setTimeout(resolve, 20))
+      controller.abort('user abort')
+      const result = await pending
+      expect(result.isError).toBe(true)
+      expect((result.content[0] as { text: string }).text).toContain('cancelled')
+    })
+  })
+})

packages/workflow/tool-workflow/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../workflow"
+    }
+  ]
+}

packages/workflow/workflow-workerthread/README.md

@@ -0,0 +1,49 @@
+# @deepseek-ai/dsh-workflow-workerthread
+
+The [`WorkflowService`](../workflow/README.md) implementation, on **`node:worker_threads`**: each run gets its OWN worker thread (one run = one worker, no pooling — a run is heavyweight, so the ~tens-of-ms thread spin-up is noise), the script executes in a vm context INSIDE that worker with the workflow hooks injected, and every `agent()` call bridges back over the message port to [`ctx.subagents`](../../subagent/README.md) on the host. Child agents are I/O-bound LLM loops and stay on the host event loop; the thread isolates the SCRIPT, the only part that can spin synchronously.
+
+## Trust premise: what the thread buys (and what it does not)
+
+Workflow scripts are **model-written** — the same trust level as the model's existing bash access — so this engine defends against **buggy** scripts, never hostile ones. A worker thread is NOT a security boundary: the vm context inside it is escapable by construction (`node:vm` shares object machinery with its surrounding realm, so a script can reach the `Function` constructor via `globalThis.constructor.constructor` and from it `process` and every Node builtin), and an escapee holds the same process privileges as the host — Node's permission model is process-wide. The absent globals are API surface that keeps honest scripts portable, not walls. What the thread concretely buys:
+
+- **The host never blocks**: `start()` returns without running any script code on the host; a synchronous spin anywhere in the script occupies the worker's loop, not the harness's.
+- **Termination is real**: a script that outlives its post-cancel grace is `worker.terminate()`d — nothing of it survives `dispose()`, where an in-process engine could only abandon the spin on its own loop.
+- **No ambient credentials**: the worker spawns with an EMPTY environment (`env: {}` plus hermetic `execArgv`, the same stance as `dsh-code-runtime-worker`; the unbuilt dev shape forwards exactly one loader variable, `TSX_TSCONFIG_PATH` — path plumbing, not a secret), so an escapee reading `process.env` finds no harness secrets — ambient-channel hardening only; the process-wide privileges above (fs and the rest) remain, so a genuine sandbox is still the engine swap.
+- **Serialization by construction**: everything crossing the thread is structured-clone data, and plain JSON before that — the `materializeFromRealm` walk rejects loud what JSON cannot carry, which is also what makes every postMessage hop total.
+
+What the seam guarantees regardless, because benign scripts hit these constantly: `result` never rejects, a dropped hook promise never becomes an unhandled rejection, values JSON cannot carry are rejected **loud** instead of silently mangled, and hook misuse is fatal instead of dissolving into a per-item `null`. Genuine sandboxing (containing what an escaped script may touch) remains an isolated-vm/separate-process engine swap behind the seam, still deferred.
+
+## The script contract it executes
+
+- **Meta as DATA** (`validateMeta`, host-side): the workflow's identity arrives on the start request as plain JSON (the tool carries it as its schema-validated `meta` parameter — never as script text) and is shape-validated loud, every violation named (`name`/`description` required; unknown fields rejected). The engine deliberately evaluates NO script text to obtain meta: an evaluated meta literal could smuggle getters that run on the host outside any vm timeout — the exact spin the worker thread exists to isolate. A body that still opens with a Claude Code-style `export const meta` statement is rejected with a pointed `SCRIPT_PARSE` message.
+- **Hooks**: `agent(prompt, {label, phase, schema, model})` (schema = the [structured-output subset](../../core/tools/README.md), forwarded as `outputSchema`; result = validated object, or final text without a schema; a failed child resolves `null`), `parallel(thunks)`, `pipeline(items, ...stages)` with NO cross-stage barrier and `(prev, item, index)` stage callbacks, `phase(title)`, `log(message)`, and the `args` global. Anything else — `effort`/`isolation`/`agentType`, unknown options, malformed arguments, schemas outside the subset — throws a FATAL `WorkflowError` that `parallel`/`pipeline` re-throw rather than nulling (see the seam README's failure discipline).
+- **No ambient APIs**: no timers, filesystem, or Node APIs are injected into the context (absence is API surface, not containment — see the trust premise).
+
+## How a run executes
+
+`start()` shape-validates the meta DATA host-side and parse-checks the body with the identical wrapper the worker compiles (`new vm.Script`, discarded), preserving the seam's synchronous `META_INVALID`/`SCRIPT_PARSE` throws; one redundant parse per run is the deliberate price. It then spawns the worker (`src/worker.ts` unbuilt via an explicit tsx `execArgv`; the sibling `lib/worker.js` bundle when built) with the meta, body, `args`, and worker-side limits as `workerData`.
+
+Inside the worker, `runWorkerSession` builds the execution core (hooks, combinators, concurrency semaphore, caps, fatal-error discipline) over a **child port**: `agent()` sends `child-start` and the host starts the child on `ctx.subagents` (parent attribution, the shared per-run abort signal, `outputSchema`/`model` pass-through), replying with the child id, its settlement (a JSON projection; an infrastructure REJECTION crosses as `child-failed` and stays the fatal `AGENT_RESULT`), and dispose acks. Observer narration (`phase`/`log`/`agent-start`/`agent-end`) crosses as messages and re-emits as the seam's `workflow/*` events. A **ready→go handshake** gates the body: a cancellation racing worker boot arrives before `go`, so a run cancelled before start never executes the body at all.
+
+## The value boundary
+
+Values LEAVING the script (hook options/schemas, the script's return) are materialized by `materializeFromRealm`: a plain recursive walk that rejects loud everything JSON cannot carry (exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers, nested `undefined`), copying into plain containers via `defineProperty` so a `"__proto__"` key becomes a data property, never a prototype mutation. Getters are read ordinarily — the RESULT is what crosses; a read that throws fails loud; both run in the WORKER, never on the host. Values ENTERING the realm (`args`, `agent()` results, hook promises and their failures, combinator arrays) are handed over directly as worker-realm values — the script is trusted, so outer prototypes are not a leak; `args` is cloned once at start so a script scribbling on it cannot mutate the caller's object. One script-visible consequence: an error thrown by a hook is built OUTSIDE the script's vm context, so `e instanceof Error` inside the script is `false` — branch on `e.name`/`e.code` instead (the combinators recognize fatality by `instanceof` against their own realm's class, which a script-built object can never pass, so fatal-vs-null cannot be forged or dissolved).
+
+## Cancellation, death, disposal
+
+Per-run limits: a concurrency semaphore (`maxConcurrentAgents`), a total-`agent()` cap (`maxTotalAgents`), and a per-call item cap (`maxItemsPerCall`), all config. `cancel()` posts the cancel to the worker (its hooks start throwing `CANCELLED`; the script dies at its next await) and cancels every host-side child NOW on **both seam channels** — the shared request signal aborts AND each registered child's explicit `cancel()` is called host-side, because the seam leaves a provider free to honor either channel and a worker wedged in a synchronous spin could not relay its own per-child cancel RPCs (those later land as idempotent no-ops). The grace then arms: a run still unsettled `disposeGraceMs` later force-settles `cancelled` and the worker is **terminated**. A cancellation that lands before the body runs (the ready→go handshake) reports `cancelled` without executing anything; a worker `result` racing an in-flight host cancellation reports `cancelled` too (first-wins settlement — the seam-visible result had not settled when cancellation was requested); post-cancel `phase`/`log` narration is suppressed host-side, while cancelled children still deliver their paired `agent-end`.
+
+A worker that dies unexpectedly (an OOM, a script reaching `process.exit` through the documented vm escape) settles the run `stopReason: 'error'` with the exit diagnostics — or `'cancelled'` when a cancel was in flight — and the host-side child registry is what winds every surviving child down. `dispose()` = cancel + immediate host-driven disposal of every registered child (a wedged worker can relay no dispose RPC, so child teardown overlaps the grace instead of starting after it; the worker's own dispose RPCs join the same per-child disposal) + bounded wait (result, then child-registry quiescence, capped by the grace) + unconditional `worker.terminate()`: the thread never outlives its run. Once a run settles, stray children a script fired without awaiting are cancelled too, and `dispose()` waits for their disposal (bounded by the grace) before returning. `agent-start`/`agent-end` pairing is host-guaranteed the same way: forwarded starts live in a ledger, worker-reported ends pair them on the graceful paths, and the termination paths (grace force-settle, worker death) synthesize the missing ends (outcome `cancelled`) before the run settles — a start still in flight across the force-settle can surface after `workflow/end`, immediately paired the same way.
+
+**Engine-specific limitations**: worker startup is paid per run; on a termination path `agentsStarted` reports the HOST-observed count (accepted `child-start`s — calls still queued worker-side for a concurrency slot are unknowable then); and a returned promise or thenable resolves per JavaScript semantics BEFORE materialization — that is what makes an un-awaited `return agent('x')` work — with the value-boundary guard applying to the resolution.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `provider` | `spawn` | The `ctx.subagents` provider children run on (host-side). |
+| `maxConcurrentAgents` | `0` (auto) | Concurrent `agent()` ceiling; `0` resolves to `min(16, max(1, cores - 2))`. |
+| `maxTotalAgents` | `1000` | Total `agent()` calls one run may start (runaway-loop backstop). |
+| `maxItemsPerCall` | `4096` | Items accepted by one `parallel()`/`pipeline()` call. |
+| `syncTimeoutMs` | `5000` | vm timeout for the script's initial synchronous slice (in the worker). |
+| `disposeGraceMs` | `5000` | How long a cancelled run may stay unsettled before force-settle + terminate; also bounds `dispose()`. |

packages/workflow/workflow-workerthread/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@deepseek-ai/dsh-workflow-workerthread",
+  "description": "worker-thread workflow engine: executes model-written orchestration scripts off the host event loop, bridging agent() calls back to ctx.subagents",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./worker": {
+      "types": "./lib/types/worker.d.ts",
+      "default": "./lib/worker.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/worker.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-workflow": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-spawn": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-workflow": "workspace:^",
+    "cordis": "^4.0.0-rc.6",
+    "tsx": "^4.19.2"
+  }
+}

packages/workflow/workflow-workerthread/src/host.ts

@@ -0,0 +1,473 @@
+/**
+ * The host half of one worker-engine run: spawn the Worker, bridge its child
+ * RPC onto `ctx.subagents`, fan its observer messages into the engine's
+ * events, and own cancellation, the settle-within-grace guarantee, and child
+ * cleanup. The worker's lifetime IS the run's lifetime: `dispose()` always
+ * ends with `worker.terminate()`, so no thread outlives its run.
+ *
+ * The run's `result` promise settles exactly once, from whichever of these
+ * lands first: the worker's `result` message (a host-side cancellation in
+ * flight overrides a non-cancelled report — the seam-visible result had not
+ * settled when cancellation was requested), an unexpected worker death
+ * (`error`/`messageerror`/premature `exit` → `stopReason: 'error'`, or
+ * `'cancelled'` when a cancel was in flight), or the post-cancel grace timer
+ * (a script that never settles is force-settled `cancelled` and its worker
+ * terminated — the real kill an in-process engine could not perform).
+ *
+ * Children live in a host-side registry (callId → run): the worker drives
+ * their disposal by RPC on the graceful path, `dispose()` host-drives every
+ * registered child's disposal immediately (a wedged worker can relay no
+ * dispose RPC, and child teardown must overlap the grace, not start after
+ * it), and the registry is what lets the host abort and dispose every
+ * survivor when the worker dies or is terminated mid-flight. The three
+ * paths share ONE disposal per child (memoized by callId; the seam's
+ * dispose() is idempotent anyway, the memo keeps the bookkeeping and the
+ * containment warn single). Lifecycle pairing is host-guaranteed the same
+ * way: every forwarded `agent-start` lives in a ledger, and a start the
+ * dead or terminated worker never paired is closed by a synthesized
+ * `agent-end` (outcome `'cancelled'`) before the run settles. On a
+ * termination path `agentsStarted` reports the
+ * HOST-observed count (accepted `child-start` messages) — `agent()` calls
+ * still queued worker-side for a concurrency slot are unknowable then; the
+ * worker's own count rides the result message on every graceful path.
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/host
+ */
+
+import { fileURLToPath } from 'node:url'
+import { Worker } from 'node:worker_threads'
+import type { WorkerOptions } from 'node:worker_threads'
+import type { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import type { SubagentRun } from '@deepseek-ai/dsh-subagent'
+import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowMeta, WorkflowResult, WorkflowRun, WorkflowRunId } from '@deepseek-ai/dsh-workflow'
+import { renderThrown } from './realm.ts'
+import type { ExecutionObserver } from './runtime.ts'
+import { HostToWorkerType, WorkerToHostType } from './protocol.ts'
+import type { HostToWorkerPayloads, WorkerToHostMessage } from './protocol.ts'
+import type { ChildStartRequest, WorkerInit } from './types.ts'
+
+/**
+ * Resolve the worker entry and spawn options for the current runtime shape.
+ * Unbuilt (tsx demos, vitest — `import.meta.url` points into `src/`), the
+ * entry is the TypeScript sibling and the worker needs the tsx loader
+ * registered explicitly: a worker thread inherits no transform pipeline from
+ * vitest (vite transforms in-process, not via a node loader), and passing
+ * execArgv explicitly also shields the worker from any loader flags the
+ * parent was started with. Built (`lib/index.js`), the entry is the sibling
+ * bundle the package tsdown config emits and no loader is needed (execArgv
+ * pinned empty — hermetic, like the environment).
+ *
+ * Both shapes spawn with an EMPTY environment (`env: {}`): the documented vm
+ * escape reaches `process`, and the harness's ambient credentials
+ * (`DEEPSEEK_API_KEY` et al.) must not ride along — the same stance as
+ * `dsh-code-runtime-worker`, stronger than the scrubbed env the
+ * defensive-patterns rule requires for spawned commands (a shell needs PATH;
+ * this worker needs nothing). Sole exception: the unbuilt shape forwards
+ * `TSX_TSCONFIG_PATH` when the parent carries it (loader plumbing the paths
+ * map depends on outside the repo cwd, not a secret). This closes the
+ * AMBIENT channel only — an escapee still holds process-wide privileges
+ * like fs access (the README's trust premise stands).
+ * @param init - the run payload, passed as `workerData`.
+ * @returns the entry URL and the Worker options to spawn it with.
+ */
+function resolveWorkerSpawn(init: WorkerInit): { entry: URL; options: WorkerOptions } {
+  /* v8 ignore next 3 -- the built-output arm: tests always run unbuilt (src/); the built-worker e2e exercises this shape for real */
+  if (!import.meta.url.endsWith('.ts')) {
+    return { entry: new URL('./worker.js', import.meta.url), options: { workerData: init, env: {}, execArgv: [] } }
+  }
+  // Lazy tsx resolution: only the unbuilt shape needs it, so the built
+  // bundle never requires tsx to be installed. TSX_TSCONFIG_PATH is the one
+  // variable forwarded through the scrub: tsx finds a tsconfig by searching
+  // UP from the worker's cwd, and a parent running with its cwd outside the
+  // repo (the ACP snapshot harness pins the tsconfig through this exact
+  // variable) would otherwise lose the dsh-* paths map and resolve workspace
+  // imports to unbuilt lib/ bundles. Loader plumbing, not a secret.
+  return {
+    entry: new URL('./worker.ts', import.meta.url),
+    options: {
+      workerData: init,
+      env: process.env.TSX_TSCONFIG_PATH === undefined ? {} : { TSX_TSCONFIG_PATH: process.env.TSX_TSCONFIG_PATH },
+      execArgv: ['--import', fileURLToPath(import.meta.resolve('tsx'))],
+    },
+  }
+}
+
+/**
+ * One live worker-engine run — the seam's {@link WorkflowRun}, returned by
+ * `start()` directly. Owns the Worker, the child registry, and the result
+ * settlement; `result` never rejects. `meta` is this handle's OWN clone
+ * (event payloads carry separate clones), so a consumer mutating it corrupts
+ * nothing.
+ */
+export class WorkerRun implements WorkflowRun {
+  /** Settles exactly once with the run's outcome; never rejects. */
+  readonly result: Promise<WorkflowResult>
+  private settleResolve!: (result: WorkflowResult) => void
+  private settled = false
+  private cancelReason: string | undefined
+  private graceTimer: NodeJS.Timeout | undefined
+  private readonly worker: Worker
+  /** Set on `exit`: the thread is gone, so posting has nowhere to go. */
+  private workerGone = false
+  /** Accepted `child-start` messages — the terminate-path `agentsStarted` (see module doc). */
+  private hostStarted = 0
+  /** Live children by callId; an entry leaves ONLY after its dispose settles (quiescence = empty). */
+  private readonly children = new Map<number, SubagentRun>()
+  /** In-flight child disposals by callId — the memo that gives every path (worker RPC, dispose(), reap) ONE shared disposal per child. */
+  private readonly childDisposals = new Map<number, Promise<void>>()
+  /** Started-but-not-ended agents by seq — the pairing ledger the HOST guarantees (see {@link endAgent}). */
+  private readonly liveAgents = new Map<number, WorkflowAgentInfo>()
+  private readonly quiescenceWaiters: (() => void)[] = []
+  /** The per-run abort fanout every child start request carries. */
+  private readonly controller = new AbortController()
+  private disposed: Promise<void> | undefined
+
+  constructor(
+    private readonly ctx: Context,
+    readonly id: WorkflowRunId,
+    readonly meta: WorkflowMeta,
+    private readonly parent: Agent,
+    init: WorkerInit,
+    private readonly provider: string,
+    private readonly disposeGraceMs: number,
+    private readonly observer: ExecutionObserver,
+    signal: AbortSignal | undefined,
+  ) {
+    this.result = new Promise<WorkflowResult>((resolve) => { this.settleResolve = resolve })
+    // workerData rides the structured clone: args are plain JSON by the seam
+    // contract, so the clone is total and doubles as the caller-isolation
+    // copy (a clone failure throws loud out of start()).
+    const { entry, options } = resolveWorkerSpawn(init)
+    this.worker = new Worker(entry, options)
+    this.worker.on('message', (message: WorkerToHostMessage) => { this.onMessage(message) })
+    this.worker.on('error', (error) => { this.onWorkerDeath(`workflow worker failed: ${renderThrown(error)}`) })
+    /* v8 ignore next -- messageerror: not constructible from the engine's own protocol (every payload is JSON data) */
+    this.worker.on('messageerror', (error) => { this.onWorkerDeath(`workflow worker message failed to deserialize: ${renderThrown(error)}`) })
+    this.worker.on('exit', (code) => {
+      this.workerGone = true
+      this.onWorkerDeath(`workflow worker exited before the run settled (exit code ${code})`)
+    })
+    if (signal?.aborted) {
+      this.cancel('workflow start signal already aborted')
+    } else {
+      signal?.addEventListener('abort', () => { this.cancel('workflow signal aborted') }, { once: true })
+    }
+  }
+
+  /**
+   * Cancel the run: the worker is told (its hooks start throwing and the
+   * script dies at its next await), every host-side child is cancelled NOW on
+   * BOTH seam channels — the shared request signal aborts and each registered
+   * child's explicit `cancel()` is called (the seam leaves a provider free to
+   * honor either, and a worker wedged in a synchronous spin could not relay
+   * its own per-child cancel RPCs until far too late) — and the grace timer
+   * arms: a run still unsettled `disposeGraceMs` later force-settles
+   * `cancelled` and its worker is TERMINATED. Idempotent; the first reason
+   * wins.
+   * @param reason - human-readable cause (default `'workflow cancelled'`).
+   */
+  cancel(reason?: string): void {
+    // A settled run has nothing left to cancel: without this guard the
+    // ordinary consumer path (await result, then dispose -> cancel) would arm
+    // a grace timer nothing ever clears, pinning the run and its Worker
+    // closure until the grace expires - a bounded leak per completed run.
+    if (this.settled || this.cancelReason !== undefined) return
+    this.cancelReason = reason ?? 'workflow cancelled'
+    this.post(HostToWorkerType.Cancel, { reason: this.cancelReason })
+    this.controller.abort(this.cancelReason)
+    // The explicit channel is driven host-side, not left to the worker: a
+    // provider honoring only run.cancel() must not wait on a wedged worker's
+    // ChildCancel relay (those later RPCs land as idempotent no-ops).
+    for (const run of this.children.values()) run.cancel(this.cancelReason)
+    this.graceTimer = setTimeout(() => {
+      // The worker may no longer speak (it is about to be terminated): pair
+      // every stranded start before the run settles, so ends precede
+      // workflow/end.
+      this.endStrandedAgents()
+      this.settleResult(this.cancelledResult(this.hostStarted))
+      void this.worker.terminate()
+    }, this.disposeGraceMs)
+    // unref'd: an armed grace timer must never hold the process open.
+    this.graceTimer.unref()
+  }
+
+  /**
+   * Cancel + bounded settle + termination. Host-drives every registered
+   * child's disposal IMMEDIATELY — a wedged worker can relay no dispose RPC,
+   * and deferring child teardown to the post-terminate reap would spend the
+   * whole grace waiting for a quiescence that cannot start, then return with
+   * the disposals still in flight — so child disposal overlaps the same
+   * grace the worker gets to settle (the worker's own dispose RPCs join the
+   * shared per-child disposal). Waits (at most the grace) for the result and
+   * child quiescence, then terminates the worker unconditionally — the
+   * thread never outlives its run — and reaps whatever children remain
+   * (their disposal is contained, not awaited past the grace, the same
+   * abandonment the seam documents for a slow-disposing child). Idempotent;
+   * safe on every path.
+   * @returns resolves when the run's resources are released or abandoned.
+   */
+  dispose(): Promise<void> {
+    this.disposed ??= (async () => {
+      this.cancel('workflow disposed')
+      for (const [callId, run] of [...this.children]) void this.disposeChild(callId, run)
+      await Promise.race([
+        (async () => {
+          await this.result
+          await this.childQuiescence()
+        })(),
+        sleep(this.disposeGraceMs),
+      ])
+      await this.worker.terminate()
+      this.reapChildren('workflow disposed')
+    })()
+    return this.disposed
+  }
+
+  /** Post one message to the worker (payload looked up from the tag's map entry), tolerating a thread that is already gone. */
+  private post<T extends HostToWorkerType>(type: T, payload: HostToWorkerPayloads[T]): void {
+    if (this.workerGone) return
+    try {
+      this.worker.postMessage({ type, ...payload })
+    } catch (error: unknown) {
+      // Only a teardown race can land here (every engine message is JSON
+      // data, so serialization cannot fail); there is nothing left to
+      // deliver to — log and move on.
+      /* v8 ignore next -- postMessage teardown race (a throw between exit and its event): not constructible in-process */
+      this.ctx.logger.warn(`workflow-workerthread: postMessage failed: ${renderThrown(error)}`)
+    }
+  }
+
+  private onMessage(message: WorkerToHostMessage): void {
+    switch (message.type) {
+      case WorkerToHostType.Ready:
+        this.post(HostToWorkerType.Go, {})
+        break
+      case WorkerToHostType.Phase:
+        // Post-cancel narration is suppressed host-side: worker-side the
+        // hooks throw once the cancel message is PROCESSED, but narration
+        // already in flight (or emitted while the cancel crossed the
+        // boundary) must not reach observers — nothing is emitted after
+        // cancel() returns.
+        if (this.cancelReason === undefined) this.observer.phase(message.title)
+        break
+      case WorkerToHostType.Log:
+        if (this.cancelReason === undefined) this.observer.log(message.message)
+        break
+      case WorkerToHostType.AgentStart:
+        this.liveAgents.set(message.info.seq, message.info)
+        this.observer.agentStart(message.info)
+        break
+      case WorkerToHostType.AgentEnd:
+        // NOT suppressed on cancel: cancelled children report their paired
+        // agent-end with outcome 'cancelled'. The gate (with the termination
+        // paths' synthesis) is what makes the one-pair-per-started-child
+        // contract hold on every stop path.
+        this.endAgent(message.info)
+        break
+      case WorkerToHostType.ChildStart:
+        this.onChildStart(message.callId, message.request)
+        break
+      case WorkerToHostType.ChildCancel:
+        this.children.get(message.callId)?.cancel(message.reason)
+        break
+      case WorkerToHostType.ChildDispose:
+        this.onChildDispose(message.callId)
+        break
+      case WorkerToHostType.Result:
+        this.onResult(message.result)
+        break
+      /* v8 ignore next 2 -- closed engine-owned union; the arm only makes adding a message type a compile error */
+      default:
+        assertNever(message, 'worker-to-host message')
+    }
+  }
+
+  private onChildStart(callId: number, request: ChildStartRequest): void {
+    if (this.cancelReason !== undefined) {
+      // The worker's start raced our cancel: refuse — a child must never
+      // start on an already-aborted signal (a provider subscribing only to
+      // future abort events would never observe it).
+      this.post(HostToWorkerType.ChildStartError, { callId, rendered: `workflow run cancelled: ${this.cancelReason}` })
+      return
+    }
+    this.hostStarted += 1
+    let run: SubagentRun
+    try {
+      run = this.ctx.subagents.start(this.provider, {
+        prompt: [{ type: 'text', text: request.prompt }],
+        parent: this.parent,
+        signal: this.controller.signal,
+        ...request.schema !== undefined ? { outputSchema: request.schema } : {},
+        ...request.model !== undefined ? { agentOptions: { model: request.model } } : {},
+      })
+    } catch (error: unknown) {
+      this.post(HostToWorkerType.ChildStartError, { callId, rendered: renderThrown(error) })
+      return
+    }
+    this.children.set(callId, run)
+    this.post(HostToWorkerType.ChildStarted, { callId, childId: run.id })
+    run.result.then(
+      (result) => {
+        this.post(HostToWorkerType.ChildSettled, {
+          callId,
+          result: {
+            output: result.output,
+            ...result.structured !== undefined ? { structured: result.structured } : {},
+            stopReason: result.stopReason,
+          },
+        })
+      },
+      (error: unknown) => { this.post(HostToWorkerType.ChildFailed, { callId, rendered: renderThrown(error) }) },
+    )
+  }
+
+  private onChildDispose(callId: number): void {
+    const run = this.children.get(callId)
+    if (run === undefined) {
+      // Already disposed host-side (a dispose() drive or a death reap beat
+      // the RPC) — the ack is still owed (the worker-side wrapper awaits it).
+      this.post(HostToWorkerType.ChildDisposed, { callId })
+      return
+    }
+    // disposeChild never rejects (containment is inside), so the ack always follows.
+    void this.disposeChild(callId, run).then(() => { this.post(HostToWorkerType.ChildDisposed, { callId }) })
+  }
+
+  /**
+   * Start (or join) one registered child's disposal; the registry entry
+   * leaves when it settles. Memoized per callId: the worker's dispose RPC,
+   * the dispose() host drive, and the reap can all land on the same child —
+   * the child's `dispose()` runs once and every caller awaits that one
+   * settlement. A rejection is contained (the subagent seam's dispose() is
+   * not supposed to reject, but a backend that does anyway must not break
+   * quiescence): logged, and the child still leaves the registry.
+   * @param callId - the child's registry key.
+   * @param run - the registered child (the caller looked it up).
+   * @returns resolves when the disposal settled either way; never rejects.
+   */
+  private disposeChild(callId: number, run: SubagentRun): Promise<void> {
+    let disposal = this.childDisposals.get(callId)
+    if (disposal === undefined) {
+      disposal = run.dispose().then(
+        () => { this.finishChild(callId) },
+        (error: unknown) => {
+          this.ctx.logger.warn(`workflow-workerthread: child dispose failed: ${renderThrown(error)}`)
+          this.finishChild(callId)
+        },
+      )
+      this.childDisposals.set(callId, disposal)
+    }
+    return disposal
+  }
+
+  /** Drop a child from the registry (and its disposal memo), releasing quiescence waiters at zero. */
+  private finishChild(callId: number): void {
+    this.children.delete(callId)
+    this.childDisposals.delete(callId)
+    if (this.children.size === 0) {
+      for (const waiter of this.quiescenceWaiters.splice(0)) waiter()
+    }
+  }
+
+  /** Resolves once the child registry is empty (every disposal settled). */
+  private childQuiescence(): Promise<void> {
+    if (this.children.size === 0) return Promise.resolve()
+    return new Promise((resolve) => { this.quiescenceWaiters.push(resolve) })
+  }
+
+  /** Abort + dispose every registered child (worker death / final teardown); disposal is contained, not awaited. */
+  private reapChildren(reason: string): void {
+    this.controller.abort(this.cancelReason ?? reason)
+    for (const [callId, run] of [...this.children]) {
+      run.cancel(this.cancelReason ?? reason)
+      void this.disposeChild(callId, run)
+    }
+  }
+
+  private onResult(result: WorkflowResult): void {
+    // The worker's settle-reap already child-cancel()s every stray; this
+    // abort fires the seam signal too, for providers that only honor the
+    // request signal (both channels, on every path).
+    if (this.cancelReason === undefined) this.controller.abort('workflow settled')
+    if (this.cancelReason !== undefined && result.stopReason !== 'cancelled') {
+      // The script settled while our cancel was crossing the thread boundary
+      // — the seam-visible result had NOT settled when cancellation was
+      // requested, so report cancelled (the vm drive()'s post-settle check,
+      // relocated to the receiving side of the race).
+      this.settleResult(this.cancelledResult(result.agentsStarted))
+      return
+    }
+    this.settleResult(result)
+  }
+
+  /** An unexpected worker death (or the expected exit after termination). */
+  private onWorkerDeath(message: string): void {
+    // Whatever the worker left behind must not leak — abort + dispose it all.
+    if (this.children.size > 0) this.reapChildren('workflow worker gone')
+    // The thread is gone: no more worker-authored agent-ends can arrive —
+    // pair every stranded start (a start that crossed between the grace
+    // force-settle and this exit included) before the run settles.
+    this.endStrandedAgents()
+    // settleResult no-ops on an already-settled run (the expected exit after
+    // a dispose's terminate lands here too).
+    if (this.cancelReason !== undefined) {
+      this.settleResult(this.cancelledResult(this.hostStarted))
+      return
+    }
+    this.settleResult({ value: null, stopReason: 'error', error: message, agentsStarted: this.hostStarted })
+  }
+
+  /**
+   * The single agent-end emission gate: forwards `end` iff its start is still
+   * unpaired in the ledger, so every forwarded `workflow/agent-start` gets
+   * EXACTLY one `workflow/agent-end` — the worker's own report where it can
+   * speak, a host-synthesized one where it cannot ({@link endStrandedAgents}).
+   * @param end - the settlement to emit (worker-reported or synthesized).
+   */
+  private endAgent(end: WorkflowAgentEndInfo): void {
+    /* v8 ignore next -- a real end still in flight across the grace force-settle: not orderable in-process */
+    if (!this.liveAgents.delete(end.seq)) return
+    this.observer.agentEnd(end)
+  }
+
+  /**
+   * Synthesize the missing `agent-end` for every started-but-unpaired agent,
+   * outcome `'cancelled'`: the reap cancels every child, and a real
+   * settlement racing the force-settle loses to the cancellation — the same
+   * first-wins override {@link onResult} applies to the run's own result.
+   * Called where the worker can no longer speak (the grace force-settle,
+   * worker death), BEFORE settleResult, so the paired ends reach observers
+   * before `workflow/end`.
+   */
+  private endStrandedAgents(): void {
+    for (const info of [...this.liveAgents.values()]) {
+      this.endAgent({ ...info, outcome: 'cancelled' })
+    }
+  }
+
+  private cancelledResult(agentsStarted: number): WorkflowResult {
+    // cancel() is the only writer of cancelReason and every caller checks it
+    // first; the fallback guards the type, not a reachable path.
+    /* v8 ignore next */
+    const reason = this.cancelReason ?? 'workflow cancelled'
+    return { value: null, stopReason: 'cancelled', error: `workflow run cancelled: ${reason}`, agentsStarted }
+  }
+
+  /** First settle wins; disarms the grace timer. */
+  private settleResult(result: WorkflowResult): void {
+    if (this.settled) return
+    this.settled = true
+    clearTimeout(this.graceTimer)
+    this.settleResolve(result)
+  }
+}
+
+/** A plain timer sleep (the dispose grace); unref'd so it never holds the process open. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms)
+    timer.unref()
+  })
+}

packages/workflow/workflow-workerthread/src/index.ts

@@ -0,0 +1,203 @@
+/**
+ * The `node:worker_threads` workflow engine: the {@link WorkflowService}
+ * implementation. Runs each script in its OWN worker thread (one run = one
+ * worker, no pooling — a run is heavyweight, so thread spin-up is noise): the
+ * body executes in a vm context INSIDE the worker with the workflow hooks
+ * injected, and `agent()` calls bridge back to `ctx.subagents` over the
+ * message port — child agents are I/O-bound LLM loops and stay on the host
+ * event loop; the thread isolates the SCRIPT, the only part that can spin
+ * synchronously.
+ *
+ * TRUST PREMISE: scripts are MODEL-WRITTEN — the same trust level as the
+ * model's existing bash access — so this engine defends against BUGGY
+ * scripts, never hostile ones. A worker thread is NOT a security boundary:
+ * the vm context inside it is escapable by construction, and an escapee
+ * holds the same process privileges as the host (Node's permission model is
+ * process-wide); genuine sandboxing (isolated-vm, a separate process) is an
+ * engine swap behind the seam. What the thread buys, concretely:
+ *
+ * - `start()` never blocks the host: the script's initial synchronous slice
+ *   (and any later synchronous spin) occupies the WORKER's event loop, not
+ *   the harness's.
+ * - Termination is REAL: a script that outlives its post-cancel grace is
+ *   `worker.terminate()`d — nothing of the script survives `dispose()`,
+ *   where an in-process engine could only abandon the spin on its own loop.
+ * - The value boundary is serialization by construction: everything crossing
+ *   the thread is structured-clone data (and plain JSON before that, by the
+ *   materialization walk in ./realm.ts).
+ *
+ * Engine-specific limitations: worker startup (~tens of ms) is paid per run;
+ * on a termination path `agentsStarted` reports the host-observed child
+ * count (calls still queued worker-side for a slot are unknowable — see
+ * ./host.ts); and a worker that dies unexpectedly (an OOM, a script reaching
+ * `process.exit` through the documented vm escape) settles the run
+ * `stopReason: 'error'` with the exit diagnostics.
+ *
+ * Plugin export shape: a default-exported {@link WorkflowService} subclass
+ * (the class-based service form, like `dsh-bash-local`).
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread
+ */
+
+import { randomUUID } from 'node:crypto'
+import { availableParallelism } from 'node:os'
+import * as vm from 'node:vm'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import WorkflowService, { WorkflowError, WorkflowRunId } from '@deepseek-ai/dsh-workflow'
+import type { WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow'
+import { WorkerRun } from './host.ts'
+import { validateMeta } from './meta.ts'
+import type { WorkerInit, WorkerLimits } from './types.ts'
+
+export { validateMeta } from './meta.ts'
+export { HostToWorkerType, WorkerToHostType } from './protocol.ts'
+export type { HostToWorkerMessage, HostToWorkerPayloads, WorkerToHostMessage, WorkerToHostPayloads } from './protocol.ts'
+export { materializeFromRealm, MaterializeError } from './realm.ts'
+export { WorkflowExecution, type ExecutionObserver } from './runtime.ts'
+export { requireParentPort, runWorkerSession } from './session.ts'
+export type {
+  ChildHandle,
+  ChildPort,
+  ChildResult,
+  ChildStartRequest,
+  WorkerInit,
+  WorkerLimits,
+} from './types.ts'
+
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /** The `ctx.subagents` provider children run on (default `spawn`). */
+  provider?: string
+  /** Concurrent `agent()` ceiling; `0` (the default) auto-resolves to `min(16, max(1, cores - 2))`. */
+  maxConcurrentAgents?: number
+  /** Total `agent()` calls one run may start — the runaway-loop backstop (default 1000). */
+  maxTotalAgents?: number
+  /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */
+  maxItemsPerCall?: number
+  /** vm timeout for the script's initial synchronous slice, inside the worker (default 5000 ms). */
+  syncTimeoutMs?: number
+  /**
+   * How long after a cancellation an unsettled script may keep running before
+   * the run force-settles `cancelled` and its worker is TERMINATED (default
+   * 5000 ms); also bounds `dispose()`.
+   */
+  disposeGraceMs?: number
+}
+
+type ResolvedConfig = Required<Config>
+
+/** A body that still carries the Claude Code-style meta header (meta rides the seam as data here). */
+const META_STATEMENT = /^\s*export\s+const\s+meta\b/
+
+/**
+ * Parse-check the body with the SAME wrapper the worker-side runtime
+ * compiles, so `start()` keeps the seam's synchronous `SCRIPT_PARSE` throw
+ * (the worker's own compile happens a thread away, after `start()` returned).
+ * One redundant parse per run, bought deliberately for the contract. A body
+ * opening with `export const meta` gets a pointed message instead of the
+ * wrapper's bare SyntaxError — the model's likeliest authoring slip.
+ */
+function assertBodyParses(body: string, name: string): void {
+  if (META_STATEMENT.test(body)) {
+    throw new WorkflowError('workflow meta rides the `meta` request field, not the script: remove the `export const meta = {...}` statement from the body', 'SCRIPT_PARSE')
+  }
+  try {
+    // Parse only — the script object is discarded, nothing executes.
+    void new vm.Script(`(async () => {\n${body}\n})()`, { filename: `workflow:${name}`, lineOffset: -1 })
+  } catch (error: unknown) {
+    throw new WorkflowError(`workflow script does not parse: ${String(error)}`, 'SCRIPT_PARSE', { cause: error })
+  }
+}
+
+/**
+ * The worker-thread engine service. `start()` validates the script up front
+ * (meta + a host-side body parse) and returns a {@link WorkflowRun} whose
+ * `result` never rejects; the `workflow/*` events fire around the run per
+ * the seam contract.
+ */
+export class WorkerWorkflowEngine extends WorkflowService {
+  static inject = ['subagents']
+
+  static Config: z<Config> = z.object({
+    provider: z.string().default('spawn'),
+    maxConcurrentAgents: z.natural().default(0),
+    maxTotalAgents: z.natural().min(1).default(1000),
+    maxItemsPerCall: z.natural().min(1).default(4096),
+    syncTimeoutMs: z.natural().min(1).default(5000),
+    disposeGraceMs: z.natural().default(5000),
+  })
+
+  private readonly config: ResolvedConfig
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx)
+    // schemastery (static Config) has already filled the defaulted fields;
+    // the assertion records that resolution, not a hidden fallback.
+    this.config = config as ResolvedConfig
+  }
+
+  /**
+   * Validate and execute a workflow script in a fresh worker thread. Throws
+   * {@link WorkflowError} synchronously (`META_INVALID` for a malformed meta
+   * block, `SCRIPT_PARSE` for a body that does not compile) for a request
+   * that cannot begin; once a run is returned, every failure resolves through
+   * `result.stopReason` instead.
+   * @param request - the script body, its meta data and `args`, the parent
+   *   agent, and an optional cancel signal.
+   * @returns the live run (its `result` resolves when the script settles).
+   */
+  start(request: WorkflowStartRequest): WorkflowRun {
+    const meta = validateMeta(request.meta)
+    assertBodyParses(request.script, meta.name)
+    const id = WorkflowRunId(randomUUID())
+    // The event payloads and the run handle get SEPARATE meta clones: a
+    // listener mutating its snapshot must not corrupt the holder's view.
+    const info: WorkflowRunInfo = { id, meta: structuredClone(meta) }
+    const limits: WorkerLimits = {
+      maxConcurrentAgents: this.config.maxConcurrentAgents === 0
+        ? Math.min(16, Math.max(1, availableParallelism() - 2))
+        : this.config.maxConcurrentAgents,
+      maxTotalAgents: this.config.maxTotalAgents,
+      maxItemsPerCall: this.config.maxItemsPerCall,
+      syncTimeoutMs: this.config.syncTimeoutMs,
+    }
+    const init: WorkerInit = {
+      meta,
+      body: request.script,
+      ...request.args !== undefined ? { args: request.args } : {},
+      limits,
+    }
+    const workerRun = new WorkerRun(
+      this.ctx,
+      id,
+      structuredClone(meta),
+      request.parent,
+      init,
+      this.config.provider,
+      this.config.disposeGraceMs,
+      {
+        phase: (title) => { this.emitWorkflowEvent('workflow/phase', info, title) },
+        log: (message) => { this.emitWorkflowEvent('workflow/log', info, message) },
+        agentStart: (agent) => { this.emitWorkflowEvent('workflow/agent-start', info, agent) },
+        agentEnd: (agent) => { this.emitWorkflowEvent('workflow/agent-end', info, agent) },
+      },
+      request.signal,
+    )
+
+    this.emitWorkflowEvent('workflow/start', info)
+    // `workflow/end` fires as the (never-rejecting) result settles, with the
+    // outcome DATA only — the value stays with the run's holder.
+    void workerRun.result.then((settled) => {
+      this.emitWorkflowEvent('workflow/end', info, {
+        stopReason: settled.stopReason,
+        ...settled.error !== undefined ? { error: settled.error } : {},
+        agentsStarted: settled.agentsStarted,
+      })
+    })
+
+    return workerRun
+  }
+}
+
+export default WorkerWorkflowEngine

packages/workflow/workflow-workerthread/src/meta.ts

@@ -0,0 +1,85 @@
+/**
+ * Meta validation: check the caller-provided {@link WorkflowMeta} DATA against
+ * the shape contract and reject everything else loud, every violation named.
+ * Meta arrives as plain JSON through the seam (the model-facing tool carries
+ * it as a schema-validated object parameter) — the engine never evaluates
+ * script text to obtain it, so no script-controlled code can run on the host
+ * here (an evaluated meta literal could smuggle getters that spin the host
+ * outside any vm timeout, the exact escape the worker thread exists to
+ * prevent).
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/meta
+ */
+
+import { WorkflowError } from '@deepseek-ai/dsh-workflow'
+import type { WorkflowMeta, WorkflowPhase } from '@deepseek-ai/dsh-workflow'
+
+/** Collect shape violations for a meta value (plain JSON data by the seam contract). */
+function validateMetaShape(meta: unknown): { meta?: WorkflowMeta; violations: string[] } {
+  const violations: string[] = []
+  if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) {
+    return { violations: ['meta must be an object'] }
+  }
+  const record = meta as Record<string, unknown>
+  const known = new Set(['name', 'description', 'whenToUse', 'phases'])
+  for (const key of Object.keys(record)) {
+    if (!known.has(key)) violations.push(`meta.${key} is not a recognized field (name/description/whenToUse/phases)`)
+  }
+  if (typeof record.name !== 'string' || record.name.length === 0) violations.push('meta.name must be a non-empty string')
+  if (typeof record.description !== 'string' || record.description.length === 0) violations.push('meta.description must be a non-empty string')
+  if (record.whenToUse !== undefined && typeof record.whenToUse !== 'string') violations.push('meta.whenToUse must be a string')
+  const phases: WorkflowPhase[] = []
+  if (record.phases !== undefined) {
+    if (!Array.isArray(record.phases)) {
+      violations.push('meta.phases must be an array')
+    } else {
+      record.phases.forEach((phase, index) => {
+        if (typeof phase !== 'object' || phase === null || Array.isArray(phase)) {
+          violations.push(`meta.phases[${index}] must be an object`)
+          return
+        }
+        const entry = phase as Record<string, unknown>
+        for (const key of Object.keys(entry)) {
+          if (!['title', 'detail', 'model'].includes(key)) violations.push(`meta.phases[${index}].${key} is not a recognized field`)
+        }
+        if (typeof entry.title !== 'string' || entry.title.length === 0) violations.push(`meta.phases[${index}].title must be a non-empty string`)
+        if (entry.detail !== undefined && typeof entry.detail !== 'string') violations.push(`meta.phases[${index}].detail must be a string`)
+        if (entry.model !== undefined && typeof entry.model !== 'string') violations.push(`meta.phases[${index}].model must be a string`)
+        if (violations.length === 0) {
+          phases.push({
+            title: entry.title as string,
+            ...entry.detail !== undefined ? { detail: entry.detail as string } : {},
+            ...entry.model !== undefined ? { model: entry.model as string } : {},
+          })
+        }
+      })
+    }
+  }
+  if (violations.length > 0) return { violations }
+  return {
+    violations,
+    meta: {
+      name: record.name as string,
+      description: record.description as string,
+      ...record.whenToUse !== undefined ? { whenToUse: record.whenToUse as string } : {},
+      ...record.phases !== undefined ? { phases } : {},
+    },
+  }
+}
+
+/**
+ * Validate a caller-provided meta value against the {@link WorkflowMeta}
+ * contract. Throws `META_INVALID` naming every violation (unknown fields,
+ * missing/mistyped `name`/`description`, malformed `phases`); the returned
+ * meta is a NORMALIZED copy built from the validated fields, so the engine
+ * never aliases the caller's object.
+ * @param value - the meta data from the start request (plain JSON by the seam contract).
+ * @returns the validated, normalized meta block.
+ */
+export function validateMeta(value: unknown): WorkflowMeta {
+  const { meta, violations } = validateMetaShape(value)
+  if (meta === undefined) {
+    throw new WorkflowError(`invalid meta: ${violations.join('; ')}`, 'META_INVALID')
+  }
+  return meta
+}

packages/workflow/workflow-workerthread/src/protocol.ts

@@ -0,0 +1,115 @@
+/**
+ * The host⇄worker wire protocol: one string-valued enum of message tags per
+ * direction, a payload map giving each tag its parameters (the single source
+ * of truth), and the message unions derived from them. Everything in a
+ * payload is plain JSON data by construction (the runtime materializes
+ * script values before they reach a message; the host projects seam results
+ * down to their JSON fields), so the structured-clone hop never meets a
+ * value it cannot carry.
+ *
+ * Both directions are CLOSED (engine-owned): each side switches on `type`
+ * and ends with `assertNever` — an unknown message is a protocol bug, never
+ * something to skip silently. Senders go through a generic
+ * `post(type, payload)` whose payload parameter is looked up from the map,
+ * so a tag/payload mismatch is a compile error at the call site.
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/protocol
+ */
+
+import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowResult } from '@deepseek-ai/dsh-workflow'
+import type { ChildResult, ChildStartRequest } from './types.ts'
+
+/** Message tags the worker sends the host (the wire values are the tag strings). */
+export enum WorkerToHostType {
+  /** The startup handshake: the session is listening and awaits {@link HostToWorkerType.Go}. */
+  Ready = 'ready',
+  /** Observer narration: a `phase(title)` call. */
+  Phase = 'phase',
+  /** Observer narration: a `log(message)` call. */
+  Log = 'log',
+  /** Observer lifecycle: one `agent()` call started a child. */
+  AgentStart = 'agent-start',
+  /** Observer lifecycle: one `agent()` call settled. */
+  AgentEnd = 'agent-end',
+  /** Child RPC: start a child on the host (answered by ChildStarted or ChildStartError). */
+  ChildStart = 'child-start',
+  /** Child RPC: cancel a started child (fire-and-forget). */
+  ChildCancel = 'child-cancel',
+  /** Child RPC: dispose a started child (answered by ChildDisposed). */
+  ChildDispose = 'child-dispose',
+  /** The run's single terminal result. */
+  Result = 'result',
+}
+
+/** The payload each worker→host tag carries. */
+export interface WorkerToHostPayloads {
+  /** Ready carries nothing. */
+  [WorkerToHostType.Ready]: Record<never, never>
+  /** The phase title, verbatim. */
+  [WorkerToHostType.Phase]: { title: string }
+  /** The logged message, verbatim. */
+  [WorkerToHostType.Log]: { message: string }
+  /** The call's sequence number, label, phase, and child id. */
+  [WorkerToHostType.AgentStart]: { info: WorkflowAgentInfo }
+  /** The call identity plus its outcome. */
+  [WorkerToHostType.AgentEnd]: { info: WorkflowAgentEndInfo }
+  /** The RPC correlation id and the prompt plus validated options. */
+  [WorkerToHostType.ChildStart]: { callId: number; request: ChildStartRequest }
+  /** The RPC correlation id and the cancel reason (undefined = unspecified). */
+  [WorkerToHostType.ChildCancel]: { callId: number; reason: string | undefined }
+  /** The RPC correlation id of the child to dispose. */
+  [WorkerToHostType.ChildDispose]: { callId: number }
+  /** The run's terminal outcome. */
+  [WorkerToHostType.Result]: { result: WorkflowResult }
+}
+
+/** Message tags the host sends the worker (the wire values are the tag strings). */
+export enum HostToWorkerType {
+  /** Releases the startup gate: run the script body. */
+  Go = 'go',
+  /** Cancel the run: hooks start throwing and the script dies at its next await. */
+  Cancel = 'cancel',
+  /** Child RPC reply: the start succeeded (exactly one of ChildStarted/ChildStartError per ChildStart). */
+  ChildStarted = 'child-started',
+  /** Child RPC reply: the start was refused or threw. */
+  ChildStartError = 'child-start-error',
+  /** Child RPC: a started child's result RESOLVED (its JSON projection). */
+  ChildSettled = 'child-settled',
+  /** Child RPC: a started child's result REJECTED (an infrastructure fault, rendered). */
+  ChildFailed = 'child-failed',
+  /** Child RPC reply: a requested disposal completed. */
+  ChildDisposed = 'child-disposed',
+}
+
+/** The payload each host→worker tag carries. */
+export interface HostToWorkerPayloads {
+  /** Go carries nothing. */
+  [HostToWorkerType.Go]: Record<never, never>
+  /** The cancel reason, canonical for the whole run. */
+  [HostToWorkerType.Cancel]: { reason: string }
+  /** The RPC correlation id and the child agent's id (minted by the subagent seam). */
+  [HostToWorkerType.ChildStarted]: { callId: number; childId: string }
+  /** The RPC correlation id and the rendered start failure. */
+  [HostToWorkerType.ChildStartError]: { callId: number; rendered: string }
+  /** The RPC correlation id and the child's terminal result projection. */
+  [HostToWorkerType.ChildSettled]: { callId: number; result: ChildResult }
+  /** The RPC correlation id and the rendered infrastructure fault. */
+  [HostToWorkerType.ChildFailed]: { callId: number; rendered: string }
+  /** The RPC correlation id of the completed disposal. */
+  [HostToWorkerType.ChildDisposed]: { callId: number }
+}
+
+/**
+ * One worker→host message of tag `T`; unparameterized, the closed union over
+ * every tag (a discriminated union — `switch` on `type` narrows).
+ */
+export type WorkerToHostMessage<T extends WorkerToHostType = WorkerToHostType> =
+  { [K in T]: { type: K } & WorkerToHostPayloads[K] }[T]
+
+/**
+ * One host→worker message of tag `T`; unparameterized, the closed union over
+ * every tag (a discriminated union — `switch` on `type` narrows).
+ */
+export type HostToWorkerMessage<T extends HostToWorkerType = HostToWorkerType> =
+  { [K in T]: { type: K } & HostToWorkerPayloads[K] }[T]
+

packages/workflow/workflow-workerthread/src/realm.ts

@@ -0,0 +1,174 @@
+/**
+ * The engine's value boundary: copy script-realm values into plain JSON data
+ * — loud about everything JSON cannot carry — and render thrown script
+ * values to failure text. The script runs in a vm context INSIDE the worker
+ * thread, so "host" here means the worker-side JavaScript around that
+ * context; everything that later crosses the thread boundary is JSON by this
+ * walk, which is what makes the postMessage hop total.
+ *
+ * TRUST PREMISE (everything in this module hangs on it): workflow scripts are
+ * MODEL-WRITTEN, the same trust level as the model's existing bash access, so
+ * this boundary guards against BUGGY scripts, not hostile ones. It rejects
+ * loud what JSON would silently mangle — functions, symbols, bigints,
+ * non-finite numbers, nested `undefined`, cycles, sparse arrays, exotic
+ * prototypes — because accepted-then-ignored is this repo's banned failure
+ * mode. It does NOT defend against adversarial values: the walk reads
+ * properties ordinarily (a getter runs, and whatever it returns is what
+ * crosses), {@link renderThrown} reads `stack`/`message`/`String()` directly,
+ * and a proxy is walked through its traps. A hostile script gains nothing
+ * worth defending here — the vm context inside the worker is escapable by
+ * construction, so hostile-value containment would be cost without a threat
+ * model (what the worker thread DOES buy is that a spin occupies the
+ * worker's loop, not the host's, and termination is real).
+ *
+ * The host→realm direction needs no machinery at all: hooks hand the script
+ * plain values of the worker realm, prototypes included — the script is
+ * trusted. One consequence is documented in the engine README: an error
+ * thrown by a hook is built OUTSIDE the script's vm context, so an in-script
+ * `instanceof Error` check is false; read `name`/`code`/`message` instead.
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/realm
+ */
+
+/** Thrown by {@link materializeFromRealm}; the caller wraps it into the right `WorkflowError` code. */
+export class MaterializeError extends Error {
+  constructor(public readonly path: string, public readonly reason: string) {
+    super(`${path}: ${reason}`)
+    this.name = 'MaterializeError'
+  }
+}
+
+/**
+ * Render a thrown value to failure text without ever throwing: prefer the
+ * `stack` (host or realm — a realm error's `stack` is a plain string read),
+ * fall back to `message`, then `String()`. Reading those properties MAY run
+ * script code (a getter, `toString`) — accepted under the module's trust
+ * premise; if that code itself throws, a fixed label is returned instead.
+ * @param error - the thrown value, of any shape and any realm.
+ * @returns human-readable text for the failure report; prefers the stack.
+ */
+export function renderThrown(error: unknown): string {
+  try {
+    const stack = (error as { stack?: unknown } | null | undefined)?.stack
+    if (typeof stack === 'string' && stack.length > 0) return stack
+    const message = (error as { message?: unknown } | null | undefined)?.message
+    if (typeof message === 'string' && message.length > 0) return message
+    return String(error)
+  } catch {
+    // A throwing accessor/toString on the thrown value — rendering must be
+    // total (drive()'s never-reject contract), so fall back to a fixed label.
+    return '[unrenderable thrown value]'
+  }
+}
+
+/**
+ * Whether an object's prototype chain is data-shaped: `null`, or a prototype
+ * whose own prototype is `null` (the realm's `Object.prototype` — which we
+ * cannot compare by identity across realms). A `Date`/`Map`/class instance
+ * has a longer chain and is rejected.
+ */
+function hasPlainPrototype(value: object): boolean {
+  const proto: unknown = Object.getPrototypeOf(value)
+  if (proto === null) return true
+  return Object.getPrototypeOf(proto) === null
+}
+
+/**
+ * Copy `value` (typically from the vm realm) into plain host JSON data.
+ * Throws {@link MaterializeError} naming the offending path for anything JSON
+ * cannot carry losslessly. Properties are read ordinarily — a getter runs and
+ * its RESULT is materialized; a read that throws surfaces as a
+ * {@link MaterializeError} carrying the rendered failure. `undefined` is
+ * accepted only at the ROOT (a script with no `return` value) — the caller
+ * decides what it means; an `undefined` nested INSIDE a container is a
+ * violation.
+ * @param value - the realm value to materialize.
+ * @param root - the path label for the root value (error messages).
+ * @returns the host-realm copy (plain objects/arrays/scalars only).
+ */
+export function materializeFromRealm(value: unknown, root = 'value'): unknown {
+  if (value === undefined) return undefined
+  try {
+    return materialize(value, root, new Set())
+  } catch (error: unknown) {
+    if (error instanceof MaterializeError) throw error
+    // A property read ran script code that threw; total-ize it so callers can
+    // keep the narrow MaterializeError contract.
+    throw new MaterializeError(root, `reading the value threw: ${renderThrown(error)}`)
+  }
+}
+
+function materialize(value: unknown, path: string, seen: Set<object>): unknown {
+  switch (typeof value) {
+    case 'boolean':
+    case 'string':
+      return value
+    case 'number': {
+      if (!Number.isFinite(value)) throw new MaterializeError(path, 'non-finite numbers are not JSON data')
+      return value
+    }
+    case 'bigint':
+      throw new MaterializeError(path, 'bigints are not JSON data')
+    case 'function':
+      throw new MaterializeError(path, 'functions cannot cross the workflow value boundary')
+    case 'symbol':
+      throw new MaterializeError(path, 'symbols cannot cross the workflow value boundary')
+    case 'undefined':
+      throw new MaterializeError(path, 'undefined is not JSON data')
+    case 'object':
+      break
+  }
+  if (value === null) return null
+  const objectValue: object = value
+  if (seen.has(objectValue)) throw new MaterializeError(path, 'circular references are not JSON data')
+  seen.add(objectValue)
+  try {
+    if (Array.isArray(objectValue)) return materializeArray(objectValue, path, seen)
+    return materializeObject(objectValue, path, seen)
+  } finally {
+    seen.delete(objectValue)
+  }
+}
+
+function materializeArray(value: unknown[], path: string, seen: Set<object>): unknown[] {
+  const out: unknown[] = []
+  for (let index = 0; index < value.length; index++) {
+    if (!(index in value)) throw new MaterializeError(`${path}[${index}]`, 'sparse arrays are not JSON data')
+    out.push(materialize(value[index], `${path}[${index}]`, seen))
+  }
+  // Own enumerable props beyond the indices (e.g. `arr.total = 3`) would be
+  // silently dropped by JSON — reject them instead.
+  for (const key of Object.keys(value)) {
+    const index = Number(key)
+    if (!Number.isInteger(index) || index < 0 || index >= value.length) {
+      throw new MaterializeError(`${path}.${key}`, 'arrays with non-index properties are not JSON data')
+    }
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow value boundary')
+  }
+  return out
+}
+
+function materializeObject(value: object, path: string, seen: Set<object>): Record<string, unknown> {
+  if (!hasPlainPrototype(value)) {
+    throw new MaterializeError(path, 'only plain objects and arrays are JSON data (exotic prototype)')
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow value boundary')
+  }
+  const out: Record<string, unknown> = {}
+  // Object.keys = own enumerable string keys, matching JSON.stringify's
+  // property selection exactly (non-enumerable props never reach JSON output).
+  for (const key of Object.keys(value)) {
+    // defineProperty, never assignment: a "__proto__" key must become an OWN
+    // data property of the copy, not a prototype mutation.
+    Object.defineProperty(out, key, {
+      value: materialize((value as Record<string, unknown>)[key], `${path}.${key}`, seen),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    })
+  }
+  return out
+}

packages/workflow/workflow-workerthread/src/runtime.ts

@@ -0,0 +1,522 @@
+/**
+ * Per-run execution state for the engine's THREAD side: the script's vm
+ * context and its injected hooks (`agent`/`parallel`/`pipeline`/`phase`/
+ * `log`/`args`), the concurrency semaphore and caps, cancellation, and the
+ * drive loop that turns a script settlement into a {@link WorkflowResult}.
+ * Children are started by RPC to the host through a {@link ChildPort}, so
+ * this module never touches a cordis context — it runs inside the worker
+ * thread.
+ *
+ * Value boundary (the trust premise lives in ./realm.ts): values ENTERING the
+ * worker-side host code from the script (hook options, schemas, the return
+ * value) are materialized by `materializeFromRealm` — a plain walk that
+ * rejects loud everything JSON cannot carry, which also makes every value
+ * safe for the later postMessage hop. Values ENTERING the realm (`args`,
+ * `agent()` results, hook promises and their failures, combinator arrays) are
+ * handed over DIRECTLY as worker-realm values: the script is model-written
+ * and trusted, so outer prototypes are not a leak. `args` is cloned once at
+ * start so a script scribbling on it cannot mutate the session's init object
+ * (a benign-bug guard; the postMessage clone already isolated the caller).
+ *
+ * Failure discipline: fatal {@link WorkflowError}s (bad hook arguments,
+ * unsupported options/schemas, tripped caps, host start refusals and child
+ * result rejections, cancellation) ALWAYS propagate through
+ * `parallel`/`pipeline` — recognized by `instanceof` against this realm's
+ * class, which a script inside the vm context cannot forge — and the per-item
+ * `null` is reserved for child-run failures and ordinary in-stage script
+ * errors. Every hook-returned promise gets a no-op rejection consumer, so a
+ * dropped promise cannot surface an unhandled rejection (which would kill the
+ * worker and read as an engine fault).
+ *
+ * There is deliberately NO worker-side abandon channel: a script that never
+ * settles after a cancel simply never posts a result, and the HOST enforces
+ * the settles-within-grace guarantee by force-settling `cancelled` and
+ * terminating the worker — the real kill an in-process engine could not have.
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/runtime
+ */
+
+import * as vm from 'node:vm'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { assertSupportedOutputSchema, OutputSchemaError } from '@deepseek-ai/dsh-tools'
+import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools'
+import { isFatalWorkflowError, WorkflowError } from '@deepseek-ai/dsh-workflow'
+import type {
+  WorkflowAgentEndInfo,
+  WorkflowAgentInfo,
+  WorkflowMeta,
+  WorkflowResult,
+} from '@deepseek-ai/dsh-workflow'
+import { materializeFromRealm, MaterializeError, renderThrown } from './realm.ts'
+import type { ChildHandle, ChildPort, WorkerLimits } from './types.ts'
+
+/** The observers the execution reports progress through (the session posts them to the host). */
+export interface ExecutionObserver {
+  phase(title: string): void
+  log(message: string): void
+  agentStart(info: WorkflowAgentInfo): void
+  agentEnd(info: WorkflowAgentEndInfo): void
+}
+
+/** The `agent()` options the script may pass; everything else rejects loud. */
+const SUPPORTED_AGENT_OPTIONS = new Set(['label', 'phase', 'schema', 'model'])
+/** Deferred Claude Code options we name explicitly in the rejection message. */
+const DEFERRED_AGENT_OPTIONS = new Set(['effort', 'isolation', 'agentType'])
+
+/** Flatten a child's final output blocks to text (the non-schema `agent()` result). */
+function outputText(blocks: ContentBlock[]): string {
+  return blocks
+    .filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text')
+    .map(block => block.text)
+    .join('')
+}
+
+/** A short display label derived from the prompt when the script passes none. */
+function defaultLabel(prompt: string): string {
+  const newline = prompt.indexOf('\n')
+  const line = newline === -1 ? prompt : prompt.slice(0, newline)
+  return line.length <= 48 ? line : `${line.slice(0, 47)}…`
+}
+
+/**
+ * One live script execution inside the worker. Constructed per run by the
+ * session; `drive()` is called exactly once and NEVER rejects — every failure
+ * becomes a {@link WorkflowResult} with a non-`completed` stop reason.
+ */
+export class WorkflowExecution {
+  /** 1-based count of `agent()` calls started (the `agentsStarted` result field). */
+  private started = 0
+  private activeSlots = 0
+  private readonly slotWaiters: { resolve(): void; reject(error: unknown): void }[] = []
+  private cancelReason: string | undefined
+  private cancelError: WorkflowError | undefined
+  private readonly controller = new AbortController()
+  private currentPhase: string | undefined
+  private readonly context: vm.Context
+  private readonly compiled: vm.Script
+
+  constructor(
+    meta: WorkflowMeta,
+    body: string,
+    args: unknown,
+    private readonly limits: WorkerLimits,
+    private readonly observer: ExecutionObserver,
+    private readonly children: ChildPort,
+  ) {
+    // Compile FIRST: a body syntax error must throw out of the constructor
+    // before any realm state exists. The host pre-parses the identical
+    // wrapper, so under one Node version this throw is unreachable in
+    // production — the session still maps it to an error result defensively.
+    // lineOffset compensates for the wrapper line, so stack traces carry the
+    // script's own line numbers.
+    try {
+      this.compiled = new vm.Script(`(async () => {\n${body}\n})()`, {
+        filename: `workflow:${meta.name}`,
+        lineOffset: -1,
+      })
+    } catch (error: unknown) {
+      throw new WorkflowError(`workflow script does not parse: ${String(error)}`, 'SCRIPT_PARSE', { cause: error })
+    }
+
+    this.context = vm.createContext({}, { name: `workflow:${meta.name}` })
+
+    const globals: Record<string, unknown> = {
+      agent: (prompt: unknown, opts?: unknown) => this.contain(this.agent(prompt, opts)),
+      parallel: (thunks: unknown) => this.contain(this.parallel(thunks)),
+      pipeline: (items: unknown, ...stages: unknown[]) => this.contain(this.pipeline(items, stages)),
+      phase: (title: unknown) => { this.phase(title) },
+      log: (message: unknown) => { this.log(message) },
+      // Cloned once: a script scribbling on args must not mutate the
+      // session's init object (a benign-bug guard; args is plain JSON by the
+      // seam contract and already crossed one structured clone as workerData,
+      // so this clone is total).
+      args: args === undefined ? undefined : structuredClone(args),
+    }
+    for (const [key, value] of Object.entries(globals)) {
+      // Data properties on the contextified global; frozen shape not required —
+      // a script overwriting its own hooks only sabotages itself.
+      ;(this.context as Record<string, unknown>)[key] = typeof value === 'function' ? Object.freeze(value) : value
+    }
+  }
+
+  /**
+   * Whether the run has been cancelled. A METHOD, not an inline property
+   * read: `cancel()` mutates `cancelReason` concurrently (the session's
+   * message handler), and an inline read after an `await` gets narrowed by
+   * control flow into an always-false comparison.
+   */
+  private isCancelled(): boolean {
+    return this.cancelReason !== undefined
+  }
+
+  /**
+   * Shared hook entry guard: after {@link cancel}, EVERY hook throws
+   * `CANCELLED` at its next call — cancellation is the next HOOK boundary,
+   * not just the next `agent()`, so a script that caught one cancelled
+   * rejection cannot keep emitting progress through `phase`/`log` or enter a
+   * combinator.
+   */
+  private throwIfCancelled(): void {
+    if (this.isCancelled()) throw this.cancelledError()
+  }
+
+  /**
+   * Cancel the run: in-flight children get a cancel RPC (the shared abort
+   * fanout), waiting `agent()` slots reject, and every future hook call
+   * throws `CANCELLED` — the script dies at its next await. A script that
+   * never settles anyway (parked on a promise no hook owns) is the HOST's
+   * problem: its grace timer force-settles the run and terminates the
+   * worker. Idempotent; the first reason wins.
+   * @param reason - human-readable cause, carried on the CANCELLED error and
+   * into child cancel RPCs. Required: every caller (the session's cancel
+   * message, drive()'s settle-reap) has a concrete reason.
+   */
+  cancel(reason: string): void {
+    if (this.cancelReason !== undefined) return
+    this.cancelReason = reason
+    this.cancelError = new WorkflowError(`workflow run cancelled: ${this.cancelReason}`, 'CANCELLED')
+    this.controller.abort(this.cancelReason)
+    for (const waiter of this.slotWaiters.splice(0)) waiter.reject(this.cancelledError())
+  }
+
+  /**
+   * Run the script to settlement. Resolves — never rejects — with the run's
+   * {@link WorkflowResult}: the materialized return value on `completed`, the
+   * failure message on `error`, and `cancelled` when the script died of
+   * cancellation. After settlement, any stray children a script fired without
+   * awaiting are cancelled (their `agent()` wrappers dispose them via RPC).
+   * @returns the settled outcome — this promise NEVER rejects (the seam's
+   * `result`-never-rejects contract); every failure maps to a variant.
+   */
+  async drive(): Promise<WorkflowResult> {
+    try {
+      // Cancelled before the body ever ran (an already-aborted start signal,
+      // relayed by the host before its `go`): the script must not execute at
+      // all, let alone report `completed`.
+      if (this.isCancelled()) throw this.cancelledError()
+      const scriptPromise = this.compiled.runInContext(this.context, { timeout: this.limits.syncTimeoutMs }) as Promise<unknown>
+      const raw: unknown = await this.contain(Promise.resolve(scriptPromise))
+      // Cancelled while the body ran: a script that settled without touching
+      // another hook (or without any) must still report `cancelled` — the
+      // holder asked for cancellation and `completed` would be a lie.
+      if (this.isCancelled()) throw this.cancelledError()
+      const value = raw === undefined ? null : this.materializeResult(raw)
+      return { value, stopReason: 'completed', agentsStarted: this.started }
+    } catch (error: unknown) {
+      // Any failure after cancel() reports `cancelled` with the canonical
+      // reason — the reject path mirrors the resolve path's post-settle check.
+      if (this.isCancelled()) {
+        return { value: null, stopReason: 'cancelled', error: this.cancelledError().message, agentsStarted: this.started }
+      }
+      // renderThrown is total (thrown values of any realm), so this arm
+      // cannot throw — drive() resolving is the `result` never-rejects seam
+      // contract.
+      return { value: null, stopReason: 'error', error: renderThrown(error), agentsStarted: this.started }
+    } finally {
+      // Reap strays: a script that fired agent() calls without awaiting them
+      // leaves live children behind after settlement — cancel them all. (The
+      // per-call wrappers dispose each child; the contain() consumer keeps
+      // their rejections from going unhandled.)
+      if (this.cancelReason === undefined) this.cancel('workflow settled')
+    }
+  }
+
+  /**
+   * Attach a no-op rejection consumer WITHOUT changing what the caller
+   * receives: if the script drops the promise (no await), cancellation cannot
+   * become an unhandled rejection (which would kill the worker thread); if
+   * the script does await it, it still observes the rejection.
+   */
+  private contain<T>(promise: Promise<T>): Promise<T> {
+    promise.catch(() => { /* consumed: see method contract — a dropped hook promise must not surface an unhandled rejection */ })
+    return promise
+  }
+
+  private cancelledError(): WorkflowError {
+    // cancel() arms cancelError before any caller can observe isCancelled()
+    // === true; the fallback guards the type, not a reachable path.
+    /* v8 ignore next */
+    return this.cancelError ?? new WorkflowError('workflow run cancelled', 'CANCELLED')
+  }
+
+  /** Materialize the script's return value; violations become RESULT_UNSERIALIZABLE. */
+  private materializeResult(raw: unknown): unknown {
+    try {
+      return materializeFromRealm(raw, 'workflow result')
+    } catch (error: unknown) {
+      /* v8 ignore next -- defensive rethrow arm: materializeFromRealm only throws MaterializeError */
+      if (!(error instanceof MaterializeError)) throw error
+      throw new WorkflowError(
+        `the workflow's return value is not plain JSON data — ${error.message}. Return only JSON-serializable objects/arrays/scalars.`,
+        'RESULT_UNSERIALIZABLE',
+        { cause: error },
+      )
+    }
+  }
+
+  /**
+   * Acquire one concurrency slot (FIFO). Cancellation rejects QUEUED waiters
+   * (see {@link cancel}); the callers guard their own entry and post-acquire
+   * windows, so no cancelled-precheck is duplicated here.
+   */
+  private acquireSlot(): Promise<void> {
+    if (this.activeSlots < this.limits.maxConcurrentAgents) {
+      this.activeSlots += 1
+      return Promise.resolve()
+    }
+    return new Promise<void>((resolve, reject) => {
+      this.slotWaiters.push({
+        resolve: () => {
+          this.activeSlots += 1
+          resolve()
+        },
+        reject,
+      })
+    })
+  }
+
+  private releaseSlot(): void {
+    this.activeSlots -= 1
+    const next = this.slotWaiters.shift()
+    if (next) next.resolve()
+  }
+
+  /** The `agent(prompt, opts)` hook. */
+  private async agent(rawPrompt: unknown, rawOpts: unknown): Promise<unknown> {
+    this.throwIfCancelled()
+    if (typeof rawPrompt !== 'string' || rawPrompt.length === 0) {
+      throw new WorkflowError('agent() requires a non-empty prompt string', 'INVALID_ARGUMENT')
+    }
+    const opts = this.readAgentOptions(rawOpts)
+    if (this.started >= this.limits.maxTotalAgents) {
+      throw new WorkflowError(
+        `this run reached its total agent cap (${this.limits.maxTotalAgents}) — a runaway-loop backstop; raise maxTotalAgents in the engine config if the scale is intentional`,
+        'AGENT_CAP',
+      )
+    }
+    this.started += 1
+    const seq = this.started
+    const label = opts.label ?? defaultLabel(rawPrompt)
+    const phase = opts.phase ?? this.currentPhase
+
+    await this.acquireSlot()
+    try {
+      // Re-check after the acquire: the await yields at least one microtask
+      // tick even when a slot is free, and a queued waiter resumes a tick
+      // after its release — a cancel() landing in either window must not
+      // reach the host (which would refuse anyway, but the refusal reads as
+      // a start failure rather than the cancellation it is).
+      this.throwIfCancelled()
+      let run: ChildHandle
+      try {
+        run = await this.children.startAgent({
+          prompt: rawPrompt,
+          ...opts.schema !== undefined ? { schema: opts.schema } : {},
+          ...opts.model !== undefined ? { model: opts.model } : {},
+        })
+      } catch (error: unknown) {
+        // The host refuses starts once the run is cancelled — a refusal that
+        // races our own cancel state must read as the cancellation it is,
+        // not as a broken seam.
+        if (this.isCancelled()) throw this.cancelledError()
+        throw new WorkflowError(`agent() could not start a child: ${renderThrown(error)}`, 'AGENT_START', { cause: error })
+      }
+      // The start round-trip yields to the event loop, so a cancel CAN land
+      // between the host starting the child and this continuation running —
+      // wind the fresh child down instead of leaving it live behind a dead
+      // script.
+      if (this.isCancelled()) {
+        run.cancel(this.cancelReason)
+        await run.dispose()
+        throw this.cancelledError()
+      }
+      const info: WorkflowAgentInfo = { seq, label, ...phase !== undefined ? { phase } : {}, childId: AgentId(run.id) }
+      this.observer.agentStart(info)
+      // Cancellation reaches the child through an explicit cancel RPC per
+      // child (the host also aborts its own per-run signal, but the seam
+      // leaves a provider free to honor either channel, so both are driven).
+      const onAbort = (): void => { run.cancel(this.cancelReason) }
+      this.controller.signal.addEventListener('abort', onAbort, { once: true })
+      try {
+        let result
+        try {
+          result = await run.result
+        } catch (error: unknown) {
+          // A rejected child result is an INFRASTRUCTURE fault relayed by the
+          // host — distinct from a child that failed and resolved. Pair the
+          // lifecycle before propagating, and propagate FATAL: an ordinary
+          // throw would dissolve to a per-item null inside the combinators,
+          // and a broken provider must not read as a failed child.
+          if (this.isCancelled()) {
+            this.observer.agentEnd({ ...info, outcome: 'cancelled' })
+            throw this.cancelledError()
+          }
+          this.observer.agentEnd({ ...info, outcome: 'failed' })
+          throw new WorkflowError(`child agent run failed: ${renderThrown(error)}`, 'AGENT_RESULT', { cause: error })
+        }
+        if (result.stopReason === 'completed') {
+          if (opts.schema !== undefined) {
+            // The provider honored outputSchema (capability-gated at start), so
+            // a completed run without a structured value is a child failure.
+            if (result.structured === undefined) {
+              this.observer.agentEnd({ ...info, outcome: 'failed' })
+              return null
+            }
+            this.observer.agentEnd({ ...info, outcome: 'completed' })
+            return result.structured
+          }
+          this.observer.agentEnd({ ...info, outcome: 'completed' })
+          return outputText(result.output)
+        }
+        // A cancelled RUN kills the script; a child that failed for its own
+        // reasons resolves null (scripts .filter(Boolean) per the CC contract).
+        if (this.isCancelled()) {
+          this.observer.agentEnd({ ...info, outcome: 'cancelled' })
+          throw this.cancelledError()
+        }
+        this.observer.agentEnd({ ...info, outcome: 'failed' })
+        return null
+      } finally {
+        this.controller.signal.removeEventListener('abort', onAbort)
+        await run.dispose()
+      }
+    } finally {
+      this.releaseSlot()
+    }
+  }
+
+  /** Materialize + validate the `agent()` options bag from the realm. */
+  private readAgentOptions(rawOpts: unknown): { label?: string; phase?: string; model?: string; schema?: StructuredOutputSchema } {
+    if (rawOpts === undefined) return {}
+    let opts: unknown
+    try {
+      opts = materializeFromRealm(rawOpts, 'agent() options')
+    } catch (error: unknown) {
+      /* v8 ignore next -- defensive rethrow arm: materializeFromRealm only throws MaterializeError */
+      if (!(error instanceof MaterializeError)) throw error
+      throw new WorkflowError(`agent() options must be plain JSON data — ${error.message}`, 'INVALID_ARGUMENT', { cause: error })
+    }
+    if (typeof opts !== 'object' || opts === null || Array.isArray(opts)) {
+      throw new WorkflowError('agent() options must be an object', 'INVALID_ARGUMENT')
+    }
+    const record = opts as Record<string, unknown>
+    for (const key of Object.keys(record)) {
+      if (SUPPORTED_AGENT_OPTIONS.has(key)) continue
+      if (DEFERRED_AGENT_OPTIONS.has(key)) {
+        throw new WorkflowError(`agent() option "${key}" is deferred and not supported by this engine (supported: label, phase, schema, model)`, 'UNSUPPORTED_OPTION')
+      }
+      throw new WorkflowError(`agent() option "${key}" is not recognized (supported: label, phase, schema, model)`, 'UNSUPPORTED_OPTION')
+    }
+    for (const key of ['label', 'phase', 'model'] as const) {
+      if (record[key] !== undefined && typeof record[key] !== 'string') {
+        throw new WorkflowError(`agent() option "${key}" must be a string`, 'INVALID_ARGUMENT')
+      }
+    }
+    let schema: StructuredOutputSchema | undefined
+    if (record.schema !== undefined) {
+      try {
+        assertSupportedOutputSchema(record.schema)
+        schema = record.schema
+      } catch (error: unknown) {
+        /* v8 ignore next -- defensive rethrow arm: assertSupportedOutputSchema only throws OutputSchemaError */
+        if (!(error instanceof OutputSchemaError)) throw error
+        throw new WorkflowError(`agent() schema is outside the supported subset — ${error.message}`, 'UNSUPPORTED_SCHEMA', { cause: error })
+      }
+    }
+    return {
+      ...record.label !== undefined ? { label: record.label as string } : {},
+      ...record.phase !== undefined ? { phase: record.phase as string } : {},
+      ...record.model !== undefined ? { model: record.model as string } : {},
+      ...schema !== undefined ? { schema } : {},
+    }
+  }
+
+  /** The `parallel(thunks)` hook: each thunk caught → `null`; fatal errors propagate. */
+  private async parallel(rawThunks: unknown): Promise<unknown[]> {
+    this.throwIfCancelled()
+    if (!Array.isArray(rawThunks)) {
+      throw new WorkflowError('parallel() requires an array of zero-argument functions', 'INVALID_ARGUMENT')
+    }
+    this.assertItemCap(rawThunks.length, 'parallel()')
+    const thunks = rawThunks.map((thunk, index) => {
+      if (typeof thunk !== 'function') {
+        throw new WorkflowError(`parallel() item ${index} is not a function`, 'INVALID_ARGUMENT')
+      }
+      return thunk as () => unknown
+    })
+    return Promise.all(thunks.map(async (thunk) => {
+      try {
+        return await thunk()
+      } catch (error: unknown) {
+        // Hook failures are WorkflowErrors built OUTSIDE the script's realm;
+        // fatality is recognized by `instanceof` against this realm's class —
+        // a script-built object can never pass it, so fatality cannot be
+        // forged (nor accidentally dissolved).
+        if (isFatalWorkflowError(error)) throw error
+        return null
+      }
+    }))
+  }
+
+  /** The `pipeline(items, ...stages)` hook: per-item stage chains, NO cross-stage barrier. */
+  private async pipeline(rawItems: unknown, rawStages: unknown[]): Promise<unknown[]> {
+    this.throwIfCancelled()
+    if (!Array.isArray(rawItems)) {
+      throw new WorkflowError('pipeline() requires an items array', 'INVALID_ARGUMENT')
+    }
+    this.assertItemCap(rawItems.length, 'pipeline()')
+    if (rawStages.length === 0) {
+      throw new WorkflowError('pipeline() requires at least one stage function', 'INVALID_ARGUMENT')
+    }
+    const stages = rawStages.map((stage, index) => {
+      if (typeof stage !== 'function') {
+        throw new WorkflowError(`pipeline() stage ${index} is not a function`, 'INVALID_ARGUMENT')
+      }
+      return stage as (previous: unknown, item: unknown, index: number) => unknown
+    })
+    return Promise.all(rawItems.map(async (item: unknown, index) => {
+      let value: unknown = item
+      try {
+        for (const stage of stages) {
+          value = await stage(value, item, index)
+        }
+        return value
+      } catch (error: unknown) {
+        // An ordinary stage throw drops the ITEM to null and skips its
+        // remaining stages; a fatal WorkflowError (see parallel()) kills the
+        // whole script.
+        if (isFatalWorkflowError(error)) throw error
+        return null
+      }
+    }))
+  }
+
+  private assertItemCap(length: number, hook: string): void {
+    if (length > this.limits.maxItemsPerCall) {
+      throw new WorkflowError(
+        `${hook} received ${length} items — over the per-call cap (${this.limits.maxItemsPerCall}); split the work or raise maxItemsPerCall in the engine config`,
+        'ITEM_CAP',
+      )
+    }
+  }
+
+  /** The `phase(title)` hook: sets the current label for subsequent `agent()` calls and notifies observers. */
+  private phase(title: unknown): void {
+    this.throwIfCancelled()
+    if (typeof title !== 'string' || title.length === 0) {
+      throw new WorkflowError('phase() requires a non-empty title string', 'INVALID_ARGUMENT')
+    }
+    this.currentPhase = title
+    this.observer.phase(title)
+  }
+
+  /** The `log(message)` hook: narration to observers. */
+  private log(message: unknown): void {
+    this.throwIfCancelled()
+    if (typeof message !== 'string') {
+      throw new WorkflowError('log() requires a message string', 'INVALID_ARGUMENT')
+    }
+    this.observer.log(message)
+  }
+}

packages/workflow/workflow-workerthread/src/session.ts

@@ -0,0 +1,210 @@
+/**
+ * The worker-side half of the engine: {@link runWorkerSession} wires one
+ * MessagePort to one {@link WorkflowExecution} — hook progress and child
+ * starts go out as messages, run control and child lifecycle come back in —
+ * and posts the run's terminal result exactly once. Deliberately separated
+ * from the thread bootstrap (./worker.ts): the whole session is drivable
+ * in-process over a `MessageChannel`, which is where its unit coverage lives
+ * (code inside a real Worker is invisible to the main process's coverage).
+ *
+ * Startup handshake: the session posts `ready` and runs the script only
+ * after the host's `go` — without it, a cancellation racing the worker's
+ * boot could arrive AFTER the script's initial synchronous slice already
+ * ran, and a run cancelled before start must not execute the body at all.
+ * A `cancel` arriving instead of `go` still releases the gate: `drive()`
+ * sees the cancelled state and settles without running the body.
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/session
+ */
+
+import type { MessagePort } from 'node:worker_threads'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import { HostToWorkerType, WorkerToHostType } from './protocol.ts'
+import type { HostToWorkerMessage, WorkerToHostPayloads } from './protocol.ts'
+import { renderThrown } from './realm.ts'
+import { WorkflowExecution } from './runtime.ts'
+import type { ExecutionObserver } from './runtime.ts'
+import type {
+  ChildHandle,
+  ChildPort,
+  ChildResult,
+  ChildStartRequest,
+  WorkerInit,
+} from './types.ts'
+
+/** The book-keeping for one in-flight child RPC (keyed by callId). */
+interface PendingChild {
+  started: PromiseWithResolvers<string>
+  settled: PromiseWithResolvers<ChildResult>
+  disposed: PromiseWithResolvers<void>
+}
+
+/** The typed post half of the port: each tag pairs with ITS payload from the map (a mismatch is a compile error at the call site). */
+type Post = <T extends WorkerToHostType>(type: T, payload: WorkerToHostPayloads[T]) => void
+
+/**
+ * The worker-side handle for one started child agent ({@link ChildHandle}):
+ * every member is an RPC to the host keyed by this call's `callId`, resolved
+ * by the session's message handler through the bridge's pending entry.
+ */
+class RpcChildHandle implements ChildHandle {
+  readonly result: Promise<ChildResult>
+
+  constructor(
+    private readonly post: Post,
+    private readonly callId: number,
+    private readonly entry: PendingChild,
+    readonly id: string,
+  ) {
+    this.result = entry.settled.promise
+  }
+
+  cancel(reason?: string): void {
+    this.post(WorkerToHostType.ChildCancel, { callId: this.callId, reason })
+  }
+
+  dispose(): Promise<void> {
+    this.post(WorkerToHostType.ChildDispose, { callId: this.callId })
+    return this.entry.disposed.promise
+  }
+}
+
+/**
+ * The worker-side child-RPC bridge ({@link ChildPort}): allocates callIds,
+ * posts the start/cancel/dispose RPCs, and owns the per-call pending
+ * book-keeping the session's message handler settles via the `onChild*`
+ * entry points.
+ */
+class ChildRpcBridge implements ChildPort {
+  private nextCallId = 0
+  private readonly pending = new Map<number, PendingChild>()
+
+  constructor(private readonly post: Post) {}
+
+  async startAgent(request: ChildStartRequest): Promise<ChildHandle> {
+    this.nextCallId += 1
+    const callId = this.nextCallId
+    const entry: PendingChild = {
+      started: Promise.withResolvers<string>(),
+      settled: Promise.withResolvers<ChildResult>(),
+      disposed: Promise.withResolvers<void>(),
+    }
+    // Containment: when the start is refused (or the run torn down) the
+    // settled promise may never gain a consumer — it must not surface as an
+    // unhandled rejection and kill the worker.
+    entry.settled.promise.catch(() => { /* consumed: unconsumed child settlement after a refused start */ })
+    this.pending.set(callId, entry)
+    this.post(WorkerToHostType.ChildStart, { callId, request })
+    const childId = await entry.started.promise
+    return new RpcChildHandle(this.post, callId, entry, childId)
+  }
+
+  /** The host started the child; releases the `startAgent` await. */
+  onChildStarted(callId: number, childId: string): void {
+    this.pending.get(callId)?.started.resolve(childId)
+  }
+
+  /** The host refused the start; `startAgent` rejects with the rendered cause. */
+  onChildStartError(callId: number, rendered: string): void {
+    this.pending.get(callId)?.started.reject(new Error(rendered))
+  }
+
+  /** The child's terminal result arrived. */
+  onChildSettled(callId: number, result: ChildResult): void {
+    this.pending.get(callId)?.settled.resolve(result)
+  }
+
+  /** The child's `result` rejected host-side (an infrastructure fault, relayed as fatal). */
+  onChildFailed(callId: number, rendered: string): void {
+    this.pending.get(callId)?.settled.reject(new Error(rendered))
+  }
+
+  /** The host acked the dispose; the call's book-keeping is complete. */
+  onChildDisposed(callId: number): void {
+    const entry = this.pending.get(callId)
+    this.pending.delete(callId)
+    entry?.disposed.resolve()
+  }
+}
+
+/**
+ * Narrow the nullable `parentPort` the bootstrap reads from
+ * `node:worker_threads`.
+ * @param port - `parentPort` as imported (null on the main thread).
+ * @returns the port, non-null.
+ */
+export function requireParentPort(port: MessagePort | null): MessagePort {
+  if (port === null) throw new Error('the workflow worker entry must be loaded inside a worker thread (no parentPort)')
+  return port
+}
+
+/**
+ * Run one workflow script to settlement against `port`, posting the terminal
+ * result message exactly once; resolves after that post (stray children may
+ * still be winding down through the port — the host owns their teardown and
+ * ultimately terminates the thread). Never rejects: a constructor failure
+ * (unparseable body — host pre-parse makes this a Node-version-skew signal)
+ * is reported as an `error` result rather than dying without a result.
+ * @param port - the channel to the host (the real `parentPort`, or one side
+ *   of an in-process `MessageChannel` in tests).
+ * @param init - the run payload the host provided as `workerData`.
+ */
+export async function runWorkerSession(port: MessagePort, init: WorkerInit): Promise<void> {
+  const post: Post = (type, payload) => {
+    port.postMessage({ type, ...payload })
+  }
+  const children = new ChildRpcBridge(post)
+
+  const observer: ExecutionObserver = {
+    phase: (title) => { post(WorkerToHostType.Phase, { title }) },
+    log: (message) => { post(WorkerToHostType.Log, { message }) },
+    agentStart: (info) => { post(WorkerToHostType.AgentStart, { info }) },
+    agentEnd: (info) => { post(WorkerToHostType.AgentEnd, { info }) },
+  }
+
+  let execution: WorkflowExecution
+  try {
+    execution = new WorkflowExecution(init.meta, init.body, init.args, init.limits, observer, children)
+  } catch (error: unknown) {
+    post(WorkerToHostType.Result, { result: { value: null, stopReason: 'error', error: renderThrown(error), agentsStarted: 0 } })
+    return
+  }
+
+  const gate = Promise.withResolvers<void>()
+  port.on('message', (message: HostToWorkerMessage) => {
+    switch (message.type) {
+      case HostToWorkerType.Go:
+        gate.resolve()
+        break
+      case HostToWorkerType.Cancel:
+        execution.cancel(message.reason)
+        // A cancel doubles as the gate release: drive() checks the cancelled
+        // state before running the body, so the script never executes.
+        gate.resolve()
+        break
+      case HostToWorkerType.ChildStarted:
+        children.onChildStarted(message.callId, message.childId)
+        break
+      case HostToWorkerType.ChildStartError:
+        children.onChildStartError(message.callId, message.rendered)
+        break
+      case HostToWorkerType.ChildSettled:
+        children.onChildSettled(message.callId, message.result)
+        break
+      case HostToWorkerType.ChildFailed:
+        children.onChildFailed(message.callId, message.rendered)
+        break
+      case HostToWorkerType.ChildDisposed:
+        children.onChildDisposed(message.callId)
+        break
+      /* v8 ignore next 2 -- closed engine-owned union; the arm only makes adding a message type a compile error */
+      default:
+        assertNever(message, 'host-to-worker message')
+    }
+  })
+
+  post(WorkerToHostType.Ready, {})
+  await gate.promise
+  const result = await execution.drive()
+  post(WorkerToHostType.Result, { result })
+}

packages/workflow/workflow-workerthread/src/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Non-protocol wire vocabulary for the worker-thread engine: the `workerData` init
+ * payload and the child-port interfaces the worker-side runtime consumes.
+ * The host⇄worker MESSAGE protocol lives in ./protocol.ts; everything here
+ * that a message transports (`ChildStartRequest`, `ChildResult`) is plain
+ * JSON data by construction, so the structured-clone hop never meets a value
+ * it cannot carry. Types only, per the package convention.
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/types
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { StructuredOutputSchema } from '@deepseek-ai/dsh-tools'
+import type { WorkflowMeta } from '@deepseek-ai/dsh-workflow'
+
+/**
+ * The per-run limits the worker-side runtime enforces. The host keeps the
+ * knobs only it can act on (`provider`, `disposeGraceMs`).
+ */
+export interface WorkerLimits {
+  /** Concurrent `agent()` ceiling (already auto-resolved; ≥ 1). */
+  maxConcurrentAgents: number
+  /** Total `agent()` calls per run (the runaway-loop backstop). */
+  maxTotalAgents: number
+  /** Items accepted by one `parallel()`/`pipeline()` call. */
+  maxItemsPerCall: number
+  /** vm timeout for the script's initial synchronous slice (inside the worker). */
+  syncTimeoutMs: number
+}
+
+/** The `workerData` payload one run is initialized with (host → worker, once, at spawn). */
+export interface WorkerInit {
+  /** The validated meta block (plain data off the start request, validated host-side). */
+  meta: WorkflowMeta
+  /** The plain-JS script body, exactly as the start request carried it. */
+  body: string
+  /** The run's `args` value; the workerData structured clone is the copy that isolates the caller. */
+  args?: unknown
+  /** The worker-enforced limits. */
+  limits: WorkerLimits
+}
+
+/** What the worker asks the host to start for one `agent()` call (options already validated worker-side). */
+export interface ChildStartRequest {
+  /** The child's prompt text. */
+  prompt: string
+  /** The structured-output schema, if the call passed one (already subset-checked). */
+  schema?: StructuredOutputSchema
+  /** The per-child model override, if the call passed one. */
+  model?: string
+}
+
+/**
+ * The JSON projection of a child's `SubagentResult` crossing the port. The
+ * seam's `stopReason` union is merge-extensible, so it degrades to `string`
+ * on the wire — the runtime only ever branches on `'completed'`.
+ */
+export interface ChildResult {
+  /** The child's final assistant output blocks. */
+  output: ContentBlock[]
+  /** The structured value, present iff the request carried a schema AND the provider honored it. */
+  structured?: unknown
+  /** Why the child run ended (`'completed'` is the only value the runtime branches on). */
+  stopReason: string
+}
+
+/**
+ * The worker-side handle for one started child — the RPC mirror of the
+ * subagent seam's run handle, reduced to what the runtime consumes.
+ */
+export interface ChildHandle {
+  /** The child agent's id (minted host-side by the subagent seam). */
+  readonly id: string
+  /**
+   * Resolves with the child's terminal {@link ChildResult}; REJECTS only when
+   * the host reports an infrastructure fault (`child-failed`) — a child that
+   * failed for its own reasons resolves with a non-`completed` stop reason.
+   */
+  readonly result: Promise<ChildResult>
+  /** Ask the host to cancel the child (fire-and-forget). */
+  cancel(reason?: string): void
+  /** Ask the host to dispose the child; resolves on the host's ack. */
+  dispose(): Promise<void>
+}
+
+/**
+ * The worker-side port the runtime starts child agents through — the seam
+ * that lets the execution core stay ignorant of the thread boundary.
+ */
+export interface ChildPort {
+  /**
+   * Start one child agent on the host (the `agent()` hook's start half).
+   * @param request - the prompt and validated options.
+   * @returns the child handle; rejects when the host refuses the start.
+   */
+  startAgent(request: ChildStartRequest): Promise<ChildHandle>
+}

packages/workflow/workflow-workerthread/src/worker.ts

@@ -0,0 +1,18 @@
+/**
+ * The worker-thread entry the engine spawns: bootstrap ./session.ts on the
+ * real `parentPort`. Deliberately a single statement — every piece of logic
+ * lives in `runWorkerSession`, which the unit suite drives in-process over a
+ * `MessageChannel` (code inside a real Worker is invisible to main-process
+ * coverage); loading this module on the main thread throws via
+ * `requireParentPort`, which is how the suite covers the file itself.
+ *
+ * @module @deepseek-ai/dsh-workflow-workerthread/worker
+ */
+
+import { parentPort, workerData } from 'node:worker_threads'
+import { requireParentPort, runWorkerSession } from './session.ts'
+import type { WorkerInit } from './types.ts'
+
+// workerData is `any` at the node:worker_threads boundary; the engine is the
+// only spawner and always provides a WorkerInit.
+void runWorkerSession(requireParentPort(parentPort), workerData as WorkerInit)

packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs'
+import { rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+const builtIndex = join(packageRoot, 'lib', 'index.js')
+const builtWorker = join(packageRoot, 'lib', 'worker.js')
+const run = promisify(execFile)
+
+/**
+ * The BUILT-output guard for the worker entry: every other suite runs
+ * unbuilt (src/ + tsx), so nothing else proves that `lib/index.js` resolves
+ * its sibling `lib/worker.js` and that the bundle boots a worker under plain
+ * node (no tsx loader). Keyless — a zero-agent script needs no provider —
+ * and self-skips until `pnpm run build` has produced the bundles.
+ */
+describe.skipIf(!existsSync(builtIndex) || !existsSync(builtWorker))('built worker entry (lib/worker.js)', () => {
+  it('the built engine spawns its built worker under plain node and completes a run', async () => {
+    // ESM resolves bare specifiers from the IMPORTING FILE's location, so the
+    // driver must live inside the package for its node_modules to apply — a
+    // temp-named file at the package root, removed on the way out.
+    const driver = join(packageRoot, `.built-worker-driver-${process.pid}.mjs`)
+    try {
+      await writeFile(driver, `
+import { Context } from 'cordis'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import WorkerWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread'
+
+const ctx = new Context()
+await ctx.plugin(SubagentService)
+await ctx.plugin(WorkerWorkflowEngine, {})
+const run = ctx.workflows.start({
+  script: 'return 6 * 7',
+  meta: { name: 'built-smoke', description: 'built worker smoke' },
+  // A zero-agent script never touches the provider, so a bare id suffices.
+  parent: { id: 'built-smoke-parent', options: {} },
+})
+const result = await run.result
+await run.dispose()
+if (result.stopReason !== 'completed' || result.value !== 42) {
+  console.error('unexpected result: ' + JSON.stringify(result))
+  process.exit(1)
+}
+console.log('built-worker-smoke-ok')
+`, 'utf8')
+      // Plain node — no tsx loader anywhere; the bundle must stand on its own.
+      const { stdout } = await run(process.execPath, [driver], { cwd: packageRoot, timeout: 60_000 })
+      expect(stdout).toContain('built-worker-smoke-ok')
+    } finally {
+      await rm(driver, { force: true })
+    }
+  }, 120_000)
+})

packages/workflow/workflow-workerthread/tests/integration.spec.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+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, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as Invariants from '@deepseek-ai/dsh-invariants'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as spawn from '@deepseek-ai/dsh-subagent-spawn'
+import { STRUCTURED_OUTPUT_TOOL } from '@deepseek-ai/dsh-subagent-inprocess'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import WorkerWorkflowEngine from '../src/index.ts'
+
+type Script = ConstructorParameters<typeof MockAdapter>[0]
+
+/**
+ * The whole in-process stack, keyless, with the script in a REAL worker
+ * thread: the engine drives the REAL spawn backend (with its
+ * structured runtime) on a real agent loop; the scripted mock MODEL is the
+ * only mocked boundary. This is the guard the unit suites structurally
+ * cannot give — the MessageChannel suite fakes the host, and the host suite
+ * stubs the subagent seam.
+ */
+async function setup(script: Script) {
+  const ctx = new Context()
+  const adapter = new MockAdapter(script)
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(Invariants)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(spawn, { providerName: 'spawn' })
+  await ctx.plugin(WorkerWorkflowEngine, {})
+  ctx.llm.registerAdapter(['mock'], adapter)
+  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
+  return { ctx, parent, adapter }
+}
+
+describe('dsh-workflow-workerthread over the real in-process stack', () => {
+  it('runs a two-stage workflow: a plain child, then a schema child through the structured runtime', async () => {
+    const { ctx, parent } = await setup([
+      textResponse('the file list is a.ts'),
+      toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { verdict: 'real', confidence: 0.9 }),
+    ])
+    const childIds: string[] = []
+    ctx.on('workflow/agent-start', (_info, agent) => { childIds.push(agent.childId) })
+    const run = ctx.workflows.start({
+      meta: { name: 'integration', description: 'plain + structured children' },
+      script: `phase('Read')
+const prose = await agent('read the repo')
+phase('Judge')
+const judged = await agent('judge: ' + prose, {
+  schema: { type: 'object', properties: { verdict: { type: 'string', enum: ['real', 'bogus'] }, confidence: { type: 'number' } }, required: ['verdict'] },
+})
+return { prose, verdict: judged.verdict, confidence: judged.confidence }`,
+      parent,
+    })
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(result.value).toEqual({ prose: 'the file list is a.ts', verdict: 'real', confidence: 0.9 })
+    expect(result.agentsStarted).toBe(2)
+    await run.dispose()
+    // Both children were disposed to quiescence — no live child agents remain.
+    expect(childIds.length).toBe(2)
+    for (const childId of childIds) {
+      expect(ctx.agents.get(AgentId(childId))).toBeUndefined()
+    }
+  })
+
+  it('a child that fails against its schema (nudges exhausted) reaches the script as null', async () => {
+    const { ctx, parent } = await setup([
+      textResponse('prose only'),
+      textResponse('still prose after the nudge'),
+    ])
+    const run = ctx.workflows.start({
+      meta: { name: 'null-path', description: 'schema failure maps to null' },
+      script: `const judged = await agent('judge it', { schema: { type: 'object', properties: { v: { type: 'string' } } } })
+return { got: judged === null ? 'null' : 'value' }`,
+      parent,
+    })
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(result.value).toEqual({ got: 'null' })
+    await run.dispose()
+  })
+})

packages/workflow/workflow-workerthread/tests/meta.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { WorkflowError } from '@deepseek-ai/dsh-workflow'
+import { validateMeta } from '../src/meta.ts'
+
+/** Assert a META_INVALID throw whose message matches every given fragment. */
+function expectInvalid(value: unknown, ...fragments: string[]): void {
+  let thrown: unknown
+  try {
+    validateMeta(value)
+  } catch (error: unknown) {
+    thrown = error
+  }
+  expect(thrown).toBeInstanceOf(WorkflowError)
+  expect((thrown as WorkflowError).code).toBe('META_INVALID')
+  for (const fragment of fragments) {
+    expect((thrown as WorkflowError).message).toContain(fragment)
+  }
+}
+
+describe('validateMeta', () => {
+  it('accepts a minimal meta and returns a normalized copy (no aliasing of the input)', () => {
+    const input = { name: 'audit', description: 'audit the repo' }
+    const meta = validateMeta(input)
+    expect(meta).toEqual({ name: 'audit', description: 'audit the repo' })
+    expect(meta).not.toBe(input)
+    input.name = 'mutated'
+    expect(meta.name).toBe('audit')
+  })
+
+  it('accepts the full shape and rebuilds phases entry by entry', () => {
+    const meta = validateMeta({
+      name: 'migrate',
+      description: 'migrate call sites',
+      whenToUse: 'large mechanical sweeps',
+      phases: [
+        { title: 'Discover' },
+        { title: 'Transform', detail: 'one agent per file', model: 'deepseek-v4-pro' },
+      ],
+    })
+    expect(meta).toEqual({
+      name: 'migrate',
+      description: 'migrate call sites',
+      whenToUse: 'large mechanical sweeps',
+      phases: [
+        { title: 'Discover' },
+        { title: 'Transform', detail: 'one agent per file', model: 'deepseek-v4-pro' },
+      ],
+    })
+  })
+
+  it('rejects non-object values loud', () => {
+    expectInvalid(undefined, 'meta must be an object')
+    expectInvalid('a string', 'meta must be an object')
+    expectInvalid(null, 'meta must be an object')
+    expectInvalid([{ name: 'x', description: 'd' }], 'meta must be an object')
+  })
+
+  it('rejects unknown fields by name (accepted-then-ignored is banned)', () => {
+    expectInvalid({ name: 'x', description: 'd', color: 'red' }, 'meta.color is not a recognized field')
+  })
+
+  it('rejects missing or mistyped name/description/whenToUse', () => {
+    expectInvalid({ description: 'd' }, 'meta.name must be a non-empty string')
+    expectInvalid({ name: '', description: 'd' }, 'meta.name must be a non-empty string')
+    expectInvalid({ name: 'x' }, 'meta.description must be a non-empty string')
+    expectInvalid({ name: 'x', description: 42 }, 'meta.description must be a non-empty string')
+    expectInvalid({ name: 'x', description: 'd', whenToUse: 3 }, 'meta.whenToUse must be a string')
+  })
+
+  it('rejects malformed phases, entry by entry', () => {
+    expectInvalid({ name: 'x', description: 'd', phases: 'Scan' }, 'meta.phases must be an array')
+    expectInvalid({ name: 'x', description: 'd', phases: ['Scan'] }, 'meta.phases[0] must be an object')
+    expectInvalid({ name: 'x', description: 'd', phases: [{ title: '' }] }, 'meta.phases[0].title must be a non-empty string')
+    expectInvalid({ name: 'x', description: 'd', phases: [{ title: 'Scan', order: 1 }] }, 'meta.phases[0].order is not a recognized field')
+    expectInvalid({ name: 'x', description: 'd', phases: [{ title: 'Scan', detail: 9 }] }, 'meta.phases[0].detail must be a string')
+    expectInvalid({ name: 'x', description: 'd', phases: [{ title: 'Scan', model: 9 }] }, 'meta.phases[0].model must be a string')
+  })
+
+  it('names EVERY violation in one throw, not just the first', () => {
+    expectInvalid(
+      { description: 7, extra: true, phases: [{ title: 'Scan' }, 'bad'] },
+      'meta.extra is not a recognized field',
+      'meta.name must be a non-empty string',
+      'meta.description must be a non-empty string',
+      'meta.phases[1] must be an object',
+    )
+  })
+})

packages/workflow/workflow-workerthread/tests/realm.spec.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest'
+import * as vm from 'node:vm'
+import { materializeFromRealm, MaterializeError, renderThrown } from '../src/realm.ts'
+
+/** Evaluate an expression inside a fresh vm realm and hand back the raw realm value. */
+function inRealm(expression: string): unknown {
+  return vm.runInNewContext(`(${expression})`)
+}
+
+/** The MaterializeError message for a value that must be rejected (throws if accepted). */
+function rejection(value: unknown): string {
+  try {
+    materializeFromRealm(value)
+  } catch (error: unknown) {
+    if (error instanceof MaterializeError) return error.message
+    throw error
+  }
+  throw new Error('expected the value to be rejected')
+}
+
+describe('materializeFromRealm', () => {
+  it('copies realm objects/arrays/scalars into host plain data', () => {
+    const value = inRealm("{ a: 1, b: 'x', c: true, d: null, list: [1, [2, { deep: 'y' }]] }")
+    const out = materializeFromRealm(value) as Record<string, unknown>
+    expect(out).toEqual({ a: 1, b: 'x', c: true, d: null, list: [1, [2, { deep: 'y' }]] })
+    // The copy is HOST data: prototypes are the host intrinsics.
+    expect(Object.getPrototypeOf(out)).toBe(Object.prototype)
+    expect(Array.isArray(out.list)).toBe(true)
+    // And it round-trips through JSON byte-identically (the whole point).
+    expect(JSON.parse(JSON.stringify(out))).toEqual(out)
+  })
+
+  it('accepts undefined ONLY at the root (a valueless script return)', () => {
+    expect(materializeFromRealm(undefined)).toBeUndefined()
+    expect(rejection(inRealm('{ a: undefined }'))).toContain('value.a')
+  })
+
+  it('invokes getters ordinarily — the getter RESULT is what crosses (trust premise)', () => {
+    const counter = inRealm(`
+      (() => {
+        globalThis.reads = 0
+        return { get x() { globalThis.reads += 1; return globalThis.reads } }
+      })()
+    `)
+    expect(materializeFromRealm(counter)).toEqual({ x: 1 })
+  })
+
+  it('a getter that THROWS surfaces as a MaterializeError carrying the rendered failure', () => {
+    const hostile = inRealm("{ get x() { throw new Error('read failed') } }")
+    const message = rejection(hostile)
+    expect(message).toContain('reading the value threw')
+    expect(message).toContain('read failed')
+  })
+
+  it('a "__proto__" key becomes an OWN data property of the copy, never a prototype mutation', () => {
+    const value: unknown = vm.runInNewContext('JSON.parse(\'{"__proto__": {"polluted": 1}, "ok": 2}\')')
+    const out = materializeFromRealm(value) as Record<string, unknown>
+    expect(Object.getPrototypeOf(out)).toBe(Object.prototype)
+    expect(Object.prototype.hasOwnProperty.call(out, '__proto__')).toBe(true)
+    expect(out.ok).toBe(2)
+    // The host Object.prototype was NOT touched.
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined()
+  })
+
+  it('rejects functions, symbols (keys and values), and bigints with path-qualified messages', () => {
+    expect(rejection(inRealm('{ fn: () => 1 }'))).toContain('value.fn')
+    expect(rejection(inRealm("{ [Symbol('k')]: 1 }"))).toContain('symbol-keyed')
+    expect(rejection(inRealm("{ s: Symbol('v') }"))).toContain('value.s')
+    expect(rejection(inRealm('{ big: 1n }'))).toContain('value.big')
+    expect(rejection(inRealm("[Symbol('x')]"))).toContain('value[0]')
+    const taggedArray = inRealm("(() => { const a = [1]; a[Symbol('t')] = 1; return a })()")
+    expect(rejection(taggedArray)).toContain('symbol-keyed')
+  })
+
+  it('rejects non-finite numbers and undefined values inside containers', () => {
+    expect(rejection(inRealm('{ n: NaN }'))).toContain('non-finite')
+    expect(rejection(inRealm('[Infinity]'))).toContain('non-finite')
+  })
+
+  it('rejects exotic prototypes (Date, Map, class instances) but accepts null-prototype data', () => {
+    expect(rejection(inRealm('{ d: new Date(0) }'))).toContain('exotic prototype')
+    expect(rejection(inRealm('new Map()'))).toContain('exotic prototype')
+    expect(rejection(inRealm('(() => { class C { constructor() { this.x = 1 } } return new C() })()')))
+      .toContain('exotic prototype')
+    expect(materializeFromRealm(inRealm('Object.assign(Object.create(null), { a: 1 })'))).toEqual({ a: 1 })
+  })
+
+  it('rejects cycles and accepts the same object reused as a sibling (a DAG)', () => {
+    expect(rejection(inRealm('(() => { const o = {}; o.self = o; return o })()'))).toContain('circular')
+    const dag = inRealm('(() => { const leaf = { v: 1 }; return { a: leaf, b: leaf } })()')
+    expect(materializeFromRealm(dag)).toEqual({ a: { v: 1 }, b: { v: 1 } })
+  })
+
+  it('rejects sparse arrays and non-index array properties; an array getter element materializes its value', () => {
+    expect(rejection(inRealm('[1, , 3]'))).toContain('sparse')
+    expect(rejection(inRealm('(() => { const a = [1]; a.total = 3; return a })()')))
+      .toContain('non-index')
+    expect(materializeFromRealm(inRealm('(() => { const a = [1]; Object.defineProperty(a, 0, { get: () => 7, enumerable: true }); return a })()')))
+      .toEqual([7])
+  })
+
+  it('skips non-enumerable own properties (matching JSON.stringify exactly)', () => {
+    const value = inRealm(`(() => {
+      const o = { visible: 1 }
+      Object.defineProperty(o, 'hidden', { value: () => 1, enumerable: false })
+      return o
+    })()`)
+    expect(materializeFromRealm(value)).toEqual({ visible: 1 })
+  })
+
+  it('works on plain host values too (the boundary is realm-agnostic)', () => {
+    expect(materializeFromRealm({ a: [1, 'x'] })).toEqual({ a: [1, 'x'] })
+    expect(materializeFromRealm('str')).toBe('str')
+    expect(materializeFromRealm(3)).toBe(3)
+    expect(materializeFromRealm(false)).toBe(false)
+    expect(materializeFromRealm(null)).toBeNull()
+  })
+})
+
+describe('renderThrown', () => {
+  it('prefers the stack, for host and realm errors alike', () => {
+    const host = renderThrown(new Error('host failure'))
+    expect(host).toContain('host failure')
+    expect(host).toContain('at ') // a real stack, not just the message
+    const realmError: unknown = vm.runInNewContext('(() => { try { throw new Error("realm failure") } catch (e) { return e } })()')
+    expect(renderThrown(realmError)).toContain('realm failure')
+  })
+
+  it('falls back from stack to message to String()', () => {
+    expect(renderThrown({ stack: 'custom data stack' })).toBe('custom data stack')
+    const stackless = new Error('stackless failure')
+    delete stackless.stack
+    expect(renderThrown(stackless)).toBe('stackless failure')
+    expect(renderThrown({ code: 42 })).toBe('[object Object]')
+    expect(renderThrown('plain')).toBe('plain')
+    expect(renderThrown(42)).toBe('42')
+    expect(renderThrown(undefined)).toBe('undefined')
+    expect(renderThrown(null)).toBe('null')
+  })
+
+  it('is total: a value whose accessors/toString throw renders as a fixed label', () => {
+    expect(renderThrown({ get stack() { throw new Error('nope') } })).toBe('[unrenderable thrown value]')
+    expect(renderThrown({ [Symbol.toPrimitive]() { throw new Error('nope') } })).toBe('[unrenderable thrown value]')
+  })
+})

packages/workflow/workflow-workerthread/tests/session.spec.ts

@@ -0,0 +1,504 @@
+import { describe, expect, it, vi } from 'vitest'
+import { MessageChannel } from 'node:worker_threads'
+import type { MessagePort } from 'node:worker_threads'
+import { HostToWorkerType, WorkerToHostType } from '../src/protocol.ts'
+import type { HostToWorkerMessage, WorkerToHostMessage } from '../src/protocol.ts'
+import { requireParentPort, runWorkerSession } from '../src/session.ts'
+import type { ChildResult, WorkerInit } from '../src/types.ts'
+
+/** Default limits for in-process sessions (concurrency pinned; auto is machine-derived). */
+function limits(overrides?: Partial<WorkerInit['limits']>): WorkerInit['limits'] {
+  return { maxConcurrentAgents: 8, maxTotalAgents: 1000, maxItemsPerCall: 4096, syncTimeoutMs: 5000, ...overrides }
+}
+
+/** Wrap a body in the minimal valid meta header (the session receives it pre-extracted). */
+function init(body: string, args?: unknown, limitOverrides?: Partial<WorkerInit['limits']>): WorkerInit {
+  return {
+    meta: { name: 'test-flow', description: 'a test workflow' },
+    body,
+    ...args !== undefined ? { args } : {},
+    limits: limits(limitOverrides),
+  }
+}
+
+/** One scripted host over the other end of a MessageChannel. */
+interface FakeHost {
+  port: MessagePort
+  messages: WorkerToHostMessage[]
+  /** Messages of one type, as they arrive. */
+  ofType<T extends WorkerToHostMessage['type']>(type: T): Extract<WorkerToHostMessage, { type: T }>[]
+  send(message: HostToWorkerMessage): void
+  /** Resolves with the terminal result message. */
+  result(): Promise<Extract<WorkerToHostMessage, { type: 'result' }>['result']>
+  close(): void
+}
+
+interface FakeHostOptions {
+  /** Auto-respond to child-start: reply started + settled per child index. Omit a reply to leave the child pending. */
+  reply?: (request: { prompt: string; schema?: unknown; model?: string }, index: number) => ChildResult | undefined
+  /** Reject the start instead (child-start-error) when returning a string. */
+  refuse?: (index: number) => string | undefined
+  /** Auto-send `go` on `ready` (default true). */
+  go?: boolean
+  /** Manual mode: do NOT auto-answer child-start at all (the test scripts the replies). */
+  manual?: boolean
+}
+
+/**
+ * Drive runWorkerSession IN-PROCESS over a MessageChannel: this is where the
+ * worker-side files earn their coverage — code inside a real Worker is
+ * invisible to main-process coverage. The fake host mirrors the real host's
+ * protocol discipline (one started/start-error per start; settled/disposed
+ * follow).
+ */
+function fakeHost(options?: FakeHostOptions): FakeHost {
+  const channel = new MessageChannel()
+  const messages: WorkerToHostMessage[] = []
+  const resultGate = Promise.withResolvers<Extract<WorkerToHostMessage, { type: 'result' }>['result']>()
+  let childIndex = 0
+  channel.port1.on('message', (message: WorkerToHostMessage) => {
+    messages.push(message)
+    switch (message.type) {
+      case WorkerToHostType.Ready:
+        if (options?.go !== false) channel.port1.postMessage({ type: HostToWorkerType.Go } satisfies HostToWorkerMessage)
+        break
+      case WorkerToHostType.ChildStart: {
+        if (options?.manual) break
+        const index = childIndex
+        childIndex += 1
+        const refusal = options?.refuse?.(index)
+        if (refusal !== undefined) {
+          channel.port1.postMessage(
+            { type: HostToWorkerType.ChildStartError, callId: message.callId, rendered: refusal } satisfies HostToWorkerMessage,
+          )
+          break
+        }
+        channel.port1.postMessage({ type: HostToWorkerType.ChildStarted, callId: message.callId, childId: `child-${index}` } satisfies HostToWorkerMessage)
+        const reply = options?.reply?.(message.request, index)
+        if (reply !== undefined) {
+          channel.port1.postMessage(
+            { type: HostToWorkerType.ChildSettled, callId: message.callId, result: reply } satisfies HostToWorkerMessage,
+          )
+        }
+        break
+      }
+      case WorkerToHostType.ChildDispose:
+        channel.port1.postMessage({ type: HostToWorkerType.ChildDisposed, callId: message.callId } satisfies HostToWorkerMessage)
+        break
+      case WorkerToHostType.Result:
+        resultGate.resolve(message.result)
+        break
+      default:
+        break
+    }
+  })
+  return {
+    port: channel.port2,
+    messages,
+    ofType: type => messages.filter((message): message is never => message.type === type),
+    send: (message) => { channel.port1.postMessage(message) },
+    result: () => resultGate.promise,
+    close: () => { channel.port1.close() },
+  }
+}
+
+/** A completed text child result. */
+function text(reply: string): ChildResult {
+  return { output: [{ type: 'text', text: reply }], stopReason: 'completed' }
+}
+
+describe('runWorkerSession over an in-process MessageChannel', () => {
+  it('runs a script end to end: ready/go handshake, phases, log, agents, result', async () => {
+    const host = fakeHost({ reply: (_request, index) => text(`answer-${index}`) })
+    const session = runWorkerSession(host.port, init(`
+      phase('Scan')
+      log('starting with ' + args.files.length + ' files')
+      const answers = await pipeline(args.files, (prev, item) => agent('read ' + item))
+      return { answers }
+    `, { files: ['a.ts', 'b.ts'] }))
+    const result = await host.result()
+    await session
+    expect(result.stopReason).toBe('completed')
+    expect(result.agentsStarted).toBe(2)
+    expect(result.value).toEqual({ answers: ['answer-0', 'answer-1'] })
+    expect(host.messages[0]!.type).toBe('ready')
+    expect(host.ofType(WorkerToHostType.Phase).map(m => m.title)).toEqual(['Scan'])
+    expect(host.ofType(WorkerToHostType.Log).map(m => m.message)).toEqual(['starting with 2 files'])
+    expect(host.ofType(WorkerToHostType.AgentStart).map(m => m.info.childId)).toEqual(['child-0', 'child-1'])
+    expect(host.ofType(WorkerToHostType.AgentEnd).every(m => m.info.outcome === 'completed')).toBe(true)
+    host.close()
+  })
+
+  it('agent({schema}) forwards the schema on the start request and returns the structured value', async () => {
+    const host = fakeHost({ reply: () => ({ output: [], structured: { files: ['x.ts'] }, stopReason: 'completed' }) })
+    void runWorkerSession(host.port, init(`
+      const found = await agent('list files', { schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } } }, model: 'deepseek-v4-pro' })
+      return { first: found.files[0] }
+    `))
+    const result = await host.result()
+    expect(result.value).toEqual({ first: 'x.ts' })
+    const start = host.ofType(WorkerToHostType.ChildStart)[0]!
+    expect(start.request.schema).toEqual({ type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } } })
+    expect(start.request.model).toBe('deepseek-v4-pro')
+    host.close()
+  })
+
+  it('a schema child completing WITHOUT a structured value resolves null with a failed outcome', async () => {
+    const host = fakeHost({ reply: () => text('prose, no structure') })
+    void runWorkerSession(host.port, init("return await agent('p', { schema: { type: 'object' } })"))
+    const result = await host.result()
+    expect(result.value).toBeNull()
+    expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('failed')
+    host.close()
+  })
+
+  it('a child settling non-completed resolves null (scripts filter), never throwing into the script', async () => {
+    const host = fakeHost({ reply: (_request, index) => index === 0 ? { output: [], stopReason: 'error' } : text('ok') })
+    void runWorkerSession(host.port, init("return await parallel([() => agent('one'), () => agent('two')])"))
+    const result = await host.result()
+    expect(result.value).toEqual([null, 'ok'])
+    expect(host.ofType(WorkerToHostType.AgentEnd).map(m => m.info.outcome)).toEqual(expect.arrayContaining(['failed', 'completed']))
+    host.close()
+  })
+
+  it('a start refusal (child-start-error) is a fatal AGENT_START that kills the script through a combinator', async () => {
+    const host = fakeHost({ refuse: () => 'no provider here' })
+    void runWorkerSession(host.port, init("return await pipeline([1], () => agent('p'))"))
+    const result = await host.result()
+    expect(result.stopReason).toBe('error')
+    expect(result.error).toContain('agent() could not start a child')
+    expect(result.error).toContain('no provider here')
+    host.close()
+  })
+
+  it('a child-failed message (infrastructure rejection) is fatal AGENT_RESULT with the paired failed outcome', async () => {
+    const host = fakeHost()
+    void runWorkerSession(host.port, init(`
+      try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, code: e.code, fatal: e.fatal } }
+    `))
+    await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
+    const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
+    host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' })
+    host.send({ type: HostToWorkerType.ChildFailed, callId, rendered: 'backend exploded' })
+    const result = await host.result()
+    expect(result.value).toMatchObject({ name: 'WorkflowError', code: 'AGENT_RESULT', fatal: true })
+    expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('failed')
+    host.close()
+  })
+
+  it('cancel before go: the body never runs at all and the result is cancelled (a second cancel is a no-op)', async () => {
+    const host = fakeHost({ go: false })
+    const session = runWorkerSession(host.port, init("log('ran')\nreturn 123"))
+    await vi.waitFor(() => { expect(host.messages.some(m => m.type === WorkerToHostType.Ready)).toBe(true) })
+    host.send({ type: HostToWorkerType.Cancel, reason: 'aborted before start' })
+    // Idempotence: the first reason wins; a duplicate cancel changes nothing.
+    host.send({ type: HostToWorkerType.Cancel, reason: 'a later reason that must lose' })
+    const result = await host.result()
+    await session
+    expect(result.stopReason).toBe('cancelled')
+    expect(result.error).toContain('aborted before start')
+    expect(result.error).not.toContain('must lose')
+    expect(result.value).toBeNull()
+    expect(host.ofType(WorkerToHostType.Log)).toEqual([])
+    host.close()
+  })
+
+  it('a script with no return value resolves value: null', async () => {
+    const host = fakeHost({ reply: () => text('ok') })
+    void runWorkerSession(host.port, init("await agent('p')"))
+    const result = await host.result()
+    expect(result.stopReason).toBe('completed')
+    expect(result.value).toBeNull()
+    host.close()
+  })
+
+  it('cancel mid-run: in-flight children get cancel RPCs, hooks throw at entry, the run reports cancelled', async () => {
+    const host = fakeHost()
+    void runWorkerSession(host.port, init(`
+      phase('before')
+      try { await agent('x') } catch (e) {}
+      try { phase('after') } catch (e) {}
+      try { log('after') } catch (e) {}
+      try { await parallel([() => 'ran']) } catch (e) {}
+      try { await pipeline(['item'], p => p) } catch (e) {}
+      return 'survived by catching'
+    `))
+    await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
+    const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
+    host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' })
+    host.send({ type: HostToWorkerType.Cancel, reason: 'stop everything' })
+    // The real host settles the aborted child; mirror it.
+    host.send({ type: HostToWorkerType.ChildSettled, callId, result: { output: [], stopReason: 'aborted' } })
+    const result = await host.result()
+    expect(result.stopReason).toBe('cancelled')
+    expect(result.error).toContain('stop everything')
+    expect(host.ofType(WorkerToHostType.ChildCancel).map(m => m.callId)).toContain(callId)
+    expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('cancelled')
+    // No post-cancel narration left the runtime (the hooks threw at entry).
+    expect(host.ofType(WorkerToHostType.Phase).map(m => m.title)).toEqual(['before'])
+    expect(host.ofType(WorkerToHostType.Log)).toEqual([])
+    host.close()
+  })
+
+  it('cancellation between a queued waiter and its slot: the waiter rejects without a child-start', async () => {
+    const host = fakeHost({ go: true })
+    void runWorkerSession(host.port, init(
+      "return await parallel([() => agent('a'), () => agent('b')])",
+      undefined,
+      { maxConcurrentAgents: 1 },
+    ))
+    await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
+    host.send({ type: HostToWorkerType.Cancel, reason: 'raced' })
+    const result = await host.result()
+    expect(result.stopReason).toBe('cancelled')
+    // Only the first agent ever reached the host.
+    expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1)
+    host.close()
+  })
+
+  it('a stray (never-awaited) agent is reaped after settlement: cancel + dispose RPCs flow, no unhandled rejection', async () => {
+    const unhandled: unknown[] = []
+    const onUnhandled = (reason: unknown): void => { unhandled.push(reason) }
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const host = fakeHost()
+      void runWorkerSession(host.port, init(`
+        agent('stray, never awaited')
+        return 'done without awaiting'
+      `))
+      const result = await host.result()
+      expect(result.stopReason).toBe('completed')
+      await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
+      const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
+      host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' })
+      host.send({ type: HostToWorkerType.ChildSettled, callId, result: { output: [], stopReason: 'aborted' } })
+      await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildDispose).map(m => m.callId)).toContain(callId) })
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(unhandled).toEqual([])
+      host.close()
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+
+  it('an unparseable body settles an error result instead of dying without one (host pre-parse skew guard)', async () => {
+    const host = fakeHost()
+    await runWorkerSession(host.port, init('return ((('))
+    const result = await host.result()
+    expect(result.stopReason).toBe('error')
+    expect(result.error).toContain('does not parse')
+    expect(result.agentsStarted).toBe(0)
+    host.close()
+  })
+
+  it('a synchronous spin in the initial slice dies by the in-worker vm timeout', async () => {
+    const host = fakeHost()
+    void runWorkerSession(host.port, init('while (true) {}', undefined, { syncTimeoutMs: 50 }))
+    const result = await host.result()
+    expect(result.stopReason).toBe('error')
+    expect(result.error?.toLowerCase()).toContain('timed out')
+    host.close()
+  })
+
+  it('a non-JSON return value fails loud as RESULT_UNSERIALIZABLE', async () => {
+    const host = fakeHost()
+    void runWorkerSession(host.port, init('return { when: new Date(0) }'))
+    const result = await host.result()
+    expect(result.stopReason).toBe('error')
+    expect(result.error).toContain('not plain JSON data')
+    host.close()
+  })
+
+  it('tolerates replies for unknown callIds (a teardown race): nothing crashes, the run completes', async () => {
+    const host = fakeHost({ reply: () => text('fine') })
+    void runWorkerSession(host.port, init("return await agent('p')"))
+    host.send({ type: HostToWorkerType.ChildStarted, callId: 999, childId: 'ghost' })
+    host.send({ type: HostToWorkerType.ChildStartError, callId: 999, rendered: 'ghost' })
+    host.send({ type: HostToWorkerType.ChildSettled, callId: 999, result: text('ghost') })
+    host.send({ type: HostToWorkerType.ChildFailed, callId: 999, rendered: 'ghost' })
+    host.send({ type: HostToWorkerType.ChildDisposed, callId: 999 })
+    const result = await host.result()
+    expect(result.stopReason).toBe('completed')
+    expect(result.value).toBe('fine')
+    host.close()
+  })
+
+  it('caps and malformed hook arguments reject loud (the runtime runs unchanged inside the session)', async () => {
+    const cases: [string, string][] = [
+      ['return await agent(42)', 'non-empty prompt string'],
+      ["return await agent('')", 'non-empty prompt string'],
+      ["return await agent('p', 'opts')", 'options must be an object'],
+      ["return await agent('p', { label: 3 })", '"label" must be a string'],
+      ["return await agent('p', { get label() { throw new Error('read failed') } })", 'options must be plain JSON data'],
+      ["return await agent('p', { bogus: true })", '"bogus" is not recognized'],
+      ["return await agent('p', { effort: 'high' })", '"effort" is deferred'],
+      ["return await agent('p', { schema: { type: 'object', oneOf: [] } })", 'outside the supported subset'],
+      ['return await parallel([() => 1, () => 2, () => 3])', 'over the per-call cap (2)'],
+      ['return await pipeline([1, 2, 3], (x) => x)', 'maxItemsPerCall'],
+      ["return await parallel('no')", 'parallel() requires an array'],
+      ['return await parallel([3])', 'item 0 is not a function'],
+      ["return await pipeline('no', () => 1)", 'pipeline() requires an items array'],
+      ['return await pipeline([1])', 'at least one stage'],
+      ["return await pipeline([1], 'x')", 'stage 0 is not a function'],
+      ["phase('')", 'phase() requires a non-empty title string'],
+      ['log(3)', 'log() requires a message string'],
+    ]
+    for (const [body, expected] of cases) {
+      const host = fakeHost({ reply: () => text('ok') })
+      void runWorkerSession(host.port, init(body, undefined, { maxItemsPerCall: 2 }))
+      const result = await host.result()
+      expect(result.stopReason).toBe('error')
+      expect(result.error).toContain(expected)
+      host.close()
+    }
+  })
+
+  it('combinator semantics: thunk/stage throws null the item; a forged fatal-shaped object stays null; real fatals propagate', async () => {
+    const host = fakeHost({ reply: () => text('fine') })
+    void runWorkerSession(host.port, init(`
+      const viaParallel = await parallel([
+        () => { throw new Error('boom') },
+        () => agent('fine'),
+        () => 'plain value',
+        () => { throw { name: 'WorkflowError', fatal: true, message: 'forged fatal' } },
+      ])
+      const viaPipeline = await pipeline([10, 20],
+        (prev, item, index) => { if (item === 10) throw new Error('ordinary failure'); return 'kept-' + item + '-' + index },
+      )
+      return { viaParallel, viaPipeline }
+    `))
+    const result = await host.result()
+    expect(result.stopReason).toBe('completed')
+    expect(result.value).toEqual({
+      viaParallel: [null, 'fine', 'plain value', null],
+      viaPipeline: [null, 'kept-20-1'],
+    })
+    host.close()
+  })
+
+  it('trips the total-agent cap with a message naming the config knob', async () => {
+    const host = fakeHost({ reply: () => text('ok') })
+    void runWorkerSession(host.port, init("await agent('1'); await agent('2'); await agent('3')", undefined, { maxTotalAgents: 2 }))
+    const result = await host.result()
+    expect(result.stopReason).toBe('error')
+    expect(result.error).toContain('total agent cap (2)')
+    expect(result.agentsStarted).toBe(2)
+    host.close()
+  })
+
+  it('queued agents proceed through the concurrency semaphore in FIFO order', async () => {
+    const host = fakeHost({ reply: request => text(`ok:${request.prompt}`) })
+    void runWorkerSession(host.port, init(
+      "return await parallel([1, 2, 3].map((n) => () => agent('job ' + n)))",
+      undefined,
+      { maxConcurrentAgents: 1 },
+    ))
+    const result = await host.result()
+    expect(result.value).toEqual(['ok:job 1', 'ok:job 2', 'ok:job 3'])
+    host.close()
+  })
+
+  it('labels default from the prompt first line, truncated; explicit label/phase options win', async () => {
+    const host = fakeHost({ reply: () => text('ok') })
+    void runWorkerSession(host.port, init(`
+      phase('Find')
+      await agent('a prompt that is quite long and will surely get truncated down to a display label\\n'
+        + 'with a second line the label must not include')
+      await agent('short', { label: 'named', phase: 'Custom' })
+      return null
+    `))
+    await host.result()
+    const starts = host.ofType(WorkerToHostType.AgentStart).map(m => m.info)
+    expect(starts[0]).toMatchObject({ seq: 1, phase: 'Find' })
+    expect(starts[0]!.label.length).toBeLessThanOrEqual(48)
+    expect(starts[0]!.label).not.toContain('second line')
+    expect(starts[1]).toMatchObject({ seq: 2, label: 'named', phase: 'Custom' })
+    host.close()
+  })
+
+  it('non-text output blocks are filtered out of the text result', async () => {
+    const host = fakeHost({
+      reply: () => ({
+        output: [
+          { type: 'text', text: 'first ' },
+          { type: 'tool_call', id: 'c1', name: 'x', arguments: {} } as never,
+          { type: 'text', text: 'second' },
+        ],
+        stopReason: 'completed',
+      }),
+    })
+    void runWorkerSession(host.port, init("return await agent('p')"))
+    const result = await host.result()
+    expect(result.value).toBe('first second')
+    host.close()
+  })
+
+  it('a cancel landing DURING the start round-trip winds the fresh child down (cancel + dispose) and dies cancelled', async () => {
+    const host = fakeHost({ manual: true })
+    void runWorkerSession(host.port, init("return await agent('p')"))
+    await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
+    const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
+    // Cancel FIRST, then the (stale) started reply: the worker processes them
+    // in order, so the agent() continuation resumes already-cancelled — the
+    // window the real host cannot produce (it refuses starts once cancelled)
+    // but a teardown race can.
+    host.send({ type: HostToWorkerType.Cancel, reason: 'raced the start' })
+    host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' })
+    const result = await host.result()
+    expect(result.stopReason).toBe('cancelled')
+    await vi.waitFor(() => {
+      expect(host.ofType(WorkerToHostType.ChildCancel).map(m => m.callId)).toContain(callId)
+      expect(host.ofType(WorkerToHostType.ChildDispose).map(m => m.callId)).toContain(callId)
+    })
+    // The child never became an agent-start: it was wound down pre-lifecycle.
+    expect(host.ofType(WorkerToHostType.AgentStart)).toEqual([])
+    host.close()
+  })
+
+  it('a start refusal arriving after a cancel reads as the cancellation, not a broken seam', async () => {
+    const host = fakeHost({ manual: true })
+    void runWorkerSession(host.port, init(`
+      try { await agent('p'); return 'unreachable' } catch (e) { return { code: e.code } }
+    `))
+    await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
+    const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
+    host.send({ type: HostToWorkerType.Cancel, reason: 'stopping' })
+    host.send({ type: HostToWorkerType.ChildStartError, callId, rendered: 'workflow run cancelled: stopping' })
+    const result = await host.result()
+    // The run reports cancelled (the script died of CANCELLED, not AGENT_START).
+    expect(result.stopReason).toBe('cancelled')
+    host.close()
+  })
+
+  it('a child result rejection while cancelled pairs a cancelled agent-end, and the run reports cancelled', async () => {
+    const host = fakeHost({ manual: true })
+    void runWorkerSession(host.port, init("return await agent('doomed')"))
+    await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
+    const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
+    host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' })
+    await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.AgentStart).length).toBe(1) })
+    host.send({ type: HostToWorkerType.Cancel, reason: 'user aborted' })
+    host.send({ type: HostToWorkerType.ChildFailed, callId, rendered: 'backend crashed on abort' })
+    const result = await host.result()
+    expect(result.stopReason).toBe('cancelled')
+    expect(host.ofType(WorkerToHostType.AgentEnd)[0]!.info.outcome).toBe('cancelled')
+    host.close()
+  })
+
+})
+
+describe('the worker bootstrap', () => {
+  it('requireParentPort narrows a real port and throws on the main thread', () => {
+    const channel = new MessageChannel()
+    expect(requireParentPort(channel.port1)).toBe(channel.port1)
+    channel.port1.close()
+    expect(() => requireParentPort(null)).toThrow(/inside a worker thread/)
+  })
+
+  it('the entry module itself throws when loaded on the main thread (no parentPort)', async () => {
+    // This import EXECUTES ../src/worker.ts on the main thread, which is what
+    // covers the bootstrap file: requireParentPort throws before
+    // runWorkerSession is reached.
+    await expect(import('../src/worker.ts')).rejects.toThrow(/inside a worker thread/)
+  })
+})

packages/workflow/workflow-workerthread/tests/workflow-workerthread.e2e.ts

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+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, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as Spawn from '@deepseek-ai/dsh-subagent-spawn'
+import WorkerWorkflowEngine from '../src/index.ts'
+
+/**
+ * With-key e2e: a REAL script in a REAL worker thread
+ * drives REAL spawn children against the live DeepSeek API — one plain child
+ * and one schema'd child through the real structured-output runtime — and
+ * the run's value, events, and child sessions are asserted from the outside
+ * (never the script's self-report alone). Key-gated (self-skips without
+ * DEEPSEEK_API_KEY).
+ */
+
+let ctx: Context | undefined
+
+afterEach(async () => {
+  await ctx?.fiber.dispose()
+  ctx = undefined
+})
+
+async function harness(): Promise<Context> {
+  const built = new Context()
+  await built.plugin(LlmService)
+  await built.plugin(SessionStore)
+  await built.plugin(SystemPrompt)
+  await built.plugin(ToolRegistry)
+  await built.plugin(AgentRegistry)
+  await built.plugin(AgentLoop, { agents: [] })
+  await built.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await built.plugin(SubagentService)
+  await built.plugin(Spawn, { providerName: 'spawn' })
+  await built.plugin(WorkerWorkflowEngine, { provider: 'spawn' })
+  return built
+}
+
+const META = {
+  name: 'e2e-worker-arithmetic',
+  description: 'two real children through a worker thread: one prose, one structured',
+  phases: [{ title: 'Ask' }, { title: 'Judge' }],
+}
+const SCRIPT = `phase('Ask')
+log('asking the prose child')
+const prose = await agent('Reply with exactly one short sentence: what is 2 + 2?')
+phase('Judge')
+const judged = await agent(
+  'Here is an answer to the question "what is 2+2": ' + prose
+  + ' — report whether it contains the number 4 and your confidence between 0 and 1.',
+  { schema: { type: 'object', properties: { containsFour: { type: 'boolean' }, confidence: { type: 'number' } }, required: ['containsFour'] } },
+)
+return { prose, containsFour: judged === null ? null : judged.containsFour }`
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('worker workflow engine with-key e2e', () => {
+  it('runs a two-phase script in a worker thread over real children, one through the structured runtime', async () => {
+    ctx = await harness()
+    const parentHandle = ctx.agents.create({
+      agentId: AgentId('wf-worker-e2e-parent'),
+      sessionId: 'wf-worker-e2e-session' as never,
+      agentOptions: { model: 'deepseek-v4-flash' },
+    })
+
+    const events: string[] = []
+    const childIds: string[] = []
+    for (const name of ['workflow/start', 'workflow/phase', 'workflow/log', 'workflow/agent-start', 'workflow/agent-end', 'workflow/end'] as const) {
+      ctx.on(name, (...payload: unknown[]) => {
+        events.push(name)
+        if (name === 'workflow/agent-start') childIds.push((payload[1] as { childId: string }).childId)
+      })
+    }
+
+    const run = ctx.workflows.start({ script: SCRIPT, meta: META, parent: parentHandle.agent })
+    const result = await run.result
+    await run.dispose()
+
+    expect(result.stopReason).toBe('completed')
+    expect(result.agentsStarted).toBe(2)
+    const value = result.value as { prose: string; containsFour: boolean | null }
+    // World checks: the prose child really answered (a real completion), and
+    // the structured child judged it against the REAL schema-forced tool.
+    expect(value.prose.length).toBeGreaterThan(0)
+    expect(value.containsFour).toBe(true)
+
+    expect(events[0]).toBe('workflow/start')
+    expect(events.at(-1)).toBe('workflow/end')
+    expect(events.filter(name => name === 'workflow/phase').length).toBe(2)
+    expect(events.filter(name => name === 'workflow/agent-start').length).toBe(2)
+    expect(childIds.length).toBe(2)
+    // The children were disposed to quiescence after collection.
+    for (const childId of childIds) {
+      expect(ctx.agents.get(AgentId(childId))).toBeUndefined()
+    }
+    await parentHandle.dispose()
+  }, 240_000)
+})

packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts

@@ -0,0 +1,904 @@
+import { describe, expect, it, vi } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import type { SubagentCapabilities, SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+import type { WorkflowMeta, WorkflowResult, WorkflowResultInfo, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow'
+import * as workerEngineModule from '../src/index.ts'
+import WorkerWorkflowEngine, { type Config } from '../src/index.ts'
+
+/** A minimal parent stand-in: the engine only threads it through to the provider. */
+function fakeParent(): Agent {
+  return { id: AgentId('workflow-parent'), options: {} } as unknown as Agent
+}
+
+/** The vm-context escape hatch, spelled once: real Worker tests use it to make the WORKER misbehave. */
+const ESCAPE = "globalThis.constructor.constructor('return process')()"
+
+/** One controllable child run: the test (or auto mode) settles it. */
+interface ControlledRun {
+  request: SubagentStartRequest
+  settle(result: SubagentResult): void
+  cancelled: string | undefined
+  disposed: boolean
+  disposeCalls: number
+}
+
+/**
+ * A scripted in-test provider over the REAL SubagentService registry: `auto`
+ * settles each run via the reply function on a microtask; `manual` piles runs
+ * up in `runs` for the test to settle. A run aborts (settles `aborted`) when
+ * the request signal fires, like the real in-process backends.
+ */
+class StubProvider implements SubagentProvider {
+  readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true }
+  readonly inheritsParentContext = false
+  readonly runs: ControlledRun[] = []
+
+  constructor(
+    readonly name: string,
+    private readonly reply?: (request: SubagentStartRequest, index: number) => SubagentResult,
+    private readonly disposeDelayMs = 0,
+  ) {}
+
+  start(request: SubagentStartRequest): SubagentRun {
+    let settle!: (result: SubagentResult) => void
+    const result = new Promise<SubagentResult>((resolve) => { settle = resolve })
+    const controlled: ControlledRun = { request, settle, cancelled: undefined, disposed: false, disposeCalls: 0 }
+    this.runs.push(controlled)
+    const index = this.runs.length - 1
+    request.signal?.addEventListener('abort', () => { settle({ output: [], stopReason: 'aborted' }) }, { once: true })
+    if (this.reply) {
+      const reply = this.reply
+      queueMicrotask(() => { settle(reply(request, index)) })
+    }
+    return {
+      id: AgentId(`stub-child-${index}`),
+      result,
+      cancel: (reason?: string) => {
+        controlled.cancelled = reason ?? 'cancelled'
+        settle({ output: [], stopReason: 'aborted' })
+      },
+      dispose: () => {
+        controlled.disposeCalls += 1
+        if (this.disposeDelayMs === 0) {
+          controlled.disposed = true
+          return Promise.resolve()
+        }
+        return new Promise<void>((resolve) => {
+          setTimeout(() => {
+            controlled.disposed = true
+            resolve()
+          }, this.disposeDelayMs)
+        })
+      },
+    }
+  }
+}
+
+/** Text-reply helper for auto providers. */
+function text(reply: string): SubagentResult {
+  return { output: [{ type: 'text', text: reply }], stopReason: 'completed' }
+}
+
+interface SetupOptions {
+  config?: Config
+  reply?: (request: SubagentStartRequest, index: number) => SubagentResult
+  manual?: boolean
+  disposeDelayMs?: number
+}
+
+async function setup(options?: SetupOptions) {
+  const ctx = new Context()
+  await ctx.plugin(SubagentService)
+  const provider = new StubProvider(
+    'stub',
+    options?.manual ? undefined : options?.reply ?? (() => text('stub reply')),
+    options?.disposeDelayMs ?? 0,
+  )
+  ctx.subagents.registerProvider(provider)
+  // A fixed concurrency ceiling: the auto-resolved default is machine-derived
+  // (cores - 2, floored at 1), so tests that expect N children in flight
+  // would wedge on small CI runners.
+  await ctx.plugin(WorkerWorkflowEngine, { provider: 'stub', maxConcurrentAgents: 8, ...options?.config })
+  return { ctx, provider, parent: fakeParent() }
+}
+
+/** The standard test meta plus a body, spread into a start request. */
+function scripted(body: string, metaExtra?: Partial<WorkflowMeta>): { script: string; meta: WorkflowMeta } {
+  return { script: body, meta: { name: 'test-flow', description: 'a test workflow', ...metaExtra } }
+}
+
+/** Start + await one run, disposing on the way out. */
+async function run(ctx: Context, parent: Agent, source: { script: string; meta: WorkflowMeta }, args?: unknown): Promise<WorkflowResult> {
+  const handle = ctx.workflows.start({ ...source, parent, ...args !== undefined ? { args } : {} })
+  try {
+    return await handle.result
+  } finally {
+    await handle.dispose()
+  }
+}
+
+describe('dsh-workflow-workerthread', () => {
+  describe('script execution over a real worker thread', () => {
+    it('runs a script end-to-end: agent() text results, phases, log, args, return value, events', async () => {
+      const { ctx, parent, provider } = await setup({ reply: (_request, index) => text(`answer-${index}`) })
+      const events: [string, unknown[]][] = []
+      for (const name of ['workflow/start', 'workflow/phase', 'workflow/log', 'workflow/agent-start', 'workflow/agent-end', 'workflow/end'] as const) {
+        ctx.on(name, (...payload: unknown[]) => { events.push([name, payload]) })
+      }
+      const result = await run(ctx, parent, scripted(`
+        phase('Scan')
+        log('starting with ' + args.files.length + ' files')
+        const answers = await pipeline(args.files, (prev, item) => agent('read ' + item))
+        phase('Report')
+        return { answers, count: args.files.length }
+      `, { phases: [{ title: 'Scan' }, { title: 'Report' }] }), { files: ['a.ts', 'b.ts'] })
+
+      expect(result.stopReason).toBe('completed')
+      expect(result.agentsStarted).toBe(2)
+      expect(result.value).toEqual({ answers: ['answer-0', 'answer-1'], count: 2 })
+      expect(provider.runs.every(r => r.disposed)).toBe(true)
+
+      const names = events.map(([name]) => name)
+      expect(names[0]).toBe('workflow/start')
+      expect(names).toContain('workflow/phase')
+      expect(names).toContain('workflow/log')
+      expect(names.at(-1)).toBe('workflow/end')
+      const info = events[0]![1][0] as WorkflowRunInfo
+      expect(info.meta.name).toBe('test-flow')
+      const end = events.at(-1)![1][1] as Record<string, unknown>
+      expect(end).toEqual({ stopReason: 'completed', agentsStarted: 2 })
+      expect('value' in end).toBe(false)
+    })
+
+    it('agent({schema, model}) forwards outputSchema and agentOptions to the provider across the thread', async () => {
+      const { ctx, parent, provider } = await setup({
+        reply: () => ({ output: [], structured: { files: ['x.ts', 'y.ts'] }, stopReason: 'completed' }),
+      })
+      const result = await run(ctx, parent, scripted(`
+        const found = await agent('list files', { model: 'deepseek-v4-pro', schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } }, required: ['files'] } })
+        return { first: found.files[0], count: found.files.length }
+      `))
+      expect(result.value).toEqual({ first: 'x.ts', count: 2 })
+      expect(provider.runs[0]!.request.outputSchema).toEqual({
+        type: 'object',
+        properties: { files: { type: 'array', items: { type: 'string' } } },
+        required: ['files'],
+      })
+      expect(provider.runs[0]!.request.agentOptions).toEqual({ model: 'deepseek-v4-pro' })
+      expect(provider.runs[0]!.request.parent).toBeDefined()
+    })
+
+    it('a fatal hook error inside the worker kills the script and reports the error', async () => {
+      const { ctx, parent } = await setup()
+      const result = await run(ctx, parent, scripted("return await parallel([() => agent('x', { isolation: 'worktree' })])"))
+      expect(result.stopReason).toBe('error')
+      expect(result.error).toContain('"isolation" is deferred')
+    })
+
+    it('a provider start failure crosses back as a fatal AGENT_START error', async () => {
+      const { ctx, parent } = await setup({ config: { provider: 'nonexistent' } })
+      const result = await run(ctx, parent, scripted("return await pipeline([1], () => agent('p'))"))
+      expect(result.stopReason).toBe('error')
+      expect(result.error).toContain('agent() could not start a child')
+    })
+
+    it('a child result REJECTION crosses back as a fatal AGENT_RESULT error (a broken provider is not a failed child)', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      const provider: SubagentProvider = {
+        name: 'rejecting',
+        capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
+        start: () => ({
+          id: AgentId('reject-child'),
+          result: Promise.reject(new Error('backend exploded')),
+          cancel: () => { /* nothing in flight */ },
+          dispose: () => Promise.resolve(),
+        }),
+      }
+      ctx.subagents.registerProvider(provider)
+      await ctx.plugin(WorkerWorkflowEngine, { provider: 'rejecting', maxConcurrentAgents: 2 })
+      const result = await run(ctx, fakeParent(), scripted(`
+        try { await agent('p'); return 'unreachable' } catch (e) { return { name: e.name, code: e.code, fatal: e.fatal, message: e.message } }
+      `))
+      expect(result.value).toMatchObject({ name: 'WorkflowError', code: 'AGENT_RESULT', fatal: true })
+      expect((result.value as { message: string }).message).toContain('backend exploded')
+    })
+
+    it('a child whose dispose() rejects cannot wedge the script (the host acks anyway)', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      const provider: SubagentProvider = {
+        name: 'bad-dispose',
+        capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
+        start: () => ({
+          id: AgentId('bad-dispose-child'),
+          result: Promise.resolve({ output: [{ type: 'text', text: 'fine' }], stopReason: 'completed' }),
+          cancel: () => { /* settled already */ },
+          dispose: () => Promise.reject(new Error('dispose exploded')),
+        }),
+      }
+      ctx.subagents.registerProvider(provider)
+      await ctx.plugin(WorkerWorkflowEngine, { provider: 'bad-dispose', maxConcurrentAgents: 2 })
+      const result = await run(ctx, fakeParent(), scripted("return await agent('p')"))
+      expect(result.stopReason).toBe('completed')
+      expect(result.value).toBe('fine')
+    })
+
+    it('a child dispose() rejecting an UNRENDERABLE value still acks — the containment warn is total', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      const provider: SubagentProvider = {
+        name: 'coercion-trap-dispose',
+        capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
+        start: () => ({
+          id: AgentId('trap-child'),
+          result: Promise.resolve({ output: [{ type: 'text', text: 'fine' }], stopReason: 'completed' }),
+          cancel: () => { /* settled already */ },
+          // The rejection VALUE's own coercion throws: a warn built with bare
+          // String(error) would itself throw, skipping the ChildDisposed ack
+          // and wedging the script's finally until the grace/terminate path.
+          // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- the non-Error rejection IS the scenario under test
+          dispose: () => Promise.reject({ toString: () => { throw new Error('coercion trap') } }),
+        }),
+      }
+      ctx.subagents.registerProvider(provider)
+      await ctx.plugin(WorkerWorkflowEngine, { provider: 'coercion-trap-dispose', maxConcurrentAgents: 2 })
+      const result = await run(ctx, fakeParent(), scripted("return await agent('p')"))
+      expect(result.stopReason).toBe('completed')
+      expect(result.value).toBe('fine')
+    })
+
+    it('the worker spawns with an EMPTY environment: an escaped script finds no ambient credentials', async () => {
+      const { ctx, parent } = await setup()
+      // A canary in the HARNESS process's env: with an inherited environment
+      // the escape below would read it back (exactly how DEEPSEEK_API_KEY
+      // would leak); env: {} in the spawn options is what keeps it out.
+      process.env.WORKFLOW_ENV_CANARY = 'leak me'
+      try {
+        const result = await run(ctx, parent, scripted(`
+          const proc = ${ESCAPE}
+          return { canary: proc.env.WORKFLOW_ENV_CANARY ?? null, keys: Object.keys(proc.env).length }
+        `))
+        expect(result.stopReason).toBe('completed')
+        expect(result.value).toEqual({ canary: null, keys: 0 })
+      } finally {
+        delete process.env.WORKFLOW_ENV_CANARY
+      }
+    })
+
+    it('the unbuilt worker forwards exactly TSX_TSCONFIG_PATH through the scrub: the paths-map pin survives, secrets do not', async () => {
+      const { ctx, parent } = await setup()
+      // The ACP snapshot harness runs the parent with its cwd OUTSIDE the
+      // repo and pins the repo tsconfig through this variable; the worker
+      // must inherit the pin (or its dsh-* imports silently resolve to
+      // unbuilt lib/ bundles) while every other variable stays scrubbed.
+      const tsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+      process.env.TSX_TSCONFIG_PATH = tsconfig
+      process.env.WORKFLOW_ENV_CANARY = 'leak me'
+      try {
+        const result = await run(ctx, parent, scripted(`
+          const proc = ${ESCAPE}
+          return { keys: Object.keys(proc.env), tsconfig: proc.env.TSX_TSCONFIG_PATH }
+        `))
+        expect(result.stopReason).toBe('completed')
+        expect(result.value).toEqual({ keys: ['TSX_TSCONFIG_PATH'], tsconfig })
+      } finally {
+        delete process.env.TSX_TSCONFIG_PATH
+        delete process.env.WORKFLOW_ENV_CANARY
+      }
+    })
+  })
+
+  describe('lifecycle: parse errors, cancellation, termination, disposal', () => {
+    it('start() throws synchronously for invalid meta data or an unparseable body (host-side pre-checks)', async () => {
+      const { ctx, parent } = await setup()
+      // Meta is DATA — shape violations reject loud, every one named.
+      expect(() => ctx.workflows.start({ script: 'return 1', meta: { name: '', description: 'd' }, parent })).toThrow(/meta\.name must be a non-empty string/)
+      expect(() => ctx.workflows.start({ script: 'return 1', meta: { name: 'x', description: 'd', extra: 1 } as unknown as WorkflowMeta, parent })).toThrow(/META_INVALID|not a recognized field/)
+      expect(() => ctx.workflows.start({ ...scripted('return ((('), parent })).toThrow(/does not parse/)
+      // The likeliest authoring slip — a Claude Code-style meta header in the
+      // body — gets a pointed message, not a bare SyntaxError.
+      expect(() => ctx.workflows.start({ ...scripted("export const meta = { name: 'x', description: 'd' }\nreturn 1"), parent })).toThrow(/meta rides the `meta` request field/)
+    })
+
+    it('cancel() aborts in-flight children (signal AND cancel RPC) and settles the run cancelled', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true })
+      const ends: unknown[] = []
+      ctx.on('workflow/agent-end', (_info, agent) => { ends.push(agent) })
+      const runEnds: WorkflowResultInfo[] = []
+      ctx.on('workflow/end', (_info, result) => { runEnds.push(result) })
+      const handle = ctx.workflows.start({ ...scripted("return await agent('long job')"), parent })
+      await vi.waitFor(() => { expect(provider.runs.length).toBe(1) })
+      handle.cancel('user stopped it')
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      expect(result.error).toContain('user stopped it')
+      await handle.dispose()
+      expect(provider.runs[0]!.disposed).toBe(true)
+      expect(ends).toEqual([expect.objectContaining({ seq: 1, outcome: 'cancelled' })])
+      // workflow/end is an observer's only death signal: it fires for a
+      // cancelled run too, mirroring the settled outcome data.
+      expect(runEnds).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: result.agentsStarted }])
+    })
+
+    it('an already-aborted request signal cancels before the body ever runs (the go handshake holds it)', async () => {
+      const { ctx, parent, provider } = await setup()
+      const controller = new AbortController()
+      controller.abort()
+      const logs: string[] = []
+      ctx.on('workflow/log', (_info, message) => { logs.push(message) })
+      const handle = ctx.workflows.start({ ...scripted("log('ran')\nreturn 123"), parent, signal: controller.signal })
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      expect(result.value).toBeNull()
+      expect(logs).toEqual([])
+      expect(provider.runs.length).toBe(0)
+      await handle.dispose()
+    })
+
+    it('cancel() right after start() cancels before the body runs; the signal aborting mid-run cancels like cancel()', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true })
+      const first = ctx.workflows.start({ ...scripted("return await agent('never')"), parent })
+      // No-reason cancel: the canonical default reason must ride the result.
+      first.cancel()
+      const firstResult = await first.result
+      expect(firstResult.stopReason).toBe('cancelled')
+      expect(firstResult.error).toContain('workflow cancelled')
+      expect(provider.runs.length).toBe(0)
+      await first.dispose()
+
+      const controller = new AbortController()
+      const second = ctx.workflows.start({ ...scripted("return await agent('job')"), parent, signal: controller.signal })
+      await vi.waitFor(() => { expect(provider.runs.length).toBe(1) })
+      controller.abort()
+      expect((await second.result).stopReason).toBe('cancelled')
+      await second.dispose()
+    })
+
+    it('a child-start racing the host cancel is refused: no child starts after cancellation', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true })
+      // Cancel from INSIDE the log listener: the worker has already posted
+      // its child-start (queued right behind the log message), so the host
+      // processes it with cancelReason set — the refusal arm no real-world
+      // timing can hit reliably. (The closure runs only after `handle` below
+      // is initialized — the listener fires on the worker's first message.)
+      ctx.on('workflow/log', () => { handle.cancel('cancelled from the log listener') })
+      const handle = ctx.workflows.start({ ...scripted("log('mark')\nreturn await agent('late')"), parent })
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      expect(provider.runs.length).toBe(0)
+      await handle.dispose()
+    })
+
+    it('post-cancel narration is suppressed host-side, and completion racing a cancel reports cancelled', async () => {
+      const { ctx, parent } = await setup()
+      const narration: string[] = []
+      ctx.on('workflow/log', (_info, message) => { narration.push(message) })
+      ctx.on('workflow/phase', (_info, title) => { narration.push(`phase:${title}`) })
+      const handle = ctx.workflows.start({
+        // The sync spin keeps the worker's loop busy so the cancel message
+        // cannot be processed before the script settles `completed` — the
+        // worker posts a completed result that must LOSE to the in-flight
+        // host cancellation. The trailing narration exercises host-side
+        // suppression: posted pre-cancel-processing worker-side, arriving
+        // post-cancel host-side.
+        ...scripted(`
+          log('started')
+          const end = Date.now() + 1000
+          while (Date.now() < end) {}
+          phase('late phase')
+          log('late log')
+          return 'done'
+        `),
+        parent,
+      })
+      await vi.waitFor(() => { expect(narration).toContain('started') })
+      handle.cancel('raced the completion')
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      expect(result.error).toContain('raced the completion')
+      expect(narration).toEqual(['started'])
+      await handle.dispose()
+    }, 15_000)
+
+    it('cancel() force-settles a script parked on a promise no hook owns, and TERMINATES its worker', async () => {
+      const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 50 } })
+      const runEnds: WorkflowResultInfo[] = []
+      ctx.on('workflow/end', (_info, result) => { runEnds.push(result) })
+      const handle = ctx.workflows.start({
+        ...scripted("await new Promise(() => {})\nreturn 'unreachable'"),
+        parent,
+      })
+      handle.cancel('user aborted')
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      expect(result.error).toContain('user aborted')
+      // The grace force-settle fires workflow/end exactly like an ordinary
+      // settlement — a terminated script's death still reaches observers.
+      expect(runEnds).toEqual([{ stopReason: 'cancelled', error: result.error, agentsStarted: 0 }])
+      await handle.dispose()
+    })
+
+    it('dispose() on a stuck script returns within the grace instead of hanging (result settles cancelled)', async () => {
+      const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 50 } })
+      const handle = ctx.workflows.start({
+        ...scripted("await new Promise(() => {})\nreturn 'unreachable'"),
+        parent,
+      })
+      const before = Date.now()
+      await handle.dispose()
+      expect(Date.now() - before).toBeLessThan(2000)
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+    })
+
+    it('dispose() is idempotent and settles cleanly after a completed run', async () => {
+      const { ctx, parent } = await setup()
+      const handle = ctx.workflows.start({ ...scripted('return 1'), parent })
+      await handle.result
+      await handle.dispose()
+      await handle.dispose()
+    })
+
+    it('a settled run arms NO grace timer: disposing a completed run must not pin it for disposeGraceMs', async () => {
+      // A distinctive grace so the spy can tell the cancel-path grace timer
+      // apart from every other timeout in flight.
+      const GRACE = 44_444
+      const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: GRACE } })
+      const handle = ctx.workflows.start({ ...scripted('return 1'), parent })
+      await handle.result
+      const spy = vi.spyOn(globalThis, 'setTimeout')
+      try {
+        await handle.dispose()
+        // dispose()'s own bounded-wait sleep is the ONLY grace-sized timer
+        // allowed here; before the settled guard, cancel() armed a second one
+        // that nothing would ever clear (the run was already settled), keeping
+        // the WorkerRun/Worker closure alive until the grace expired.
+        const graceTimers = spy.mock.calls.filter(call => call[1] === GRACE)
+        expect(graceTimers.length).toBe(1)
+      } finally {
+        spy.mockRestore()
+      }
+    })
+
+    it('strays: children fired without await are aborted once the script settles, and dispose() waits for their disposal', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true, disposeDelayMs: 40 })
+      const handle = ctx.workflows.start({
+        ...scripted(`
+          agent('stray')
+          return 'done without awaiting'
+        `),
+        parent,
+      })
+      const result = await handle.result
+      expect(result.stopReason).toBe('completed')
+      await vi.waitFor(() => { expect(provider.runs.length).toBe(1) })
+      await handle.dispose()
+      // Not a waitFor: by the time dispose() returns, the slow child disposal
+      // must already be complete (host-side registry quiescence).
+      expect(provider.runs[0]!.disposed).toBe(true)
+    })
+
+    it('the settle-reap fires the request signal too: a provider honoring ONLY the signal winds its stray down promptly', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      const aborted: string[] = []
+      const provider: SubagentProvider = {
+        name: 'signal-only',
+        capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
+        start: (request) => {
+          let settle!: (result: SubagentResult) => void
+          const result = new Promise<SubagentResult>((resolve) => { settle = resolve })
+          request.signal?.addEventListener('abort', () => {
+            aborted.push(String(request.signal?.reason))
+            settle({ output: [], stopReason: 'aborted' })
+          }, { once: true })
+          return {
+            id: AgentId('signal-only-child'),
+            result,
+            // The seam leaves a provider free to honor EITHER cancel channel;
+            // this one deliberately ignores run.cancel() — only the request
+            // signal can wind it down.
+            cancel: () => { /* signal-only by design */ },
+            dispose: () => Promise.resolve(),
+          }
+        },
+      }
+      ctx.subagents.registerProvider(provider)
+      await ctx.plugin(WorkerWorkflowEngine, { provider: 'signal-only', maxConcurrentAgents: 2 })
+      const handle = ctx.workflows.start({
+        ...scripted(`
+          agent('stray, never awaited')
+          return 'done'
+        `),
+        parent: fakeParent(),
+      })
+      const result = await handle.result
+      expect(result.stopReason).toBe('completed')
+      // BEFORE dispose(): the settlement itself must have aborted the signal —
+      // without it this child would stay live until dispose's terminate.
+      await vi.waitFor(() => { expect(aborted).toEqual(['workflow settled']) })
+      await handle.dispose()
+    })
+
+    it("cancel() drives each child's explicit cancel() host-side: a wedged worker cannot delay it", async () => {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      let starts = 0
+      const cancelled: string[] = []
+      const provider: SubagentProvider = {
+        name: 'cancel-only',
+        capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
+        start: () => {
+          starts += 1
+          return {
+            id: AgentId('cancel-only-child'),
+            result: new Promise(() => { /* only cancel() ends this child */ }),
+            // Deliberately ignores the request signal — the seam leaves a
+            // provider free to honor ONLY the explicit cancel() channel.
+            cancel: (reason?: string) => { cancelled.push(reason ?? 'cancelled') },
+            dispose: () => Promise.resolve(),
+          }
+        },
+      }
+      ctx.subagents.registerProvider(provider)
+      // A deliberately huge grace: if only the grace/terminate reap could
+      // reach this child, the assertion below would time out first.
+      await ctx.plugin(WorkerWorkflowEngine, { provider: 'cancel-only', maxConcurrentAgents: 2, disposeGraceMs: 30_000 })
+      const handle = ctx.workflows.start({
+        // The stray child's start RPC reaches the host, then the script wedges
+        // its own worker in a synchronous spin: the worker cannot process the
+        // Cancel message, so it can relay NO ChildCancel RPC — only the host's
+        // own children loop can deliver the explicit cancel in time. The
+        // microtask yields let the agent() continuation POST its child-start
+        // before the spin seizes the worker's loop (the posted message needs
+        // no further worker-loop turns to reach the host).
+        ...scripted(`
+          agent('wedged child')
+          for (let i = 0; i < 20; i++) await null
+          const end = Date.now() + 1500
+          while (Date.now() < end) {}
+          return 'raced'
+        `),
+        parent: fakeParent(),
+      })
+      await vi.waitFor(() => { expect(starts).toBe(1) })
+      handle.cancel('stop now')
+      await vi.waitFor(() => { expect(cancelled).toEqual(['stop now']) }, { timeout: 800 })
+      // The wedged worker's own completion loses to the in-flight cancel.
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      await handle.dispose()
+    }, 15_000)
+
+    it('dispose() on a wedged worker host-drives child disposal inside the grace: it returns with the children DISPOSED, not with their teardown still in flight', async () => {
+      const { ctx, parent, provider } = await setup({
+        manual: true,
+        disposeDelayMs: 40,
+        config: { provider: 'stub', maxConcurrentAgents: 8, disposeGraceMs: 400 },
+      })
+      const handle = ctx.workflows.start({
+        // Same shape as the wedged-cancel test above: the child's start RPC
+        // reaches the host, then the script seizes its worker's loop, so the
+        // worker can relay NO dispose RPC — the host's own dispose() drive is
+        // the only thing that can start (and finish) this child's disposal
+        // before the grace runs out.
+        ...scripted(`
+          agent('wedged child')
+          for (let i = 0; i < 20; i++) await null
+          const end = Date.now() + 1500
+          while (Date.now() < end) {}
+          return 'raced'
+        `),
+        parent,
+      })
+      await vi.waitFor(() => { expect(provider.runs.length).toBe(1) })
+      const before = Date.now()
+      await handle.dispose()
+      // Bounded by the grace (plus the terminate), never by the 1.5s spin.
+      expect(Date.now() - before).toBeLessThan(1200)
+      // Not a waitFor: dispose() resolving IS the quiescence claim — the slow
+      // child disposal must be complete, not merely started (before the
+      // host-driven drive, disposal only STARTED at the post-terminate reap,
+      // so dispose() returned with it still in flight).
+      expect(provider.runs[0]!.disposed).toBe(true)
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+    }, 15_000)
+
+    it('a live child disposed by the dispose() drive is disposed ONCE, and the worker\'s late dispose RPC still gets its ack (the script settles, not the grace)', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true })
+      const handle = ctx.workflows.start({
+        ...scripted(`
+          await agent('long child')
+          return 'unreachable'
+        `),
+        parent,
+      })
+      await vi.waitFor(() => { expect(provider.runs.length).toBe(1) })
+      const handleDispose = handle.dispose()
+      const result = await handle.result
+      // The script itself settled (the wrapper's own dispose RPC found the
+      // child already reaped host-side and was acked) — a missing ack would
+      // wedge the wrapper's finally until the 5s default grace force-settle.
+      expect(result.stopReason).toBe('cancelled')
+      expect(result.error).toContain('workflow disposed')
+      await handleDispose
+      expect(provider.runs[0]!.disposed).toBe(true)
+      // The memo: the host drive and the worker's RPC share one disposal.
+      expect(provider.runs[0]!.disposeCalls).toBe(1)
+    })
+
+    it('the grace force-settle pairs every stranded start: a host-synthesized cancelled agent-end lands before workflow/end', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true, config: { provider: 'stub', maxConcurrentAgents: 8, disposeGraceMs: 300 } })
+      const ends: { seq: number; outcome: string }[] = []
+      const order: string[] = []
+      ctx.on('workflow/agent-start', (_info, agent) => { order.push(`start:${agent.seq}`) })
+      ctx.on('workflow/agent-end', (_info, agent) => {
+        ends.push({ seq: agent.seq, outcome: agent.outcome })
+        order.push(`end:${agent.seq}`)
+      })
+      ctx.on('workflow/end', () => { order.push('run-end') })
+      const handle = ctx.workflows.start({
+        // 'slow' starts and its agent-start crosses to observers (the awaited
+        // 'fast' call keeps the worker loop turning), then the script seizes
+        // the loop: the wedged worker can never author slow's agent-end —
+        // only the host's ledger can close the pair.
+        ...scripted(`
+          const p = agent('slow')
+          await agent('fast')
+          const end = Date.now() + 1500
+          while (Date.now() < end) {}
+          return 'raced'
+        `),
+        parent,
+      })
+      await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) })
+      const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')!
+      fast.settle(text('fast done'))
+      handle.cancel('stop now')
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      // fast's end is the worker's own report; slow's is host-synthesized at
+      // the force-settle — exactly one end per started seq, no third event.
+      expect(ends).toEqual([
+        { seq: 2, outcome: 'completed' },
+        { seq: 1, outcome: 'cancelled' },
+      ])
+      // Both ends reached observers BEFORE workflow/end: a progress consumer
+      // can finalize its state at run-end without dangling agents.
+      expect(order.indexOf('run-end')).toBe(order.length - 1)
+      await handle.dispose()
+    }, 15_000)
+
+    it('graceful cancellation keeps pairing worker-authored: exactly one agent-end per start, nothing synthesized on top', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true })
+      const ends: { seq: number; outcome: string }[] = []
+      const order: string[] = []
+      ctx.on('workflow/agent-end', (_info, agent) => {
+        ends.push({ seq: agent.seq, outcome: agent.outcome })
+        order.push(`end:${agent.seq}`)
+      })
+      ctx.on('workflow/end', () => { order.push('run-end') })
+      const handle = ctx.workflows.start({
+        ...scripted("await parallel([() => agent('a'), () => agent('b')])\nreturn 'unreachable'"),
+        parent,
+      })
+      await vi.waitFor(() => { expect(provider.runs.length).toBe(2) })
+      handle.cancel('user stop')
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      // The live worker reported both pairs itself; the ledger must not add
+      // a synthesized duplicate on any path that settles inside the grace.
+      expect(ends.map(end => end.outcome)).toEqual(['cancelled', 'cancelled'])
+      expect(new Set(ends.map(end => end.seq)).size).toBe(2)
+      expect(order.indexOf('run-end')).toBe(order.length - 1)
+      await handle.dispose()
+    })
+  })
+
+  describe('worker death', () => {
+    it('a worker that exits before settling reports an error result and reaps its children', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      // The child's dispose() REJECTS on top of the worker death: the reap
+      // must contain it (warn, not crash) while still emptying the registry.
+      const cancelled: string[] = []
+      const provider: SubagentProvider = {
+        name: 'doomed',
+        capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
+        start: () => ({
+          id: AgentId('doomed-child'),
+          result: new Promise(() => { /* never settles; the reap is the teardown */ }),
+          cancel: (reason?: string) => { cancelled.push(reason ?? 'cancelled') },
+          dispose: () => Promise.reject(new Error('dispose exploded during reap')),
+        }),
+      }
+      ctx.subagents.registerProvider(provider)
+      await ctx.plugin(WorkerWorkflowEngine, { provider: 'doomed', maxConcurrentAgents: 2 })
+      const runEnds: WorkflowResultInfo[] = []
+      ctx.on('workflow/end', (_info, result) => { runEnds.push(result) })
+      const handle = ctx.workflows.start({
+        // The stray child's start RPC reaches the host, then the script kills
+        // its own worker through the documented vm escape — the host must
+        // settle `error` with the exit diagnostics and wind the child down.
+        ...scripted(`
+          agent('doomed')
+          const proc = ${ESCAPE}
+          const st = globalThis.constructor.constructor('return setTimeout')()
+          await new Promise(resolve => st(resolve, 200))
+          proc.exit(7)
+        `),
+        parent: fakeParent(),
+      })
+      const result = await handle.result
+      expect(result.stopReason).toBe('error')
+      expect(result.error).toContain('exit code 7')
+      expect(result.agentsStarted).toBe(1)
+      // A worker death is a stop reason like any other: workflow/end fires
+      // with the error outcome — for a bus observer it is the only obituary.
+      expect(runEnds).toEqual([{ stopReason: 'error', error: result.error, agentsStarted: 1 }])
+      await vi.waitFor(() => { expect(cancelled.length).toBe(1) })
+      await handle.dispose()
+    }, 15_000)
+
+    it('an uncaught exception inside the worker surfaces as an error result and reaps the in-flight child', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true })
+      const handle = ctx.workflows.start({
+        ...scripted(`
+          agent('in flight when the worker dies')
+          const proc = ${ESCAPE}
+          const st = globalThis.constructor.constructor('return setTimeout')()
+          await new Promise(resolve => st(resolve, 200))
+          proc.nextTick(() => { throw new Error('worker blew up') })
+          await new Promise(() => {})
+        `),
+        parent,
+      })
+      const result = await handle.result
+      expect(result.stopReason).toBe('error')
+      expect(result.error).toContain('worker blew up')
+      // The reap wound the stray child down (cancel + a CLEAN dispose).
+      await vi.waitFor(() => {
+        expect(provider.runs.length).toBe(1)
+        expect(provider.runs[0]!.disposed).toBe(true)
+      })
+      await handle.dispose()
+    }, 15_000)
+
+    it('a worker death pairs every stranded start: the synthesized cancelled agent-end precedes the error workflow/end', async () => {
+      const { ctx, parent, provider } = await setup({ manual: true })
+      const ends: { seq: number; outcome: string }[] = []
+      const order: string[] = []
+      ctx.on('workflow/agent-start', (_info, agent) => { order.push(`start:${agent.seq}`) })
+      ctx.on('workflow/agent-end', (_info, agent) => {
+        ends.push({ seq: agent.seq, outcome: agent.outcome })
+        order.push(`end:${agent.seq}`)
+      })
+      ctx.on('workflow/end', () => { order.push('run-end') })
+      const handle = ctx.workflows.start({
+        // Same choreography as the force-settle pairing test, but the worker
+        // DIES (the documented vm escape) instead of being terminated: the
+        // exit path must close slow's pair from the ledger too. The escaped
+        // setTimeout lets the already-posted messages flush before the kill.
+        ...scripted(`
+          const p = agent('slow')
+          await agent('fast')
+          const proc = ${ESCAPE}
+          const st = globalThis.constructor.constructor('return setTimeout')()
+          await new Promise(resolve => st(resolve, 150))
+          proc.exit(7)
+        `),
+        parent,
+      })
+      await vi.waitFor(() => { expect(order.filter(entry => entry.startsWith('start:')).length).toBe(2) })
+      const fast = provider.runs.find(run => (run.request.prompt[0] as { text?: string }).text === 'fast')!
+      fast.settle(text('fast done'))
+      const result = await handle.result
+      expect(result.stopReason).toBe('error')
+      expect(result.error).toContain('exit code 7')
+      expect(ends).toEqual([
+        { seq: 2, outcome: 'completed' },
+        { seq: 1, outcome: 'cancelled' },
+      ])
+      expect(order.indexOf('run-end')).toBe(order.length - 1)
+      await handle.dispose()
+    }, 15_000)
+
+    it('a dispose ack racing the worker death is dropped, not crashed (post after exit)', async () => {
+      // Slow child disposal: the ack resolves only AFTER the worker died, so
+      // it has nowhere to go and must be dropped silently (the workerGone
+      // guard in post()).
+      const { ctx, parent, provider } = await setup({ disposeDelayMs: 300 })
+      const handle = ctx.workflows.start({
+        // The STRAY child settles instantly, so its wrapper starts the slow
+        // host-side disposal concurrently while the script goes on to kill
+        // its own worker — the ack then resolves into a dead thread.
+        ...scripted(`
+          agent('stray, never awaited')
+          const proc = ${ESCAPE}
+          const st = globalThis.constructor.constructor('return setTimeout')()
+          await new Promise(resolve => st(resolve, 150))
+          proc.exit(5)
+        `),
+        parent,
+      })
+      const result = await handle.result
+      expect(result.stopReason).toBe('error')
+      expect(result.error).toContain('exit code 5')
+      await vi.waitFor(() => { expect(provider.runs[0]!.disposed).toBe(true) })
+      await handle.dispose()
+    }, 15_000)
+
+    it('a worker death AFTER a cancel reports cancelled, not error', async () => {
+      const { ctx, parent } = await setup({ config: { provider: 'stub', disposeGraceMs: 60_000 } })
+      const handle = ctx.workflows.start({
+        ...scripted(`
+          const proc = ${ESCAPE}
+          const st = globalThis.constructor.constructor('return setTimeout')()
+          log('armed')
+          await new Promise(resolve => st(resolve, 400))
+          proc.exit(3)
+        `),
+        parent,
+      })
+      const logs: string[] = []
+      ctx.on('workflow/log', (_info, message) => { logs.push(message) })
+      await vi.waitFor(() => { expect(logs).toContain('armed') })
+      handle.cancel('stop it')
+      // The grace is deliberately huge: only the worker's own death (exit 3,
+      // unreachable by the cancel — the script ignores hooks) settles this.
+      const result = await handle.result
+      expect(result.stopReason).toBe('cancelled')
+      expect(result.error).toContain('stop it')
+      await handle.dispose()
+    }, 15_000)
+  })
+
+  describe('service surface', () => {
+    it('run ids are unique per start; the run handle and event payloads hold SEPARATE meta clones', async () => {
+      const { ctx, parent } = await setup()
+      let eventMeta: WorkflowRunInfo | undefined
+      ctx.on('workflow/start', (info) => { eventMeta = info })
+      const first = ctx.workflows.start({ ...scripted('return 1'), parent })
+      const second = ctx.workflows.start({ ...scripted('return 2'), parent })
+      expect(first.id).not.toBe(second.id)
+      eventMeta!.meta.name = 'corrupted'
+      expect(second.meta.name).toBe('test-flow')
+      await Promise.all([first.result, second.result])
+      await first.dispose()
+      await second.dispose()
+    })
+
+    it('unregisters ctx.workflows when the engine fiber is disposed (HMR safety), and default config runs (auto concurrency)', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SubagentService)
+      const fiber = await ctx.plugin(WorkerWorkflowEngine, {})
+      expect(ctx.get('workflows')).toBeDefined()
+      // A zero-agent run through the DEFAULT config exercises the auto
+      // concurrency resolution (cores - 2, capped) in start().
+      const result = await run(ctx, fakeParent(), scripted('return 6 * 7'))
+      expect(result.value).toBe(42)
+      await fiber.dispose()
+      expect(ctx.get('workflows')).toBeUndefined()
+    })
+
+    it('has the class-plugin export shape (default = the engine service class)', () => {
+      expect(workerEngineModule.default).toBe(WorkerWorkflowEngine)
+      const loader = Object.create(Loader.prototype) as Loader
+      const unwrapped: unknown = loader.unwrapExports(workerEngineModule)
+      expect(unwrapped).toBe(WorkerWorkflowEngine)
+    })
+  })
+})

packages/workflow/workflow-workerthread/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../subagent/subagent"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../workflow"
+    }
+  ]
+}

packages/workflow/workflow-workerthread/tsdown.config.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * The engine ships two runtime entries: the engine service (index) and the
+ * worker-thread entry (worker) the engine spawns via `new Worker`. The
+ * entries are JS emitted by tsc under lib/types and are bundled as two
+ * single-entry passes so shared modules (realm, runtime, session) are inlined
+ * into each instead of split into a hash-named chunk (the worker entry must
+ * be a self-contained file the Worker constructor can load by path).
+ */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/worker.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])

packages/workflow/workflow/README.md

@@ -0,0 +1,29 @@
+# @deepseek-ai/dsh-workflow
+
+The **workflow seam** (`ctx.workflows`): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the [workflow family](../README.md): implementations subclass `WorkflowService` and register as the `workflows` service (one per context); [`dsh-workflow-workerthread`](../workflow-workerthread/README.md) (one worker thread per run) is the implementation, and [`dsh-tool-workflow`](../tool-workflow/README.md) is the model-facing consumer.
+
+## Service: `WorkflowService` (abstract)
+
+`start(request: WorkflowStartRequest): WorkflowRun` — parse and execute a script. Throws synchronously (`SCRIPT_PARSE`/`META_INVALID`) for a script that cannot begin; once a run is returned, its `result` NEVER rejects — every failure resolves with `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled, `result` settles within the implementation's bounded grace even if the script itself never settles (a consumer awaiting `result` must never be wedged past a cancellation). `dispose()` must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller. Runs are HOLDER-owned: the engine does not track its live runs, so disposing the engine's fiber mid-run leaves each run to its holder's teardown.
+
+The protected `emitWorkflowEvent` helper dispatches the `workflow/*` events with PER-LISTENER containment and PER-LISTENER payload snapshots (a throwing subscriber is logged, never propagated, and cannot starve later listeners; each subscriber gets its own clone of the payload, so mutating it corrupts neither the engine nor other listeners) — the same containment guarantee as the subagent seam's lifecycle emits.
+
+## Vocabulary
+
+- `WorkflowStartRequest` — `{ script, args?, parent: Agent, signal? }`. `parent` is REQUIRED: every child the script spawns is attributed to it. `args` must be plain host-realm JSON data.
+- `WorkflowMeta` / `WorkflowPhase` — the workflow's identity block, carried as plain JSON data on the start request (Claude Code meta vocabulary: required `name`/`description`, optional `whenToUse`/`phases`) and shape-validated by the engine.
+- `WorkflowRun` — `{ id, meta, result, cancel(reason?), dispose() }`; the consumer awaits `result` and MUST `dispose` on every path.
+- `WorkflowResult` — `{ value, stopReason: 'completed'|'cancelled'|'error', error?, agentsStarted }`; `value` is the script's materialized return (plain JSON data; `null` for no return).
+- `WorkflowError` — `HarnessError` with a `WorkflowErrorCode` and a `fatal` flag driving the combinator discipline: a fatal error (bad hook arguments, unsupported options/schemas, tripped caps, seam start failures, cancellation) always propagates through `parallel()`/`pipeline()` instead of dissolving into a per-item `null`. `isFatalWorkflowError(error)` is the catch-site predicate.
+
+## Events
+
+All observe-only emits carrying DATA SNAPSHOTS (`WorkflowRunInfo` = id + meta) — never the live `WorkflowRun`, so a listener cannot gain `cancel`/`dispose`; control stays with the `start()` caller:
+
+- `workflow/start`(info) / `workflow/end`(info, resultInfo) — run lifecycle; `resultInfo` deliberately omits the value.
+- `workflow/phase`(info, title) / `workflow/log`(info, message) — script narration.
+- `workflow/agent-start`(info, agent) / `workflow/agent-end`(info, agent + outcome) — one pair per `agent()` call that STARTED a child run (a call rejected at validation or caps, refused at start, or cancelled while queued for a slot emits no pair), correlated by `seq`.
+
+## Non-goals (this cut)
+
+Background collection, journaling/resume, saved workflows, nested `workflow()`, token budgets — see the [RFC's deferred section](../../../docs/rfc/implemented/feature/2026-07-05-dynamic-workflows.md).

packages/workflow/workflow/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-workflow",
+  "description": "Workflow capability seam: ctx.workflows service, run vocabulary, and workflow/* events",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/workflow/workflow/src/index.ts

@@ -0,0 +1,269 @@
+/**
+ * The workflow capability seam (`ctx.workflows`): an abstract service defining
+ * WHAT a workflow engine does — execute a model-written orchestration script
+ * that fans out subagents — without saying HOW. Implementations subclass
+ * {@link WorkflowService} and register as the `workflows` service (one
+ * implementation per context, cordis' standard duplicate-service behavior);
+ * the implementation is `@deepseek-ai/dsh-workflow-workerthread`, which runs each
+ * script in its own worker thread. Hardened engines (an isolated-vm or
+ * separate-process sandbox) swap in without touching the model-facing tool
+ * that consumes them (`@deepseek-ai/dsh-tool-workflow`).
+ *
+ * The `workflow/*` lifecycle events are OBSERVE-ONLY data snapshots: they
+ * carry {@link WorkflowRunInfo} (id + meta), never the live {@link WorkflowRun}
+ * — a listener must not gain `cancel`/`dispose`; control stays with the
+ * `start()` caller holding the run. Every emit is per-listener contained (a
+ * throwing subscriber is logged, never propagated) and every listener gets its
+ * own payload clone (mutating it corrupts nothing), so one bad observer can
+ * neither strand a live run, starve later listeners, nor poison another
+ * listener's view.
+ *
+ * @module @deepseek-ai/dsh-workflow
+ */
+
+import { Context, Service } from 'cordis'
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+import type {
+  WorkflowAgentEndInfo,
+  WorkflowAgentInfo,
+  WorkflowResultInfo,
+  WorkflowRun,
+  WorkflowRunInfo,
+  WorkflowStartRequest,
+} from './types.ts'
+
+export { WorkflowRunId } from './types.ts'
+export type {
+  WorkflowAgentEndInfo,
+  WorkflowAgentInfo,
+  WorkflowAgentOutcome,
+  WorkflowMeta,
+  WorkflowPhase,
+  WorkflowResult,
+  WorkflowResultInfo,
+  WorkflowRun,
+  WorkflowRunInfo,
+  WorkflowStartRequest,
+  WorkflowStopReason,
+} from './types.ts'
+
+declare module 'cordis' {
+  interface Context {
+    workflows: WorkflowService
+  }
+
+  interface Events {
+    /**
+     * A workflow run started — the script's meta block validated, the body
+     * about to execute. Paired with {@link Events['workflow/end']}.
+     * @param info - the run's identity snapshot (id + meta).
+     * @mode emit
+     */
+    'workflow/start'(info: WorkflowRunInfo): void
+    /**
+     * The script entered a phase (a `phase(title)` call) — progress grouping
+     * for observers; no execution semantics.
+     * @param info - the run's identity snapshot.
+     * @param title - the phase title, verbatim.
+     * @mode emit
+     */
+    'workflow/phase'(info: WorkflowRunInfo, title: string): void
+    /**
+     * The script emitted a narration line (a `log(message)` call).
+     * @param info - the run's identity snapshot.
+     * @param message - the logged message, verbatim.
+     * @mode emit
+     */
+    'workflow/log'(info: WorkflowRunInfo, message: string): void
+    /**
+     * One `agent()` call started a child run. Paired with
+     * {@link Events['workflow/agent-end']} by `agent.seq`.
+     * @param info - the run's identity snapshot.
+     * @param agent - the call's sequence number, label, phase, and child id.
+     * @mode emit
+     */
+    'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
+    /**
+     * One `agent()` call settled (clean result, child failure, or run
+     * cancellation). Paired with {@link Events['workflow/agent-start']} by
+     * `agent.seq`, exactly once per started call on every stop path — on an
+     * engine termination path (a worker killed past its grace) the end is
+     * engine-synthesized with outcome `'cancelled'`.
+     * @param info - the run's identity snapshot.
+     * @param agent - the call identity plus its outcome.
+     * @mode emit
+     */
+    'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
+    /**
+     * A workflow run settled (any stop reason). Fired when
+     * {@link WorkflowRun.result} resolves. Paired with
+     * {@link Events['workflow/start']}.
+     * @param info - the run's identity snapshot.
+     * @param result - the outcome data (stop reason, error, agent count) —
+     *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+     * @mode emit
+     */
+    'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
+  }
+}
+
+/** The full set of `workflow/*` event names {@link WorkflowService.emitWorkflowEvent} dispatches. */
+export type WorkflowEventName =
+  | 'workflow/start'
+  | 'workflow/phase'
+  | 'workflow/log'
+  | 'workflow/agent-start'
+  | 'workflow/agent-end'
+  | 'workflow/end'
+
+/**
+ * The workflow-seam error codes. Every one of these is FATAL when it reaches
+ * a script (see {@link WorkflowError.fatal}): the combinators re-throw it
+ * instead of dissolving it into an ordinary per-item `null`.
+ *
+ * - `SCRIPT_PARSE` — the script (or its meta statement) does not parse.
+ * - `META_INVALID` — the meta block evaluated but fails the shape contract.
+ * - `INVALID_ARGUMENT` — a hook was called with malformed arguments.
+ * - `UNSUPPORTED_OPTION` — an `agent()` option this engine does not support
+ *   (deferred: `effort`/`isolation`/`agentType`) or does not know.
+ * - `UNSUPPORTED_SCHEMA` — an `agent()` schema outside the structured-output
+ *   subset (see dsh-tools).
+ * - `AGENT_CAP` / `ITEM_CAP` — the run/agent caps tripped.
+ * - `AGENT_START` — the subagent seam refused to start a child.
+ * - `AGENT_RESULT` — a child's `result` REJECTED: an infrastructure fault at
+ *   the subagent seam, distinct from a child that failed and resolved (which
+ *   is the per-item `null`, never an error).
+ * - `RESULT_UNSERIALIZABLE` — a value crossing the script/host value boundary
+ *   is not plain JSON data.
+ * - `CANCELLED` — the run was cancelled; pending and future hooks reject
+ *   with this (the script-kill mechanism).
+ */
+export type WorkflowErrorCode =
+  | 'SCRIPT_PARSE'
+  | 'META_INVALID'
+  | 'INVALID_ARGUMENT'
+  | 'UNSUPPORTED_OPTION'
+  | 'UNSUPPORTED_SCHEMA'
+  | 'AGENT_CAP'
+  | 'ITEM_CAP'
+  | 'AGENT_START'
+  | 'AGENT_RESULT'
+  | 'RESULT_UNSERIALIZABLE'
+  | 'CANCELLED'
+
+/**
+ * Typed error for workflow-seam failures. Extends {@link HarnessError}, so the
+ * `code` is machine-routable taxonomy. `fatal` drives the combinator
+ * discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd
+ * option or a tripped cap must kill the script loudly), and reserve the
+ * per-item `null` for child-run failures and ordinary in-stage script errors.
+ * Every {@link WorkflowErrorCode} is fatal in this cut; the flag exists so the
+ * distinction is explicit at every catch site rather than implied.
+ */
+export class WorkflowError extends HarnessError {
+  /** Whether combinators must propagate this error instead of nulling the item. */
+  readonly fatal: boolean
+
+  constructor(message: string, code: WorkflowErrorCode, options?: ErrorOptions & { fatal?: boolean }) {
+    super(message, code, options)
+    this.name = 'WorkflowError'
+    this.fatal = options?.fatal ?? true
+  }
+}
+
+/**
+ * Whether combinators must re-throw `error` instead of mapping the item to `null`.
+ * @param error - any thrown value; fatality is host `instanceof` (unforgeable from a script realm).
+ * @returns true iff `error` is a {@link WorkflowError} whose `fatal` flag is set.
+ */
+export function isFatalWorkflowError(error: unknown): boolean {
+  return error instanceof WorkflowError && error.fatal
+}
+
+/**
+ * Abstract workflow execution service. Subclass, implement {@link start}, and
+ * load the subclass as a plugin — it registers as `ctx.workflows` (one
+ * implementation per context; loading a second throws, cordis' standard
+ * duplicate-service behavior).
+ *
+ * Semantics every implementation must honor:
+ * - {@link start} throws synchronously for a request that cannot begin (an
+ *   unparseable script, an invalid meta block). Once it returns a
+ *   {@link WorkflowRun}, `result` NEVER rejects — every failure resolves with
+ *   `stopReason: 'error'` (or `'cancelled'`) — and once the run is cancelled,
+ *   `result` SETTLES within the implementation's bounded grace even if the
+ *   script itself never settles (a consumer awaiting `result` must never be
+ *   wedged past a cancellation).
+ * - The `workflow/*` events fire through {@link emitWorkflowEvent} (data
+ *   snapshots, per-listener containment); `workflow/end` fires exactly once
+ *   per started run, after `result` is settled or as it settles.
+ * - `dispose()` reaches quiescence within a bounded grace: it cancels, waits
+ *   for the script to settle AND its started children to finish disposing,
+ *   and abandons whatever is left rather than hanging its caller (the engine
+ *   documents what abandonment leaves behind).
+ * - Runs are HOLDER-OWNED: the engine hands control (`cancel`/`dispose`) to
+ *   the `start()` caller and does not track its live runs — disposing the
+ *   engine's own fiber mid-run deliberately leaves those runs to their
+ *   holders' teardown, so an engine reload cannot yank a run out from under
+ *   the consumer awaiting it.
+ */
+export abstract class WorkflowService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'workflows')
+  }
+
+  /**
+   * Parse and execute a workflow script.
+   * @param request - the script, its `args`, the parent agent, and an
+   *   optional cancel signal.
+   * @returns the live run; its `result` resolves when the script settles.
+   */
+  abstract start(request: WorkflowStartRequest): WorkflowRun
+
+  /**
+   * Emit one `workflow/*` lifecycle event with PER-LISTENER containment and
+   * PER-LISTENER payload snapshots: each subscriber is dispatched individually
+   * with its OWN structural clone of the payload (the payloads are plain JSON
+   * data by the seam contract), so a listener mutating what it received can
+   * corrupt neither the engine's live state nor any other listener's or later
+   * event's view; a thrown listener is logged (never propagated — the logging
+   * itself is total, even for a thrown value whose own string coercion
+   * throws), so one bad subscriber can neither fail the engine mid-run,
+   * surface as an unhandled rejection on a detached settle hook, nor starve
+   * the listeners registered after it (cordis `emit` halts on the first throw
+   * — same guarantee as the subagent seam's lifecycle emits).
+   * @param name - the `workflow/*` event to dispatch.
+   * @param args - the event's payload, matching its declared signature.
+   */
+  protected emitWorkflowEvent(name: WorkflowEventName, ...args: unknown[]): void {
+    for (const callback of this.ctx.events.dispatch('emit', [name, ...args])) {
+      try {
+        // The declared workflow/* signatures are all void-returning emits; the
+        // dispatch callback applies the payload tuple.
+        ;(callback as (...payload: unknown[]) => void)(...structuredClone(args))
+      } catch (error: unknown) {
+        this.ctx.logger.warn(`workflow: ${name} listener threw: ${renderListenerError(error)}`)
+      }
+    }
+  }
+}
+
+/**
+ * Total renderer for a listener-thrown value: the containment catch must never
+ * itself throw, and `String(error)` does when the value's own `toString` /
+ * `Symbol.toPrimitive` throws. Local rather than an engine package's renderer
+ * — the seam sits below every engine and cannot import one.
+ * @param error - any thrown value.
+ * @returns `String(error)`, or a fixed label when even coercion throws.
+ */
+function renderListenerError(error: unknown): string {
+  try {
+    return String(error)
+  } catch {
+    // Only a throwing toString/Symbol.toPrimitive lands here; the fixed label
+    // keeps the containment guarantee total.
+    return '[unrenderable thrown value]'
+  }
+}
+
+export default WorkflowService