Extract the shared in-process driver into dsh-subagent-inprocess (review feedback)

The shared run driver lived inside dsh-subagent-spawn, so the spawn package
carried fork-aware seeding logic and dsh-subagent-fork depended backward on
dsh-subagent-spawn — the two in-process backends were not independent.

Move the driver (startInProcessRun, depthOf, SubagentDepthError,
InProcessRunOptions) into a new pure-library package
@deepseek-ai/dsh-subagent-inprocess that registers nothing. spawn and fork now
both depend only on that driver and neither knows about the other; spawn no
longer re-exports it and fork no longer imports from spawn.

Also wire BOTH backends in examples/coding-agent/cordis.yml (config-only): load
dsh-subagent-spawn + dsh-subagent-fork + two dsh-tool-subagent instances with
distinct toolNames (subagent → spawn, subagent_fork → fork), demonstrating that
exposing multiple transports needs no code change.

packages/subagent/subagent-inprocess/README.md

@@ -0,0 +1,28 @@
+# @deepseek-ai/dsh-subagent-inprocess
+
+The shared **in-process subagent run driver**. A pure library (no provider, no registration) that the in-process backends — [spawn](../subagent-spawn/README.md) (a fresh child) and [fork](../subagent-fork/README.md) (a child seeded with a prefix of the parent's log) — both build on. The backends are thin shells that differ ONLY in the session seed they pass; everything downstream lives here, so neither backend depends on the other.
+
+## What it exports
+
+### `startInProcessRun(ctx, request, options): SubagentRun`
+
+Runs a child as a child [`Agent`](../../core/agent) on the same cordis context (`ctx.agents`):
+
+1. computes child depth = `depthOf(parent) + 1`; if `request.maxDepth` is set and exceeded, throws `SubagentDepthError` (the `depthLimit` capability);
+2. creates a child via `ctx.agents.create` with a fresh `AgentId`/`SessionId`, the parent's `cwd` + `parentSession` lineage, the optional `options.seed` (fork's completed-turn prefix; omitted for a fresh child), and `agentOptions` (the child inherits the **parent's model** by default — a child with no model can't run — overridable via `request.agentOptions.model`; the system prompt is NOT inherited);
+3. drives the one-shot: `child.send(prompt)` then `await child.whenIdle()` (ordering matters — `send` enqueues synchronously, so `whenIdle` observes the queued work and resolves on the child's `running → idle` transition, never before the turn starts);
+4. reads the result, scoped to the child's OWN events (everything at or after `seedLength`, so a seeded child that produced no message of its own never returns the seeded parent's last message): the last `assistant/message` content (deep-cloned — the log is frozen) and the last `turn/end.reason` mapped to a `SubagentStopReason`.
+
+`dispose()` delegates to `AgentHandle.dispose()` (stop loop → await quiescence → remove session); `cancel()` cancels the child's in-flight turn. A cancel landing before any `turn/end` (the pre-turn window) still settles `aborted`, honoring the cancel contract rather than the generic no-turn `error`.
+
+### `InProcessRunOptions`
+
+`{ providerName: string; seed?: SessionEvent[] }` — the per-backend inputs: the provider name (for error context) and the optional child-session seed.
+
+### `depthOf(agent): number`
+
+Delegation depth rides on a merge-extensible `AgentOptions.subagentDepth` field (0 for a top-level agent, parent + 1 for a child), so a nested spawn reads its parent's depth from `parent.options.subagentDepth`. `depthOf` reads it (absent ⇒ 0).
+
+### `SubagentDepthError`
+
+Thrown by `startInProcessRun` when a spawn would exceed the request's `maxDepth` cap; carries `attemptedDepth` and `maxDepth`.

packages/subagent/subagent-inprocess/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-inprocess",
+  "description": "Shared in-process subagent run driver: drives a child agent on ctx.agents (used by the spawn and fork backends)",
+  "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-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "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-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

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

