Add in-process subagent backends: spawn (fresh) and fork (seeded)

The second PR of the subagent seam: the two in-process backends that run a
child agent on the same cordis context, reusing the agent factory's quiescent
AgentHandle teardown. Both register on ctx.subagents (PR1's named-provider
registry) and share one run driver.

- dsh-subagent-spawn: a FRESH child via ctx.agents.create — own session, the
  parent's model by default (overridable), zero inherited conversation. Also
  exports the shared in-process run driver (startInProcessRun): mint ids, stamp
  cwd/parentSession-lineage/depth, drive the one-shot (send → whenIdle), read
  the last assistant/message + turn/end reason, dispose to quiescence.
- dsh-subagent-fork: a child SEEDED with the parent's balanced completed-turn
  prefix (the log up to and including its last turn/end), so the child inherits
  context. The in-flight unbalanced turn is excluded — a raw seed would fail the
  invariants replay. Proven: a regression test goes red if the boundary seeds
  the open turn.
- Seam extension: CreateAgentOptions.seed, threaded through AgentLoop.createAgent
  → ctx.sessions.prepare({ seed }) (the primitive resume already used). This is
  the fork-lineage path the TODO(sub-agents) markers anticipated.
- Depth: a merge-extensible AgentOptions.subagentDepth (0 top-level, parent+1 for
  a child); the depthLimit capability refuses a spawn past request.maxDepth.

Tests: real-loop unit tests for both backends (mock MODEL only, real loop +
invariants), a multi-subagent test (one parent drives a fork AND a spawn child
then keeps working), and a with-key e2e (a real parent delegates via the
`subagent` tool to a real child that writes a file on disk — world-verified).
100% per-file coverage. The coding-agent demo wires the spawn backend + tool.

Snapshot coverage of nested agents is deferred to a stacked follow-up
(TODO(subagent-snapshots)): dsh-llm-replay is a single global positional cursor
that cannot route calls to a parent vs. a child on one context. Recorded in the
RFC's deferrals and a new AGENTS.md rule: designing a subsystem must design its
test infrastructure END TO END up front, verifying the snapshot/e2e harness can
express the new shape — a gap this plan hit.

packages/subagent/subagent-fork/README.md

