@morlay/dsh-subagent 0.0.6 → 0.0.7

package/src/vendor/dsh-subagent/out-of-process.ts

@@ -0,0 +1,219 @@
+/**
+ * Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
+ * that enforce this seam's own contracts around a child in another process:
+ * the no-capabilities advertisement, timing-bound validation, child
+ * working-directory validation, the never-reject result settlement, and the standard
+ * run-handle publication. Backends compose these with their own wire drivers;
+ * the process machinery itself (spawn, env scrub, managed-range teardown)
+ * belongs to the `dsh-subprocess` seam.
+ *
+ * @module @deepseek-ai/dsh-subagent/out-of-process
+ */
+
+import { accessSync, constants, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import type { ContentBlock } from "@deepseek-ai/dsh-llm";
+import type {
+  SubagentCapabilities,
+  SubagentResult,
+  SubagentRun,
+  SubagentStopReason,
+} from "./types.ts";
+
+/** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
+const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096;
+
+const DIAGNOSTIC_TRUNCATION_SUFFIX = "\n[diagnostic truncated]";
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder();
+
+/**
+ * Limit provider-authored failure detail without splitting a UTF-8 sequence.
+ * @param diagnostic - safe diagnostic text produced by the provider.
+ * @returns the original text, or a visibly truncated value within the limit.
+ */
+function limitSubagentDiagnostic(diagnostic: string): string {
+  const bytes = utf8Encoder.encode(diagnostic);
+  if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES) return diagnostic;
+
+  const suffixBytes = utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
+  let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - suffixBytes;
+  while (((bytes[prefixBytes] as number) & 0b1100_0000) === 0b1000_0000) {
+    prefixBytes -= 1;
+  }
+  return utf8Decoder.decode(bytes.subarray(0, prefixBytes)) + DIAGNOSTIC_TRUNCATION_SUFFIX;
+}
+
+/** Enforce the byte limit on a provider-returned diagnostic. */
+function normalizeSubagentDiagnostic(result: SubagentResult): SubagentResult {
+  return result.diagnostic === undefined
+    ? result
+    : { ...result, diagnostic: limitSubagentDiagnostic(result.diagnostic) };
+}
+
+/**
+ * The capability advertisement of an out-of-process backend: NONE. A child in
+ * another process cannot honor parent-enforced start features
+ * (`agentOptions`/`agentPreset`/`outputSchema`/`maxDepth`), so the service rejects a
+ * request needing any of them before `start` runs — never accepted-then-ignored.
+ */
+export const NO_START_CAPABILITIES: SubagentCapabilities = Object.freeze({
+  agentOptions: false,
+  agentPreset: false,
+  outputSchema: false,
+  depthLimit: false,
+});
+
+/**
+ * Assert a configured timing bound is a positive finite number (it bounds a
+ * teardown or shutdown wait; zero, negative, or NaN would skip or wedge it).
+ * @param prefix - the consuming plugin's diagnostic prefix (e.g. `subagent-acp`).
+ * @param name - the config field name, for the diagnostic.
+ * @param value - the configured value.
+ */
+export function assertPositiveFinite(prefix: string, name: string, value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${prefix}: ${name} must be a positive finite number`);
+  }
+}
+
+/**
+ * Whether `path` names an existing directory the harness can ENTER. The
+ * search-permission probe matters: `statSync().isDirectory()` is true for a
+ * mode-600 directory, but a subprocess cwd needs `X_OK` or spawn fails EACCES.
+ */
+function isEnterableDirectory(path: string): boolean {
+  try {
+    if (!statSync(path).isDirectory()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    // statSync/accessSync throw only filesystem access errors here
+    // (ENOENT/EACCES/ENOTDIR/…), and every one of them means the path cannot
+    // serve as the child's cwd.
+    return false;
+  }
+}
+
+/**
+ * Assert `cwd` can actually host the child: absolute (it doubles as the
+ * child's workspace identity, and a relative path would be re-anchored to the
+ * server process's launch directory) and an existing directory (fail here,
+ * before the process boundary, instead of as an ambiguous spawn ENOENT).
+ * @param prefix - the consuming plugin's diagnostic prefix.
+ * @param label - which source supplied the value, for the diagnostic.
+ * @param cwd - the candidate working directory.
+ * @returns `cwd`, validated.
+ */
+export function assertUsableCwd(prefix: string, label: string, cwd: string): string {
+  if (!isAbsolute(cwd)) {
+    throw new Error(`${prefix}: ${label} must be an absolute path: ${cwd}`);
+  }
+  if (!isEnterableDirectory(cwd)) {
+    throw new Error(`${prefix}: ${label} is not an accessible directory: ${cwd}`);
+  }
+  return cwd;
+}
+
+/** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
+function toError(value: unknown): Error {
+  // The rejecting surfaces (wire clients, spawn failures) only throw
+  // `Error`s; the `String(value)` arm is a defensive fallback for a non-Error
+  // throw the typed surfaces cannot produce.
+  /* v8 ignore next */
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+/** Inputs to {@link settleRunResult}. */
+export interface RunResultSettlement {
+  /** The turn attempt (typically racing local cancellation); returns the terminal result. */
+  attempt: () => Promise<SubagentResult>;
+  /** Snapshot the provider exposes when cancellation or failure wins settlement. */
+  collectOutput: () => readonly ContentBlock[];
+  /** Snapshot safe provider-authored detail when a failure wins settlement. */
+  collectDiagnostic?: (() => string | undefined) | undefined;
+  /** Whether local cancellation settled before the attempt's outcome is observed. */
+  cancelled: () => boolean;
+  /** Diagnostic sink for a failure flattened to a stop reason; a throw from it is contained. */
+  onError?: ((error: Error, stopReason: SubagentStopReason) => void) | undefined;
+  /** The request's cancellation signal (the listener is removed at settlement). */
+  signal: AbortSignal;
+  /** The abort listener registered on {@link signal} at start. */
+  onAbort: () => void;
+}
+
+/**
+ * Settle an out-of-process run result under the seam contract: `result` never
+ * rejects after publication. A normally completed or rejected attempt resolves
+ * as `aborted` when cancellation already settled locally; another rejection is
+ * flattened to `stopReason: 'error'` through the contained diagnostic sink.
+ * Provider-returned diagnostics use the same byte limit. The abort listener is
+ * removed on every path.
+ * @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
+ * @returns the terminal result (never a rejection).
+ */
+export async function settleRunResult(parts: RunResultSettlement): Promise<SubagentResult> {
+  try {
+    const result = await parts.attempt();
+    return parts.cancelled()
+      ? { output: parts.collectOutput(), stopReason: "aborted" }
+      : normalizeSubagentDiagnostic(result);
+  } catch (error: unknown) {
+    // Cover a rejection already queued when cancellation arrives.
+    if (parts.cancelled()) return { output: parts.collectOutput(), stopReason: "aborted" };
+    // Flatten post-publication transport failures while preserving diagnostics.
+    try {
+      parts.onError?.(toError(error), "error");
+    } catch {
+      // The diagnostic sink cannot reject the run result.
+    }
+    const collected = parts.collectDiagnostic?.();
+    const diagnostic = collected === undefined ? undefined : limitSubagentDiagnostic(collected);
+    return {
+      output: parts.collectOutput(),
+      ...(diagnostic === undefined ? {} : { diagnostic }),
+      stopReason: "error",
+    };
+  } finally {
+    parts.signal.removeEventListener("abort", parts.onAbort);
+  }
+}
+
+/** Inputs to {@link subprocessRunHandle}. */
+export interface SubprocessRunHandleParts {
+  /** The parent-scoped run id. */
+  id: SubagentRun["id"];
+  /** The flattened, never-rejecting result (the seam contract). */
+  result: Promise<SubagentResult>;
+  /** The request's cancellation signal (the listener is removed on dispose). */
+  signal: AbortSignal;
+  /** The abort listener registered on {@link signal} at start. */
+  onAbort: () => void;
+  /** Settle local cancellation so {@link result} resolves without the child. */
+  requestCancel: () => void;
+  /** Tear the child process down to quiescence (backend-owned ladder). */
+  teardown: () => Promise<void>;
+}
+
+/**
+ * Publish the seam run handle for an out-of-process child. `dispose()` is
+ * idempotent (one memoized teardown): it removes the abort listener, settles
+ * local cancellation — there is no assumption the child cooperates — and then
+ * awaits the backend's teardown to actual exit.
+ * @param parts - the run identity, result, cancellation wiring, and teardown.
+ * @returns the external run handle.
+ */
+export function subprocessRunHandle(parts: SubprocessRunHandleParts): SubagentRun {
+  let disposal: Promise<void> | undefined;
+  return {
+    id: parts.id,
+    result: parts.result,
+    dispose(): Promise<void> {
+      if (disposal !== undefined) return disposal;
+      parts.signal.removeEventListener("abort", parts.onAbort);
+      parts.requestCancel();
+      disposal = parts.teardown();
+      return disposal;
+    },
+  };
+}

package/src/vendor/dsh-subagent/projection-types.ts

@@ -0,0 +1,84 @@
+/**
+ * Pure client-safe subagent projection vocabulary.
+ *
+ * @module @deepseek-ai/dsh-subagent/projection-types
+ */
+
+import type { SessionId, SessionSeq } from "@deepseek-ai/dsh-session/types";
+
+/** One current direct-child discovery row materialized from parent facts. */
+export type SubagentCatalogEntry = {
+  readonly id: SessionId;
+  readonly createdAt: number;
+} & (
+  | { readonly mode: "one-shot"; readonly label?: string }
+  | { readonly mode: "external"; readonly label?: string }
+  | { readonly mode: "continuable"; readonly label: string }
+  | { readonly mode: "unknown"; readonly label?: string }
+);
+
+/** Durable active-turn timing for one descriptor-backed child session. */
+export interface SubagentTimingProjection {
+  /** Milliseconds accumulated across completed turns after the child's own descriptor. */
+  settledMs: number;
+  /** Same-cut bounds of the currently open turn, when one has not reached `turn/end`. */
+  active?: {
+    /** Start of the open turn. */
+    since: number;
+    /** Latest event time folded into this projection cut. */
+    through: number;
+  };
+  /**
+   * Whether the latest closed turn after the child's own descriptor completed
+   * normally; absent while a turn is open or before one closes.
+   */
+  lastTurnCompleted?: boolean;
+}
+
+/**
+ * Durable identity of one descriptor-backed subagent session: lifecycle mode
+ * plus creation label, folded last-wins from `subagent/descriptor` events.
+ * Label strength follows the descriptor schema: a continuable child always
+ * carries one, a one-shot child may omit it.
+ */
+export type SubagentIdentityProjection =
+  | {
+      /** A terminal one-shot child. */
+      mode: "one-shot";
+      /** Optional durable creation label from the child's descriptor. */
+      label?: string;
+      /**
+       * Seq of the `subagent/descriptor` event this identity was folded from.
+       * `session.isOwnSeq(seq)` proves the identity comes from the child's
+       * OWN log suffix — where a descriptor is immutable once appended — and
+       * not from a fork seed's replayed ancestor descriptor.
+       */
+      seq: SessionSeq;
+    }
+  | {
+      /** A resumable conversation. */
+      mode: "continuable";
+      /** Durable creation label from the child's descriptor. */
+      label: string;
+      /** Seq of the folded descriptor event; see the one-shot arm for the own-suffix proof. */
+      seq: SessionSeq;
+    };
+
+declare module "@deepseek-ai/dsh-session-projection/types" {
+  interface SessionProjectionMap {
+    /** Direct children in parent catalog event order, excluding fork-inherited facts. */
+    subagentCatalog: SubagentCatalogEntry[];
+    /** Active-turn duration and latest closed-turn completion for a descriptor-backed subagent session. */
+    subagentTiming: SubagentTimingProjection;
+    /**
+     * Identity of a descriptor-backed subagent session. `null` ⟺ no valid
+     * descriptor (missing, malformed, or unrecognized-version — deliberately
+     * undistinguished). The sentinel is deliberately serializable: a
+     * value pushed over JSON transports must survive `JSON.stringify`
+     * losslessly, where an `undefined` field would be dropped and a stale
+     * identity would survive on the receiving side. The entry itself stays
+     * non-optional.
+     */
+    subagent: SubagentIdentityProjection | null;
+  }
+}

package/src/vendor/dsh-subagent/projection.ts

@@ -0,0 +1,205 @@
+/**
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
+ *
+ * @module @deepseek-ai/dsh-subagent/projection
+ */
+
+import { z } from "zod";
+import { SessionSeq } from "@deepseek-ai/dsh-session";
+import type { ProjectionDefinition } from "@deepseek-ai/dsh-session-projection";
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+import { foldSubagentDescriptor } from "./descriptor.ts";
+import type { SubagentDescriptorData } from "./descriptor.ts";
+import type { SubagentIdentityProjection, SubagentTimingProjection } from "./projection-types.ts";
+
+/** Fold state for a subagent's latest timing snapshot. */
+export interface TimingState {
+  /** Milliseconds accumulated across completed post-descriptor turns. */
+  settledMs: number;
+  /** Current open interval kept paired inside the fold. */
+  active?: { since: number; through: number } | undefined;
+  /** Latest pre-descriptor turn start, promoted when the child's own descriptor arrives. */
+  pendingTurnStart?: number | undefined;
+  /** Whether the fold has crossed a descriptor in this logical log. */
+  descriptorSeen: boolean;
+  /** Whether the latest closed post-descriptor turn completed normally; absent while a turn is open or before one closes. */
+  lastTurnCompleted?: boolean | undefined;
+}
+
+const activeIntervalSchema = z
+  .object({
+    since: z.number().int().nonnegative(),
+    through: z.number().int().nonnegative(),
+  })
+  .strict();
+
+const projectionSchema: z.ZodType<SubagentTimingProjection> = z
+  .object({
+    settledMs: z.number().int().nonnegative(),
+    active: activeIntervalSchema.optional(),
+    lastTurnCompleted: z.boolean().optional(),
+  })
+  .strict()
+  .transform(({ settledMs, active, lastTurnCompleted }) => ({
+    settledMs,
+    ...(active === undefined ? {} : { active }),
+    ...(lastTurnCompleted === undefined ? {} : { lastTurnCompleted }),
+  }));
+
+const timingStateSchema: z.ZodType<TimingState> = z
+  .object({
+    settledMs: z.number().int().nonnegative(),
+    active: activeIntervalSchema.optional(),
+    pendingTurnStart: z.number().int().nonnegative().optional(),
+    descriptorSeen: z.boolean(),
+    lastTurnCompleted: z.boolean().optional(),
+  })
+  .strict();
+
+declare module "@deepseek-ai/dsh-session-projection/types" {
+  interface SessionProjectionStateMap {
+    subagentTiming: TimingState;
+    subagent: IdentityState;
+  }
+}
+
+/**
+ * Fold turn boundaries around the child's own durable descriptor.
+ *
+ * A fork seed may contain an ancestor descriptor and completed turns. Every
+ * descriptor therefore resets the accumulated state; the healthy catalog
+ * admits only a child with exactly one descriptor in its own suffix, making
+ * the final reset the child's authoritative timing origin.
+ */
+export const subagentTimingProjectionDefinition = {
+  key: "subagentTiming",
+  stateSchema: timingStateSchema,
+  init: () => ({ descriptorSeen: false, settledMs: 0 }),
+  apply: (state, event) => {
+    if (event.type === "turn/start") {
+      const { lastTurnCompleted: _closed, ...openState } = state;
+      return state.descriptorSeen
+        ? { ...openState, active: { since: event.time, through: event.time } }
+        : { ...openState, pendingTurnStart: event.time };
+    }
+    if (event.type === "subagent/descriptor") {
+      const activeSince = state.active?.since ?? state.pendingTurnStart;
+      return {
+        descriptorSeen: true,
+        settledMs: 0,
+        ...(activeSince === undefined
+          ? {}
+          : { active: { since: activeSince, through: event.time } }),
+      };
+    }
+    if (event.type === "turn/end") {
+      if (!state.descriptorSeen) {
+        if (state.pendingTurnStart === undefined) return state;
+        const { pendingTurnStart: _closed, ...next } = state;
+        return next;
+      }
+      if (state.active === undefined) return state;
+      const { active, ...rest } = state;
+      return {
+        ...rest,
+        settledMs: state.settledMs + Math.max(0, event.time - active.since),
+        lastTurnCompleted: event.data.reason.kind === "completed",
+      };
+    }
+    if (state.active === undefined) return state;
+    return { ...state, active: { ...state.active, through: event.time } };
+  },
+  wire: {
+    viewSchema: projectionSchema,
+    view: (state) => ({
+      settledMs: state.settledMs,
+      ...(state.active === undefined ? {} : { active: state.active }),
+      ...(state.lastTurnCompleted === undefined
+        ? {}
+        : { lastTurnCompleted: state.lastTurnCompleted }),
+    }),
+  },
+  stateVersion: 3,
+} satisfies ProjectionDefinition<"subagentTiming", TimingState>;
+
+interface IdentityState {
+  /** Identity from the last valid descriptor; absent before one, and after an invalid one. */
+  identity?: SubagentIdentityProjection | undefined;
+}
+
+// The cast bridges only the optional-label arm: Zod's optional output
+// includes explicit `undefined`, which exactOptionalPropertyTypes excludes
+// from the public interface. The no-value state itself is the serializable
+// `null` arm — never `undefined` — so every registry read and push frame
+// survives JSON.stringify losslessly.
+const identityValueSchema = z.discriminatedUnion("mode", [
+  z
+    .object({
+      mode: z.literal("one-shot"),
+      label: z.string().optional(),
+      seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
+    })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("continuable"),
+      label: z.string(),
+      seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
+    })
+    .strict(),
+]) as unknown as z.ZodType<SubagentIdentityProjection>;
+
+const identitySchema = identityValueSchema.nullable();
+
+const identityStateSchema: z.ZodType<IdentityState> = z
+  .object({
+    identity: identityValueSchema.optional(),
+  })
+  .strict();
+
+/** Interpret one `subagent/descriptor` event's identity; no value when the payload cannot be trusted. */
+function descriptorIdentity(event: SessionEvent): SubagentIdentityProjection | undefined {
+  let descriptor: SubagentDescriptorData | undefined;
+  try {
+    descriptor = foldSubagentDescriptor([event]);
+  } catch {
+    // Only a malformed current-version payload throws in descriptor parsing;
+    // a projection fold must never throw, so damage folds to no value.
+    descriptor = undefined;
+  }
+  if (descriptor === undefined) return undefined;
+  return descriptor.mode === "one-shot"
+    ? {
+        mode: "one-shot",
+        ...(descriptor.label !== undefined ? { label: descriptor.label } : {}),
+        seq: event.seq,
+      }
+    : { mode: "continuable", label: descriptor.label, seq: event.seq };
+}
+
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export const subagentIdentityProjectionDefinition = {
+  key: "subagent",
+  stateSchema: identityStateSchema,
+  init: () => ({}),
+  apply: (state, event) => {
+    if (event.type !== "subagent/descriptor") return state;
+    const identity = descriptorIdentity(event);
+    return identity === undefined ? {} : { identity };
+  },
+  wire: { viewSchema: identitySchema, view: (state) => state.identity ?? null },
+  // Bumped when the identity gained its `seq` field: an older checkpoint row
+  // would replay into a value the schema rejects, so it must refold instead.
+  stateVersion: 2,
+} satisfies ProjectionDefinition<"subagent", IdentityState>;

package/src/vendor/dsh-subagent/structured.ts

@@ -0,0 +1,164 @@
+/**
+ * Child-scoped structured-output tool, prompt instruction, terminal guard, and authoritative
+ * result capture for in-process subagents. Each child registers its real schema on its own
+ * scope, so concurrent runs do not interact and disposal leaves no global residue. The prompt
+ * contribution is ordinary reconstructed request state.
+ *
+ * Capture commits only after the authoritative `tools/result` succeeds; PTC mode capture also
+ * waits for the enclosing `run_code` result. The terminal result marker and monotonic tool
+ * guard prevent later calls from reopening a completed structured run.
+ * @module @deepseek-ai/dsh-subagent/structured
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import type { ToolSchema } from "@deepseek-ai/dsh-llm";
+import type { ToolExecution, ToolRunContext } from "@deepseek-ai/dsh-tools";
+import {
+  ToolArgsError,
+  validateJsonSchemaValue,
+  type ObjectJsonSchema,
+} from "@deepseek-ai/dsh-tools";
+
+/** The model-facing tool name a structured child must call to finish. */
+export const STRUCTURED_OUTPUT_TOOL = "structured_output";
+
+/**
+ * The instruction registered as the child's trailing scoped prompt section:
+ * the demand travels with the
+ * tool, as ordinary prompt state of exactly one agent.
+ */
+export const STRUCTURED_OUTPUT_INSTRUCTION =
+  "When you have your final answer, you MUST report it by calling the " +
+  `\`${STRUCTURED_OUTPUT_TOOL}\` tool with arguments matching its parameter schema exactly. ` +
+  "Do not finish with a plain text answer: only the tool call counts as your result.";
+
+/** One structured run's live handle: read the captured value once the child settles. */
+export interface StructuredAttachment {
+  /**
+   * Input stays closed from capture staging through its final result, including
+   * an enclosing PTC execution. A failed result discards its capture and reopens input.
+   * @returns whether the activation can accept another message.
+   */
+  acceptsInput(): boolean;
+  /**
+   * The captured value, once the child called the tool with valid arguments
+   * and the authoritative final tool result accepted that call.
+   * @returns the committed value, or undefined while none was accepted.
+   */
+  captured(): { value: unknown } | undefined;
+}
+
+/**
+ * Attach the scoped capture tool, instruction, and enforcement to a child during
+ * its creation window. Child disposal removes every registration.
+ * @param childCtx - the child agent's scope context (`setup`'s argument).
+ * @param schema - the trusted, already-asserted schema subset to enforce (see
+ *   `assertObjectJsonSchema` in dsh-tools).
+ * @param canComplete - whether accepted input and owned child work have finished.
+ * @returns the attachment handle (read `captured()` after the child settles).
+ */
+export function attachStructuredRuntime(
+  childCtx: Context,
+  schema: ObjectJsonSchema,
+  canComplete: () => boolean,
+): StructuredAttachment {
+  /**
+   * Validated values staged by the capture tool body, awaiting THEIR OWN
+   * authoritative `tools/result` notification. The execution object's identity
+   * uniquely identifies a trip through the pipeline: adapter call ids may
+   * repeat across steps, but another execution can never reach this Map
+   * entry. This is distinct from the opaque `ToolExecutionToken` used to
+   * correlate nested transports. The final notification always deletes its own
+   * stage, whether the result succeeded or failed.
+   */
+  const staged = new Map<ToolExecution, { value: unknown }>();
+  /** Successful nested capture waiting for its enclosing transport to commit. */
+  let pending: { parent: ToolExecution["token"]; value: unknown } | undefined;
+  let captured: { value: unknown } | undefined;
+
+  const schemaEntry: ToolSchema = {
+    name: STRUCTURED_OUTPUT_TOOL,
+    description:
+      "Report your final structured result. Call this exactly once, when your answer is complete; " +
+      "the arguments must match this tool's parameter schema exactly.",
+    parameters: { ...schema },
+  };
+
+  childCtx.tools.register({
+    ...schemaEntry,
+    output: {
+      schema: {
+        type: "object",
+        properties: { recorded: { type: "boolean", const: true } },
+        required: ["recorded"],
+        additionalProperties: false,
+      },
+      render: () => [{ type: "text", text: "Structured output recorded." }],
+    },
+    execute(args: unknown, exec: ToolRunContext): Promise<{ recorded: true }> {
+      const violations = validateJsonSchemaValue(schema, args);
+      // ToolArgsError → isError result with INVALID_ARGS: the model retries
+      // within the same turn, exactly like a schema-validated defineTool call.
+      if (violations.length > 0) throw new ToolArgsError(violations);
+      if (!canComplete())
+        throw new Error(
+          "Wait for all delegated child tasks to finish and process pending messages before submitting structured output.",
+        );
+      // Two-phase commit, keyed by THIS execution: later transformable
+      // waterfalls may still turn the success into an error. ToolRuntime has
+      // already frozen model-bound arguments at the actual input boundary.
+      staged.set(exec, { value: args });
+      exec.concludeTurn();
+      return Promise.resolve({ recorded: true });
+    },
+  });
+
+  childCtx.systemPrompt.section({
+    name: `tool:${STRUCTURED_OUTPUT_TOOL}`,
+    order: childCtx.systemPrompt.getSectionOrder("STRUCTURED_OUTPUT"),
+    text: STRUCTURED_OUTPUT_INSTRUCTION,
+  });
+
+  // Terminal WITHIN the step. Guards run after the whole pre-execute
+  // waterfall and compose monotonically (deny or abstain, never allow), so a
+  // later prepended listener cannot resurrect dispatch. Calls that precede
+  // capture in the same response remain untouched.
+  childCtx.tools.guard((exec) =>
+    captured === undefined && pending === undefined
+      ? undefined
+      : `structured output already recorded: the run is complete, so \`${exec.name}\` is not executed`,
+  );
+
+  // The capture COMMIT observes the immutable, authoritative result after the
+  // complete pipeline and outer error normalization. This notification cannot
+  // transform the outcome, so there is no wrapper outside the commit verdict.
+  childCtx.on("tools/result", function (this: unknown, exec, result) {
+    if (exec.name === STRUCTURED_OUTPUT_TOOL) {
+      const entry = staged.get(exec);
+      if (entry === undefined) return;
+      staged.delete(exec);
+      if (result.isError) return;
+      if (exec.parent === undefined) {
+        /* v8 ignore else -- sequential agent-loop dispatch lets the guard block every later supported call */
+        if (captured === undefined) captured = { value: entry.value };
+      } else {
+        /* v8 ignore else -- PTC mode serializes sub-dispatches, so the guard blocks every later supported call */
+        if (captured === undefined && pending === undefined) {
+          pending = { parent: exec.parent, value: entry.value };
+        }
+      }
+      return;
+    }
+    if (pending?.parent !== exec.token) return;
+    const entry = pending;
+    pending = undefined;
+    if (result.isError) return;
+    /* v8 ignore else -- PTC mode serializes outer executions, so the guard blocks every later supported call */
+    if (captured === undefined) captured = { value: entry.value };
+  });
+
+  return {
+    captured: () => captured,
+    acceptsInput: () => staged.size === 0 && pending === undefined && captured === undefined,
+  };
+}