@@ -0,0 +1,192 @@
+/**
+ * The shared in-process subagent run driver: run a child as a child
+ * {@link Agent} on the SAME cordis context (`ctx.agents`) — the cheapest
+ * transport, reusing the agent factory's quiescent {@link AgentHandle}
+ * teardown. The concrete in-process backends are thin shells over this driver,
+ * differing ONLY in the `seed` they pass (a fresh child vs. a child seeded with
+ * a prefix of the parent's log); everything downstream — drive the child, read
+ * its final output, map the stop reason, dispose — is identical and lives here.
+ *
+ * This package owns no provider and registers nothing; it is a pure library the
+ * backend packages depend on, so neither backend needs to know about the other.
+ *
+ * @module @deepseek-ai/dsh-subagent-inprocess
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { Context } from 'cordis'
+import { AgentId, type Agent, type AgentHandle, type AgentOptions } from '@deepseek-ai/dsh-agent'
+import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent'
+
+declare module '@deepseek-ai/dsh-agent' {
+  interface AgentOptions {
+    /**
+     * The agent's delegation depth in the subagent tree — 0 for a top-level
+     * (config/ACP-created) agent, parent depth + 1 for a subagent. Set by the
+     * in-process backends on every child they create so a nested spawn reads its
+     * parent's depth from `parent.options.subagentDepth` and the `depthLimit`
+     * capability can cap the tree. Merge-extensible field (the seam owns it; the
+     * loop neither sets nor reads it).
+     */
+    subagentDepth?: number
+  }
+}
+
+/** Read an agent's delegation depth (absent ⇒ a top-level agent, depth 0). */
+export function depthOf(agent: Agent): number {
+  return agent.options.subagentDepth ?? 0
+}
+
+/** Thrown when a spawn would exceed the request's `maxDepth` cap. */
+export class SubagentDepthError extends Error {
+  constructor(public readonly attemptedDepth: number, public readonly maxDepth: number) {
+    super(`subagent depth ${attemptedDepth} exceeds maxDepth ${maxDepth}`)
+    this.name = 'SubagentDepthError'
+  }
+}
+
+/** Map a session `turn/end` reason to a {@link SubagentStopReason}. */
+function toStopReason(reason: TurnEndReason | undefined): SubagentStopReason {
+  switch (reason?.kind) {
+    case 'completed':
+      return 'completed'
+    case 'max-tokens':
+      return 'max-tokens'
+    case 'aborted':
+      return 'aborted'
+    // `disposed` (torn down mid-turn) and `interrupted` (crash-closed) both mean
+    // the turn did not finish cleanly; surface them as a generic failure rather
+    // than a clean completion. A missing reason (no turn ran) is also an error.
+    case 'error':
+    case 'disposed':
+    case 'interrupted':
+    default:
+      return 'error'
+  }
+}
+
+/** Extra inputs the spawn/fork backends supply to {@link startInProcessRun}. */
+export interface InProcessRunOptions {
+  /** The provider name (`spawn`/`fork`), for error context only. */
+  readonly providerName: string
+  /**
+   * The child session's seed: a balanced, contiguous-from-0 prefix of the
+   * parent's log (FORK), or `undefined` for a fresh child (SPAWN).
+   */
+  readonly seed?: SessionEvent[]
+}
+
+/**
+ * Start an in-process child agent for `request` and return a {@link SubagentRun}.
+ *
+ * Drives the child as a one-shot: `send(prompt)` then `whenIdle()` (the ordering
+ * matters — `send` enqueues synchronously, so `whenIdle` observes the queued
+ * work and resolves only on the child's `running → idle` transition, never
+ * before the turn starts). The final `assistant/message` is the result output,
+ * the matching `turn/end.reason` the stop reason. `dispose()` delegates to the
+ * factory's {@link AgentHandle.dispose} (stop loop → await quiescence → remove
+ * session); `cancel()` cancels the child's in-flight turn.
+ */
+export function startInProcessRun(
+  ctx: Context,
+  request: SubagentStartRequest,
+  options: InProcessRunOptions,
+): SubagentRun {
+  const childDepth = depthOf(request.parent) + 1
+  if (request.maxDepth !== undefined && childDepth > request.maxDepth) {
+    throw new SubagentDepthError(childDepth, request.maxDepth)
+  }
+
+  const childId = AgentId(randomUUID())
+  // The child's OWN events begin after the seed (fork seeds the parent's
+  // completed-turn prefix; spawn seeds nothing). `readResult` scopes to this
+  // boundary so a child that produces no message of its own never returns the
+  // SEEDED parent's last assistant message as its result.
+  const seedLength = options.seed?.length ?? 0
+  const parentHeader = request.parent.session.header
+  // Inherit the parent's model by default (a child with no model cannot run);
+  // an explicit `request.agentOptions.model` overrides it. The parent's
+  // systemPrompt is NOT inherited — a fresh child is a clean specialist unless
+  // the caller supplies one.
+  const agentOptions: AgentOptions = {
+    ...request.parent.options.model !== undefined ? { model: request.parent.options.model } : {},
+    ...request.agentOptions,
+    subagentDepth: childDepth,
+  }
+
+  const handle: AgentHandle = ctx.agents.create({
+    agentId: childId,
+    sessionId: SessionId(randomUUID()),
+    meta: {
+      ...parentHeader.cwd !== undefined ? { cwd: parentHeader.cwd } : {},
+      parentSession: parentHeader.id,
+    },
+    ...options.seed !== undefined ? { seed: options.seed } : {},
+    agentOptions,
+  })
+  const child = handle.agent
+
+  // Bridge the request's abort signal to the child (the consumer also bridges
+  // its own exec.signal, but a backend-level bridge keeps the contract local).
+  // `cancelled` records that a cancel was requested at all, so the pre-turn
+  // cancel window — where the child clears the queued prompt before any
+  // `turn/end` is logged — settles as `aborted` (honoring the cancel contract)
+  // rather than falling through to the no-turn `error` mapping.
+  let cancelled = false
+  const requestCancel = (reason: string): void => {
+    cancelled = true
+    child.cancel(reason)
+  }
+  const onAbort = (): void => { requestCancel('subagent cancelled') }
+  request.signal?.addEventListener('abort', onAbort, { once: true })
+
+  const result: Promise<SubagentResult> = (async () => {
+    try {
+      // A signal already aborted BEFORE the run starts never fires an `abort`
+      // event (`addEventListener` only fires on the transition), so the listener
+      // above won't catch it — settle `aborted` without running the child rather
+      // than completing an already-cancelled request.
+      if (request.signal?.aborted) return { output: [], stopReason: 'aborted' }
+      child.send(request.prompt)
+      await child.whenIdle()
+      return readResult(child, seedLength, cancelled)
+    } finally {
+      request.signal?.removeEventListener('abort', onAbort)
+    }
+  })()
+
+  return {
+    id: childId,
+    result,
+    cancel(reason?: string): void {
+      requestCancel(reason ?? 'subagent cancelled')
+    },
+    async dispose(): Promise<void> {
+      request.signal?.removeEventListener('abort', onAbort)
+      await handle.dispose()
+    },
+  }
+}
+
+/**
+ * Read a settled child's terminal result from its session log, scoped to the
+ * child's OWN events (everything at or after `seedLength` — fork seeds the
+ * parent's completed-turn prefix, so a child that produced no message of its
+ * own must NOT return the seeded parent's last assistant message). The output
+ * is the child's last `assistant/message` content (deep-cloned — the log is
+ * frozen); the stop reason is the child's last `turn/end` reason mapped to a
+ * {@link SubagentStopReason}. When `cancelled` is set but no `turn/end` was
+ * logged (a cancel landed in the pre-turn window, before any turn ran), the
+ * run settles `aborted` per the {@link SubagentRun.cancel} contract rather than
+ * the generic no-turn `error`.
+ */
+function readResult(child: Agent, seedLength: number, cancelled: boolean): SubagentResult {
+  const own = child.session.events.slice(seedLength)
+  const lastMessage = own.findLast((e): e is SessionEvent<'assistant/message'> => e.type === 'assistant/message')
+  const lastEnd = own.findLast((e): e is SessionEvent<'turn/end'> => e.type === 'turn/end')
+  const output: ContentBlock[] = lastMessage ? structuredClone(lastMessage.data.content) : []
+  if (lastEnd === undefined && cancelled) return { output, stopReason: 'aborted' }
+  return { output, stopReason: toStopReason(lastEnd?.data.reason) }
+}

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