@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-subagent-fork
+
+The in-process **fork** subagent backend: a [`SubagentProvider`](../subagent/README.md) that runs each child as a child [`Agent`](../../core/agent) **seeded with a prefix of the parent's session log** — so the child inherits the parent's conversation context instead of starting fresh. Shares the run driver (`startInProcessRun`) with [`dsh-subagent-spawn`](../subagent-spawn/README.md); the only difference is the seed.
+
+## The seed boundary (the crux)
+
+At the moment a subagent tool's `execute` runs, the parent's CURRENT turn is open and unbalanced: the log holds the `assistant/message` carrying this spawn's tool-call and the dangling `tool/call` with no `tool/result` yet. Seeding that raw prefix would give the child an open turn that the session constructor and the dev-mode [invariants](../../support/invariants) replay **reject**.
+
+So the fork seeds only the **balanced completed-turn prefix** — the parent's log up to and including its last `turn/end`, excluding the in-flight turn entirely (`completedTurnPrefix`). Because the live log keeps `seq === index`, the slice is contiguous-from-0 and a valid seed. A parent on its very first (not-yet-complete) turn forks an *empty* seed — i.e. effectively a fresh child.
+
+The seam this rides on: `CreateAgentOptions.seed` (added on `dsh-agent`, threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`), the same primitive `resume` uses.
+
+## Capabilities
+
+`{ outputSchema: false, depthLimit: true, toolFilter: false }` — identical to spawn (the depth/model/output behavior is the shared driver's).
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `providerName` | Registry name on `ctx.subagents` (default `fork`). |
+
+See [`dsh-subagent-spawn`](../subagent-spawn/README.md) for the run lifecycle, model inheritance, and depth tracking — all shared.

packages/subagent/subagent-fork/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-fork",
+  "description": "In-process fork subagent backend: runs a child agent seeded with a prefix of the parent's log",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-subagent-spawn": "^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-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:^",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/subagent/subagent-fork/src/index.ts

@@ -0,0 +1,79 @@
+/**
+ * The in-process FORK subagent backend: registers a {@link SubagentProvider} on
+ * `ctx.subagents` that runs each child as a child {@link Agent} SEEDED with a
+ * prefix of the parent's session log — so the child inherits the parent's
+ * conversation context instead of starting fresh. Shares the run driver with
+ * `@deepseek-ai/dsh-subagent-spawn`; the only difference is the seed.
+ *
+ * The seed boundary is the crux: at the moment a subagent tool's `execute`
+ * runs, the parent's CURRENT turn is open and unbalanced (it holds the
+ * `assistant/message` with this spawn's tool-call, plus the dangling `tool/call`
+ * with no `tool/result`). Seeding that raw prefix gives the child an open turn
+ * the session constructor and the dev-mode invariants replay REJECT. So the
+ * fork seeds only the **balanced completed-turn prefix**: the parent's log up
+ * to and including its last `turn/end`, excluding the in-flight turn entirely.
+ *
+ * Plugin export shape: named `name`/`inject`/`Config`/`apply`, NO default.
+ *
+ * @module @deepseek-ai/dsh-subagent-fork
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { SubagentCapabilities, SubagentProvider, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+import { startInProcessRun } from '@deepseek-ai/dsh-subagent-spawn'
+
+export const name = 'subagent-fork'
+export const inject = ['subagents', 'agents']
+
+/** Config: the registry name to register the provider under. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `fork`). */
+  providerName: string
+}
+
+export const Config: z<Config> = z.object({
+  providerName: z.string().default('fork'),
+})
+
+/**
+ * The balanced completed-turn prefix of `parent`'s log: every event up to and
+ * including the last `turn/end`. Empty if the parent has never completed a turn
+ * (the in-flight turn is excluded, so a parent on its very first turn forks an
+ * empty — i.e. fresh — child). The result is contiguous from seq 0 (the live
+ * log keeps `seq === index`), so it is a valid session seed; the in-flight,
+ * unbalanced turn is dropped so the invariants replay accepts it.
+ */
+export function completedTurnPrefix(parent: Agent): SessionEvent[] {
+  const events = parent.session.events
+  const lastEnd = events.findLast(e => e.type === 'turn/end')
+  if (lastEnd === undefined) return []
+  // seq === array index (the append contract), so slice up to and including it.
+  return events.slice(0, lastEnd.seq + 1)
+}
+
+/**
+ * The fork provider. Supports `depthLimit`; NOT `outputSchema`/`toolFilter` this
+ * cut (the service rejects a request needing either before `start` runs).
+ */
+class ForkProvider implements SubagentProvider {
+  readonly capabilities: SubagentCapabilities = { outputSchema: false, depthLimit: true, toolFilter: false }
+
+  constructor(readonly name: string, private readonly ctx: Context) {}
+
+  start(request: SubagentStartRequest) {
+    const seed = completedTurnPrefix(request.parent)
+    return startInProcessRun(this.ctx, request, {
+      providerName: this.name,
+      // Only pass a seed when there's a completed turn to inherit; an empty seed
+      // is equivalent to a fresh child, so omit it to keep the session unseeded.
+      ...seed.length > 0 ? { seed } : {},
+    })
+  }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  ctx.subagents.registerProvider(new ForkProvider(config.providerName, ctx))
+}

packages/subagent/subagent-fork/tests/multi-subagent.spec.ts

@@ -0,0 +1,99 @@
+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 { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import * as fork from '../src/index.ts'
+
+type Script = ConstructorParameters<typeof MockAdapter>[0]
+
+/**
+ * The two in-process backends coexist on one context: the SAME parent agent
+ * delegates to a `spawn` child (fresh) and a `fork` child (seeded with its log),
+ * and keeps working itself. This is the multi-provider coexistence the seam
+ * exists for — the named registry lets one runtime hold both transports.
+ */
+async function setup(script: Script) {
+  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(Invariants)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(Spawn, { providerName: 'spawn' })
+  await ctx.plugin(fork, { providerName: 'fork' })
+  ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
+  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
+  return { ctx, parent }
+}
+
+function text(blocks: { type: string; text?: string }[]): string {
+  return blocks.filter(b => b.type === 'text').map(b => b.text).join('')
+}
+
+describe('multi-subagent coexistence (spawn + fork on one context)', () => {
+  it('both providers register and coexist', async () => {
+    const { ctx } = await setup([])
+    expect(ctx.subagents.list().sort()).toEqual(['fork', 'spawn'])
+  })
+
+  it('the same parent drives a spawn child AND a fork child, then keeps working', async () => {
+    // Script order: parent turn 1, spawn child, fork child, parent turn 2.
+    const { ctx, parent } = await setup([
+      textResponse('parent turn one'),
+      textResponse('spawn child reply'),
+      textResponse('fork child reply'),
+      textResponse('parent turn two'),
+    ])
+
+    // Parent does one real turn first, so the fork has a completed turn to seed.
+    parent.send([{ type: 'text', text: 'parent q1' }])
+    await parent.whenIdle()
+    const parentPrefixLen = parent.session.events.length
+
+    // Delegate to a fresh spawn child.
+    const spawnRun = ctx.subagents.start('spawn', { prompt: [{ type: 'text', text: 'spawn task' }], parent })
+    const spawnResult = await spawnRun.result
+    expect(spawnResult.stopReason).toBe('completed')
+    expect(text(spawnResult.output)).toBe('spawn child reply')
+
+    // Delegate to a fork child (seeded with the parent's turn-1 prefix).
+    const forkRun = ctx.subagents.start('fork', { prompt: [{ type: 'text', text: 'fork task' }], parent })
+    const forkResult = await forkRun.result
+    expect(forkResult.stopReason).toBe('completed')
+    expect(text(forkResult.output)).toBe('fork child reply')
+
+    // The two children are distinct sessions, both lineage-stamped to the parent.
+    const spawnChild = ctx.agents.get(spawnRun.id)!
+    const forkChild = ctx.agents.get(forkRun.id)!
+    expect(spawnChild.session.header.id).not.toBe(forkChild.session.header.id)
+    expect(spawnChild.session.header.parentSession).toBe(parent.session.header.id)
+    expect(forkChild.session.header.parentSession).toBe(parent.session.header.id)
+    // The fork child inherited the parent's prefix; the spawn child did not.
+    expect(forkChild.session.events.slice(0, parentPrefixLen).some(e => e.type === 'user/message')).toBe(true)
+
+    await spawnRun.dispose()
+    await forkRun.dispose()
+
+    // The parent is unaffected and keeps working after both delegations.
+    parent.send([{ type: 'text', text: 'parent q2' }])
+    await parent.whenIdle()
+    const lastParentMessage = parent.session.events.findLast(e => e.type === 'assistant/message')
+    expect(lastParentMessage?.type === 'assistant/message' && text(lastParentMessage.data.content)).toBe('parent turn two')
+    // The parent's OWN log never recorded the children's internal steps — its
+    // only subagent-related entries would be tool/call+tool/result IF it had
+    // used the tool, but here we called the service directly, so the parent log
+    // is purely its own two turns.
+    expect(parent.session.events.filter(e => e.type === 'turn/end')).toHaveLength(2)
+  })
+})

packages/subagent/subagent-fork/tests/subagent-fork.spec.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+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 { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import * as fork from '../src/index.ts'
+import { completedTurnPrefix } from '../src/index.ts'
+
+type Script = ConstructorParameters<typeof MockAdapter>[0]
+
+/**
+ * Drives the REAL fork backend with a real loop + scripted mock MODEL + the
+ * real dsh-invariants plugin. The invariants plugin re-replays a seeded child
+ * log on `session/created` (its freeze-check), so a malformed (unbalanced) fork
+ * seed makes these tests THROW — that is the regression guard for the
+ * completed-turn-prefix boundary.
+ */
+async function setup(script: Script) {
+  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(Invariants)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(fork, { providerName: 'fork' })
+  ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
+  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
+  return { ctx, parent }
+}
+
+function text(blocks: { type: string; text?: string }[]): string {
+  return blocks.filter(b => b.type === 'text').map(b => b.text).join('')
+}
+
+describe('completedTurnPrefix', () => {
+  it('returns an empty prefix for a parent that has never completed a turn', async () => {
+    const { parent } = await setup([])
+    expect(completedTurnPrefix(parent)).toEqual([])
+  })
+
+  it('returns the balanced prefix up to and including the last turn/end', async () => {
+    const { parent } = await setup([textResponse('first'), textResponse('second')])
+    parent.send([{ type: 'text', text: 'q1' }])
+    await parent.whenIdle()
+    parent.send([{ type: 'text', text: 'q2' }])
+    await parent.whenIdle()
+
+    const prefix = completedTurnPrefix(parent)
+    // Ends exactly at the last turn/end; seq is contiguous from 0.
+    expect(prefix.at(-1)?.type).toBe('turn/end')
+    expect(prefix.map(e => e.seq)).toEqual(prefix.map((_, i) => i))
+    // Both completed turns are present.
+    expect(prefix.filter(e => e.type === 'turn/end')).toHaveLength(2)
+  })
+})
+
+describe('dsh-subagent-fork', () => {
+  it('forks an UNSEEDED (fresh) child when the parent has no completed turn', async () => {
+    // The parent has never completed a turn → empty prefix → the provider omits
+    // the seed → the child runs fresh. Exercises the `seed.length > 0` false arm.
+    const { ctx, parent } = await setup([textResponse('fresh child')])
+    expect(completedTurnPrefix(parent)).toEqual([])
+    const run = ctx.subagents.start('fork', { prompt: [{ type: 'text', text: 'child q' }], parent })
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(text(result.output)).toBe('fresh child')
+    const child = ctx.agents.get(run.id)!
+    // Only the child's own turn — no seeded parent turns.
+    expect(child.session.events.filter(e => e.type === 'turn/end')).toHaveLength(1)
+    await run.dispose()
+  })
+
+  it('seeds the child with the parent\'s completed-turn prefix (child inherits context)', async () => {
+    // Parent runs one turn, then we fork. The child's seeded log should contain
+    // the parent's first turn, and the child should run its own new turn on top.
+    const { ctx, parent } = await setup([textResponse('parent answer'), textResponse('child answer')])
+    parent.send([{ type: 'text', text: 'parent question' }])
+    await parent.whenIdle()
+    const parentPrefixLen = parent.session.events.length
+
+    const run = ctx.subagents.start('fork', { prompt: [{ type: 'text', text: 'child question' }], parent })
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(text(result.output)).toBe('child answer')
+
+    const child = ctx.agents.get(run.id)!
+    // The child's log STARTS with the parent's prefix (seeded), then its own turn.
+    expect(child.session.events.length).toBeGreaterThan(parentPrefixLen)
+    // The seeded prefix carried the parent's user message.
+    const seededUser = child.session.events.slice(0, parentPrefixLen).find(e => e.type === 'user/message')
+    expect(seededUser).toBeDefined()
+    // Lineage stamped.
+    expect(child.session.header.parentSession).toBe(parent.session.header.id)
+    await run.dispose()
+  })
+
+  it('produces an invariant-CLEAN seed: forking mid-turn excludes the open turn', async () => {
+    // Drive the parent so it has ONE completed turn, then start a SECOND turn
+    // that is still open (a hanging model call), and fork while it's in flight.
+    // The fork must seed only the completed first turn — an unbalanced seed
+    // would make the invariants replay throw inside ctx.subagents.start.
+    const { ctx, parent } = await setup([textResponse('done'), 'hang', textResponse('child')])
+    parent.send([{ type: 'text', text: 'q1' }])
+    await parent.whenIdle()
+    // Start a second turn that hangs (open turn/start + open step, never ends).
+    parent.send([{ type: 'text', text: 'q2' }])
+    await new Promise(r => setTimeout(r, 20)) // let the hanging turn open
+
+    // Forking now must NOT throw (the open second turn is excluded from the seed).
+    const run = ctx.subagents.start('fork', { prompt: [{ type: 'text', text: 'child q' }], parent })
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(text(result.output)).toBe('child')
+
+    const child = ctx.agents.get(run.id)!
+    // The child's seed has exactly the ONE completed parent turn (the open one excluded).
+    const seedTurnEnds = child.session.events.filter(e => e.type === 'turn/end')
+    // 1 from the seeded parent turn + 1 from the child's own completed turn.
+    expect(seedTurnEnds.length).toBe(2)
+
+    parent.cancel()
+    await run.dispose()
+  })
+
+  it('advertises depthLimit but not outputSchema/toolFilter', async () => {
+    const { ctx } = await setup([])
+    expect(ctx.subagents.getProvider('fork')!.capabilities).toEqual({ outputSchema: false, depthLimit: true, toolFilter: false })
+  })
+
+  it('unregisters the provider when its fiber is disposed (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(AgentRegistry)
+    const fiber = await ctx.plugin(fork, { providerName: 'fork' })
+    expect(ctx.subagents.list()).toEqual(['fork'])
+    await fiber.dispose()
+    expect(ctx.subagents.list()).toEqual([])
+  })
+
+  it('has the namespace-plugin export shape (no stray default)', () => {
+    expect('default' in fork).toBe(false)
+    expect(fork.name).toBe('subagent-fork')
+    expect(fork.inject).toEqual(['subagents', 'agents'])
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(fork) as Record<string, unknown>
+    expect(unwrapped).toBe(fork)
+    expect(unwrapped.name).toBe('subagent-fork')
+    expect(unwrapped.inject).toEqual(['subagents', 'agents'])
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})

packages/subagent/subagent-fork/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../subagent"
+    },
+    {
+      "path": "../subagent-spawn"
+    }
+  ]
+}