subagent: implement structured output for in-process backends

The seam vocabulary (SubagentStartRequest.outputSchema, SubagentResult .structured) existed but no in-process backend honored it — spawn/fork advertised outputSchema: false. This lands the missing half: - dsh-tools gains a structured-output JSON Schema subset (json-schema.ts): StructuredOutputSchema, assertSupportedOutputSchema (rejects loud outside the enforced subset, every violation listed), validateStructuredValue (path-qualified issues, total). outputSchema's seam type becomes this raw JSON-Schema subset instead of the author-facing SchemaSpec DSL — the schema travels verbatim to the model as a forced tool's parameters. - dsh-subagent-inprocess gains the shared structured runtime: one global structured_output capture tool (placeholder parameters) + a prepend:true agent/request listener doing FINAL-REQUEST enforcement (strip for plain agents, per-run schema for structured children — survives downstream request-replacing listeners) + an agent/turn-continuation veto that stops a child's turn once captured (no wasted extra model step). Lifetime is refcounted by backends (plugin lifetime) AND live runs (start→settle). - startInProcessRun drives the capture: subset asserted before the child exists, instruction appended to the child's system prompt, clean-finish nudge loop (structuredNudgeRetries, backend Config, default 1), captured value on result.structured; a clean finish without a capture settles 'error' (never a silent success with a missing field). - spawn + fork flip outputSchema: true and inject 'tools'.
2026-07-05 11:35:39 +08:00
parent 2bad139ece
commit dafb81be7b
26 changed files with 1402 additions and 65 deletions
--- a/packages/subagent/subagent-spawn/README.md
+++ b/packages/subagent/subagent-spawn/README.md
@@ -6,14 +6,15 @@ The run mechanics live in the shared [`@deepseek-ai/dsh-subagent-inprocess`](../

 ## What it does

-`start(request)` delegates to `startInProcessRun(ctx, request, { providerName })` with no seed: a fresh child agent with the parent's `cwd`/`parentSession` lineage and (by default) the parent's model. See the [driver README](../subagent-inprocess/README.md) for the full lifecycle (depth check, one-shot drive, result read, dispose).
+`start(request)` delegates to `startInProcessRun(ctx, request, { providerName, structuredNudgeRetries })` with no seed: a fresh child agent with the parent's `cwd`/`parentSession` lineage and (by default) the parent's model. See the [driver README](../subagent-inprocess/README.md) for the full lifecycle (depth check, one-shot drive, result read, dispose).

 ## Capabilities

-`{ outputSchema: false, depthLimit: true, toolFilter: false }`. It constructs the child, so it enforces a recursion cap; structured output and tool-scoping are deferred (the service rejects a request needing either before `start` runs).
+`{ outputSchema: true, depthLimit: true, toolFilter: false }`. It constructs the child, so it enforces a recursion cap, and it supports structured output via the driver's shared [structured runtime](../subagent-inprocess/README.md) (the backend acquires it for its plugin lifetime; each structured run holds its own acquisition until it settles). Tool-scoping is deferred (the service rejects a request needing it before `start` runs).

 ## Config

 | Key | Meaning |
 |---|---|
 | `providerName` | Registry name on `ctx.subagents` (default `spawn`). |
+| `structuredNudgeRetries` | How many times a structured run re-prompts a child that finished cleanly without calling `structured_output` (default 1). |
--- a/packages/subagent/subagent-spawn/src/index.ts
+++ b/packages/subagent/subagent-spawn/src/index.ts
@@ -9,6 +9,11 @@
 * ({@link startInProcessRun}); this backend just passes NO seed (a fresh
 * child). The fork backend is an independent peer over the same driver.
 *
+ * Structured output (`outputSchema`) is supported via the driver's shared
+ * structured runtime: the backend acquires it for its plugin lifetime (so the
+ * capture tool and request-shaping listeners exist before any run), and each
+ * structured run holds its own acquisition until it settles.
+ *
 * Plugin export shape: named `name`/`inject`/`Config`/`apply`, NO default.
 *
 * @module @deepseek-ai/dsh-subagent-spawn
@@ -17,38 +22,61 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { SubagentCapabilities, SubagentProvider, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
-import { startInProcessRun } from '@deepseek-ai/dsh-subagent-inprocess'
+import { acquireStructuredRuntime, startInProcessRun } from '@deepseek-ai/dsh-subagent-inprocess'

 export const name = 'subagent-spawn'
-export const inject = ['subagents', 'agents']
+export const inject = ['subagents', 'agents', 'tools']

-/** Config: the registry name to register the provider under. */
+/** Config: the registry name to register the provider under, plus structured-run tuning. */
 export interface Config {
  /** Provider name on `ctx.subagents` (default `spawn`). */
  providerName: string
+  /**
+   * How many times a structured run re-prompts a child that finished cleanly
+   * without calling `structured_output` before giving up (default 1).
+   */
+  structuredNudgeRetries: number
 }

 export const Config: z<Config> = z.object({
  providerName: z.string().default('spawn'),
+  structuredNudgeRetries: z.natural().default(1),
 })

 /**
 * The spawn provider. Supports `depthLimit` (it constructs the child, so it can
- * enforce a recursion cap) but NOT `outputSchema` or `toolFilter` in this cut —
- * a request that needs either is rejected by the service before `start` runs.
+ * enforce a recursion cap) and `outputSchema` (via the shared in-process
+ * structured runtime); NOT `toolFilter` in this cut — a request that needs it
+ * is rejected by the service before `start` runs.
 */
 class SpawnProvider implements SubagentProvider {
-  readonly capabilities: SubagentCapabilities = { outputSchema: false, depthLimit: true, toolFilter: false }
+  readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: false }

-  constructor(readonly name: string, private readonly ctx: Context) {}
+  constructor(
+    readonly name: string,
+    private readonly ctx: Context,
+    private readonly structuredNudgeRetries: number,
+  ) {}

  start(request: SubagentStartRequest) {
    // Fresh child: no seed. The shared driver mints ids, stamps cwd/lineage/
-    // depth, drives the one-shot, and maps the result.
-    return startInProcessRun(this.ctx, request, { providerName: this.name })
+    // depth, drives the one-shot (including the structured capture/nudge loop
+    // when the request carries an outputSchema), and maps the result.
+    return startInProcessRun(this.ctx, request, {
+      providerName: this.name,
+      structuredNudgeRetries: this.structuredNudgeRetries,
+    })
  }
 }

 export function apply(ctx: Context, config: Config): void {
-  ctx.subagents.registerProvider(new SpawnProvider(config.providerName, ctx))
+  // Hold the structured runtime for the plugin's lifetime, so the capture tool
+  // and its request-shaping listeners are registered before the first
+  // structured run and torn down when the last backend unloads (live runs hold
+  // their own acquisitions, so an unload mid-run cannot strand a child).
+  ctx.effect(() => {
+    const acquisition = acquireStructuredRuntime(ctx)
+    return () => { acquisition.release() }
+  }, 'subagent-spawn structured runtime')
+  ctx.subagents.registerProvider(new SpawnProvider(config.providerName, ctx, config.structuredNudgeRetries))
 }
--- a/packages/subagent/subagent-spawn/tests/harness.ts
+++ b/packages/subagent/subagent-spawn/tests/harness.ts
@@ -31,7 +31,7 @@ export async function spawnHarness(workdir: string): Promise<Context> {
  await ctx.plugin(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 })
  await ctx.plugin(ToolBash)
  await ctx.plugin(SubagentService)
-  await ctx.plugin(Spawn, { providerName: 'spawn' })
+  await ctx.plugin(Spawn, { providerName: 'spawn', structuredNudgeRetries: 1 })
  // The model-facing subagent tool, bound to the spawn backend.
  await ctx.plugin(ToolSubagent, { provider: 'spawn' })
  return ctx
--- a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
+++ b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
@@ -34,7 +34,7 @@ async function setup(script: Script) {
  await ctx.plugin(Invariants)
  await ctx.plugin(AgentLoop, { agents: [] })
  await ctx.plugin(SubagentService)
-  await ctx.plugin(spawn, { providerName: 'spawn' })
+  await ctx.plugin(spawn, { providerName: 'spawn', structuredNudgeRetries: 1 })
  ctx.llm.registerAdapter(['mock'], adapter)
  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
  return { ctx, parent, adapter }
@@ -241,17 +241,21 @@ describe('dsh-subagent-spawn', () => {
    await parentHandle.dispose()
  })

-  it('advertises depthLimit but not outputSchema/toolFilter', async () => {
+  it('advertises depthLimit and outputSchema but not toolFilter', async () => {
    const { ctx } = await setup([])
    const provider = ctx.subagents.getProvider('spawn')!
-    expect(provider.capabilities).toEqual({ outputSchema: false, depthLimit: true, toolFilter: false })
+    expect(provider.capabilities).toEqual({ outputSchema: true, 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(spawn, { providerName: 'spawn' })
+    // The backend injects 'tools' for the structured runtime, so the registry
+    // (and its systemPrompt dependency) must be live for the fiber to activate.
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    const fiber = await ctx.plugin(spawn, { providerName: 'spawn', structuredNudgeRetries: 1 })
    expect(ctx.subagents.list()).toEqual(['spawn'])
    await fiber.dispose()
    expect(ctx.subagents.list()).toEqual([])
@@ -260,12 +264,12 @@ describe('dsh-subagent-spawn', () => {
  it('has the namespace-plugin export shape (no stray default)', () => {
    expect('default' in spawn).toBe(false)
    expect(spawn.name).toBe('subagent-spawn')
-    expect(spawn.inject).toEqual(['subagents', 'agents'])
+    expect(spawn.inject).toEqual(['subagents', 'agents', 'tools'])
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(spawn) as Record<string, unknown>
    expect(unwrapped).toBe(spawn)
    expect(unwrapped.name).toBe('subagent-spawn')
-    expect(unwrapped.inject).toEqual(['subagents', 'agents'])
+    expect(unwrapped.inject).toEqual(['subagents', 'agents', 'tools'])
    expect(typeof unwrapped.apply).toBe('function')
  })
 })