@@ -0,0 +1,85 @@
+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, type Agent } 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 { depthOf, SubagentDepthError, startInProcessRun } from '../src/index.ts'
+
+type Script = ConstructorParameters<typeof MockAdapter>[0]
+
+/**
+ * Drives the shared in-process run driver DIRECTLY (no provider package), so the
+ * driver's own contract — depth read/cap, the one-shot drive, the result read —
+ * is covered independently of which backend (spawn/fork) calls it. The only
+ * mocked boundary is the model; the real agent loop, SubagentService, and
+ * dsh-invariants are mounted, so a malformed child session log fails the test.
+ */
+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)
+  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('depthOf', () => {
+  it('reads 0 for an agent with no subagentDepth, the set value otherwise', async () => {
+    const { parent } = await setup([])
+    expect(depthOf(parent)).toBe(0)
+    const withDepth = { options: { subagentDepth: 3 } } as unknown as Agent
+    expect(depthOf(withDepth)).toBe(3)
+  })
+})
+
+describe('startInProcessRun', () => {
+  it('drives a fresh child (no seed) to completion and returns its output', async () => {
+    const { ctx, parent } = await setup([textResponse('driver child answer')])
+    const run = startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'do X' }], parent }, { providerName: 'spawn' })
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(text(result.output)).toBe('driver child answer')
+    expect(depthOf(ctx.agents.get(run.id)!)).toBe(1)
+    await run.dispose()
+  })
+
+  it('throws SubagentDepthError when the child would exceed maxDepth', async () => {
+    const { ctx, parent } = await setup([])
+    expect(() => startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'p' }], parent, maxDepth: 0 }, { providerName: 'spawn' }))
+      .toThrow(SubagentDepthError)
+  })
+
+  it('seeds the child session when a seed is supplied', async () => {
+    // Drive the parent through one real turn, then seed the child with that
+    // completed-turn prefix — the child must SEE the parent's history but its
+    // result is scoped to its OWN events (not the seeded parent message).
+    const { ctx, parent } = await setup([textResponse('parent turn'), textResponse('seeded child reply')])
+    parent.send([{ type: 'text', text: 'parent q' }])
+    await parent.whenIdle()
+    const seed = parent.session.events.slice()
+    const run = startInProcessRun(ctx, { prompt: [{ type: 'text', text: 'child q' }], parent }, { providerName: 'fork', seed })
+    const result = await run.result
+    expect(result.stopReason).toBe('completed')
+    expect(text(result.output)).toBe('seeded child reply')
+    const child = ctx.agents.get(run.id)!
+    // The child inherited the parent's prefix.
+    expect(child.session.events.slice(0, seed.length).some(e => e.type === 'user/message')).toBe(true)
+    await run.dispose()
+  })
+})

packages/subagent/subagent-inprocess/tsconfig.json

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