@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/subagents/child-engine.d.ts

@@ -0,0 +1,198 @@
+import type { RuntimeConfig, SessionStore, RuntimeHooksConfig, SandboxSettingsConfig, PermissionMode, BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import { type EngineOptions, type EngineSettingsRuleSeed, type Provider } from "../engine.js";
+import type { ChildEngineFactory } from "./child-handle.js";
+import { type ModelCatalog } from "./resolution.js";
+import type { SystemPromptAssembler } from "../context/seam.js";
+import { type SkillSessionRuntime } from "../skills/runtime.js";
+import type { SkillListing } from "../context/seam.js";
+import type { StructuredOutputSeam } from "../structured/seam.js";
+import type { SourcedHookEntry } from "../hooks/registry.js";
+import type { CompactionController } from "../compaction/seam.js";
+/** The identity an R6-17 child's own provider reports. `authRefKind` is the CHILD's material's kind (Ruling E-1), never the parent's. */
+export interface ChildProviderIdentity {
+    providerId: string;
+    modelKey: string;
+    family: string;
+    continuationDomain?: string;
+    adapterId?: string;
+    adapterVersion?: string;
+    catalogVersion?: string;
+    authRefKind?: string;
+}
+/**
+ * What `resolveChildProvider` answers. THREE shapes, plus `undefined` -- and the distinction between
+ * the third shape and `undefined` is load-bearing (P6.6 fix wave, whole-branch Important-1):
+ *
+ *  - `{ provider, identity }` -- a full resolution onto the child's OWN adapter.
+ *  - `{ refused, provider, identity }` (Ruling E-1, R-E3) -- the cross-provider child with no
+ *    credential of its own: the resolver names the child, the provider and the reason, the spawn path
+ *    says so on stderr AND on a `continuity_warning` frame, and the child runs on the
+ *    DEFERRED-REFUSAL provider it carries -- its first generation lands on R6-F with NO request. Never
+ *    the parent's provider: a foreign model id on the parent's wire is exactly what a refusal exists
+ *    to prevent.
+ *  - `{ sameAsParent: true, identity }` -- THE MODEL RESOLVED, onto exactly the key the parent is
+ *    running RIGHT NOW, so no second adapter is needed: the caller uses the parent's own provider.
+ *    The `identity` is what it resolved TO, which is what makes this shape distinguishable from an
+ *    unresolvable one on resume. No `provider` rides along deliberately: the parent's adapter is the
+ *    answer, and the resolver has no business handing back a second reference to it.
+ *  - `undefined` -- STRICTLY "unresolvable, or there is no catalog to resolve against" (a scripted
+ *    test double, a model id the registry rejects). NEVER "same as the parent" -- that overload is
+ *    exactly the bug the third shape exists to kill: `resume()` cannot distinguish "the parent moved
+ *    onto this child's own model key" (harmless, the child is servable) from "this child's model no
+ *    longer resolves at all" (a genuine refusal) when both arrive as `undefined`, and the false
+ *    refusal it produced named a provider as no longer serving a model it serves perfectly well.
+ */
+export type ChildProviderResolution = {
+    provider: Provider;
+    identity: ChildProviderIdentity;
+} | {
+    refused: {
+        providerId: string;
+        modelKey: string;
+        reason: string;
+    };
+    provider: Provider;
+    identity: ChildProviderIdentity;
+} | {
+    sameAsParent: true;
+    identity: ChildProviderIdentity;
+};
+export interface ChildEngineFactoryDeps {
+    provider: Provider;
+    /**
+     * Ruling E-1: the operator's channel for a refused cross-provider child. `main.ts` writes it to
+     * the process's stderr, `testing.ts` to the in-memory leg's own stderr queue -- the same two sinks
+     * every wiring warning already uses. Absent means the stderr half is silent (the frame still goes).
+     */
+    warn?: (line: string) => void;
+    /**
+     * Phase 6 Task 10 (R6-17): THE CHILD'S OWN PROVIDER.
+     *
+     * `AgentDefinition.model` is a real per-child model selection, and until this seam existed a child
+     * that named one ran off `deps.provider` -- the PARENT's already-resolved adapter, pinned to the
+     * parent's model id and, for a qualified `<providerId>/<model>` key, to the parent's PROVIDER. The
+     * child's model then travelled only as `ProviderRequest.model`, so a cross-provider child sent one
+     * vendor's model id to another vendor's endpoint.
+     *
+     * Returns `{ sameAsParent: true, identity }` when the model resolves to the same key the parent is
+     * running, and `undefined` when it cannot be resolved at all (no catalog, or a key the registry
+     * rejects); the parent's provider is used unchanged in BOTH cases at spawn -- which is every pre-P6
+     * child and every session whose provider is the reserved test double. They are two different facts
+     * and must not share one answer: see `ChildProviderResolution` for what `resume()` does with each.
+     *
+     * The IDENTITY comes back with it deliberately: a child running its own provider that reported its
+     * PARENT's identity would write provider-state records naming a model it never called, and the
+     * resume side reads those records to decide what may be replayed natively.
+     */
+    resolveChildProvider?: (model: string) => ChildProviderResolution | undefined | Promise<ChildProviderResolution | undefined>;
+    store?: SessionStore;
+    winterHome?: string;
+    /**
+     * WS-21 §3.7: the shared runtime home's durable-paths root (`config.storeHome`), preferred over
+     * `winterHome` wherever this factory resolves an ABSOLUTE durable path for a child -- the
+     * transcript record's own display path, and the provider-state sidecar's attachment gate below
+     * (both point at the SAME `<store>/projects/...` tree `store` itself writes into once its own
+     * construction site prefers `storeHome` too; this factory's own display/gate is what §6.3 item 11
+     * covers). Absent falls back to `winterHome`, byte-identical to pre-WS-21 behaviour.
+     */
+    storeHome?: string;
+    env?: Record<string, string | undefined>;
+    modelCatalog?: ModelCatalog;
+    interactiveDefault?: boolean;
+    disableBypassPermissionsMode?: boolean;
+    forwardSubagentText?: boolean;
+    parentPermissionRules?: {
+        allow?: string[];
+        ask?: string[];
+        deny?: string[];
+    };
+    parentHooks?: RuntimeHooksConfig;
+    parentIncludeHookEvents?: boolean;
+    parentSandbox?: SandboxSettingsConfig;
+    /**
+     * P7a (D19): the PARENT session's resolved brand profile, mirrored down like every other
+     * `parent*` field here.
+     *
+     * A child is a session of the SAME product as its parent -- its worktree lives under the parent's
+     * project dot-dir, its spawn limits read the parent's env prefix, and its own `RuntimeConfig`
+     * must carry the profile onward so ITS children (and its assembler, and its tool executors) stay
+     * branded. Omitted = `WINTER_BRAND`, which is byte-identical to the behaviour before this field.
+     */
+    parentBrand?: BrandProfile;
+    /**
+     * The host's `Options.autoMemory` and `Options.web`, mirrored down like `parentBrand` and for the
+     * same reason: a child's config is HAND-BUILT, so a host option that is not threaded reads as its
+     * DEFAULT inside the child. For `autoMemory` that meant a child rendering the memory section at the
+     * computed path under a host that had turned memory off or moved it (the child shares the
+     * production assembler). For `web` it is the fail-closed half: a child normally inherits the web
+     * configuration from the root's registration, and one that cannot see it must land on the HOST's
+     * block-list and policy, not on "search on, no block-list, ask".
+     */
+    parentAutoMemory?: RuntimeConfig["autoMemory"];
+    parentWeb?: RuntimeConfig["web"];
+    /**
+     * The session's pricing, stated-model and tool-secret seams, so a CHILD's engine has what its
+     * parent's has. `priceUsage` is what makes a child's generations priced at all; the cost then
+     * climbs through `ChildEngineRunContext.recordDescendantCost`. The two resolvers are also
+     * inherited through the web session registry -- threading them here is the fail-closed half, for a
+     * child that cannot see the root's registration.
+     */
+    priceUsage?: EngineOptions["priceUsage"];
+    /** The row facts for a child's UNPRICED generations -- see `EngineOptions.usageRowFacts`. Remapped to the child's own key exactly like `priceUsage`. */
+    usageRowFacts?: EngineOptions["usageRowFacts"];
+    resolveAuxiliaryModel?: EngineOptions["resolveAuxiliaryModel"];
+    resolveToolSecret?: EngineOptions["resolveToolSecret"];
+    getParentPolicy?: () => {
+        mode: PermissionMode;
+        version: number;
+        hash: string;
+    };
+    systemPromptAssembler?: SystemPromptAssembler;
+    skillRuntime?: {
+        index: SkillSessionRuntime["index"];
+        skillOverrides?: SkillSessionRuntime["skillOverrides"];
+    };
+    skillListing?: SkillListing;
+    /** SDK 0.0.16: the catalog's model display names, for the child's own `# Environment` line. */
+    describeModel?: EngineOptions["describeModel"];
+    /**
+     * Phase 5 residual round (NEW-4): THE SETTINGS SEED, tags intact.
+     *
+     * C1 gave the parent its settings-file rules and I1 gave it the resolved-root floors; neither
+     * reached a child, so the MANAGED tier -- the strongest one, and the only one a forced-bypass
+     * child still honours -- stopped at the session boundary. A model reached it by delegating.
+     *
+     * NOT the `getParentRules` mirror, deliberately: a mirrored entry arrives re-tagged `sdk`, and
+     * stage 2 under forced bypass honours `managed` denies alone, so the mirror is inert in precisely
+     * the hostile case. Passing the seed keeps every source tag, which is also what keeps the child's
+     * P5-A/P5-D per-tier gates identical to its parent's.
+     */
+    settingsRules?: EngineSettingsRuleSeed;
+    structuredOutput?: StructuredOutputSeam;
+    extraHookEntries?: readonly SourcedHookEntry[];
+    compactionController?: CompactionController;
+    /**
+     * Phase 5 residual round, NEW-2: ONE CONTROLLER PER SPAWN, not one per session.
+     *
+     * `compactionController` above is a single instance built once for the whole factory, so every
+     * SIBLING child shared one `lastSummary` memo. The comment at its construction site claimed
+     * "per-parent", and the reason it gives -- a child folding its own history into the parent's memo
+     * -- applies between siblings just as exactly.
+     *
+     * Bounded rather than dramatic: `compaction/controller.ts`'s carry-forward is gated on the input's
+     * head message being content-equal to `lastSummary`, so a sibling's summary can only be carried
+     * into a child whose own head is byte-identical to it. That is rare, and it is also not a property
+     * anyone reasoned about -- it is the accident that kept a shared memo from being visible.
+     *
+     * Per SPAWN and not per GENERATION: a child that compacts and then resumes must keep its own memo
+     * across generations, which is exactly what the memo is for.
+     */
+    compactionControllerFactory?: () => CompactionController;
+}
+export declare function createChildEngineFactory(deps: ChildEngineFactoryDeps): ChildEngineFactory;
+/**
+ * What a child reports when the SPENDING CEILING ended it (whole-branch review MINOR 9). One constant,
+ * because the engine's own `error_max_budget_usd` result carries no text to forward and the parent must
+ * not be told a retry is worth trying: the ceiling is the session's, so a retry hits it again.
+ */
+export declare const CHILD_BUDGET_STOP_TEXT = "The agent stopped because the session reached its spending limit (maxBudgetUsd), so no further model calls could be made. Retrying will not help -- continue with what it produced, or ask the user to raise the session's budget.";

package/dist/subagents/child-handle.d.ts

@@ -0,0 +1,344 @@
+import type { ActiveSlotSet, ControlResponseFrame, McpServerConfigForProcessTransport, OutputFormat, PermissionMode, RuntimeAgentDefinition, WinterFrame } from "@yanlinglabs/winter-agent-sdk";
+import type { RecordedModelEffort } from "./resolution.js";
+import type { McpServerStateSource } from "../mcp/state.js";
+import type { McpControlSeam } from "../mcp/control-seam.js";
+import type { ChildPolicyResult } from "../permissions/auto/inheritance.js";
+import type { ProviderMessage } from "../engine.js";
+import type { SessionRequestLayout } from "../context/request-layout.js";
+import type { GlobalAgentMessage, DeliveryOutcome } from "@yanlinglabs/winter-agent-sdk/messaging";
+export type ChildStatus = "running" | "completed" | "stopped" | "failed";
+export interface ChildSessionRecord {
+    id: string;
+    parentSessionId: string;
+    parentToolUseId: string;
+    transcript: string;
+    status: ChildStatus;
+    runtime: "winter-agent";
+    /** R-6c-20: the record's model block IS `RecordedModelEffort` (`effectiveProvider`/`slot` included) — one declaration, no local intersection. */
+    model: RecordedModelEffort;
+    permission: {
+        effectiveMode: PermissionMode;
+        parentPolicyHash: string;
+        parentPolicyVersion: number;
+    };
+    name?: string;
+    /**
+     * Task-frames parity (2026-09-17 contract §4): 1 for a top-level spawn, N+1 when spawned inside a
+     * depth-N agent -- `limits.ts`'s own `checkAndRegisterSpawn` already computes exactly this value
+     * (its own header: "depth 1 for its direct children, depth 2 for their own, etc.") and this is
+     * simply where child-engine.ts records it, once, at spawn. Absent only for a hand-built
+     * `ChildSessionRecord` (every pre-existing `impl/*.test.ts` fixture) that never went through the
+     * real spawn path at all.
+     */
+    spawnDepth?: number;
+}
+export interface ChildResult {
+    status: "completed" | "stopped" | "failed";
+    content: string;
+    resolvedModel?: string;
+    totalToolUseCount?: number;
+    totalDurationMs?: number;
+    /**
+     * RULING P5-I (Phase 5 fix wave): the child's VALIDATED structured result, when it produced one.
+     *
+     * `SpawnChildRequest.outputFormat` threads a schema into the child's own generation config, and the
+     * child's engine validates against it and puts the value on `result.structured_output` -- and
+     * nothing carried it back across this seam. Lane W's `agent({schema})` therefore re-parsed the
+     * child's final TEXT and re-validated it through the same validator, which a child forced onto
+     * `StructuredOutput` generally does not produce at all, so the call mostly resolved `null`.
+     *
+     * ABSENT when the child produced none, and a consumer must fall back to the text re-parse only
+     * then -- never treat unvalidated data as validated (the ruling's own wording).
+     */
+    structuredOutput?: unknown;
+    /**
+     * Task-frames parity (2026-09-17 contract §4): the SAME counting `task_progress` uses, taken at
+     * settle() -- `total_tokens` is the LAST recorded turn's (input + cache_write + cache_read) plus
+     * the SUM of every turn's output_tokens; `tool_uses` is every `tool_use` block seen across the
+     * child's own assistant messages; `duration_ms` is settle time minus spawn time. Needed here (not
+     * only on the last `task_progress` frame) because the pin's FINAL `task_notification.usage` must
+     * include the child's LAST turn too -- a trailing text-only turn (no tool_use block) never fires
+     * `onProgress` at all, so tools/impl/agent.ts has nowhere else to read a complete total from.
+     *
+     * Always present once a generation actually started (even a zero-turn child reports zeroed
+     * counters) -- never fabricated for a child that never ran at all, which cannot reach settle().
+     */
+    usage?: {
+        totalTokens: number;
+        toolUses: number;
+        durationMs: number;
+    };
+}
+/**
+ * Task-frames parity (2026-09-17 contract §4): what `SpawnChildRequest.onProgress` (below) is called
+ * with -- one call per child ASSISTANT message that carries at least one `tool_use` block, foreground
+ * and background alike, synchronous with the frame reaching the parent's own stream.
+ */
+export interface ChildTaskProgress {
+    /** `tool_uses` accumulated so far this generation -- the running total, not a per-message delta. */
+    toolUses: number;
+    /** `total_tokens` per the contract's own formula (see `ChildResult.usage`'s own comment). */
+    totalTokens: number;
+    durationMs: number;
+    /** The name of the LAST `tool_use` block in the qualifying message. */
+    lastToolName: string;
+    /**
+     * Contract §8: the activity text of the child's MOST RECENT RECORDED tool call (every `tool_use`
+     * except the structured-output tool is recorded; the value is sticky across messages, like the
+     * pin's tracker `lastActivity`). `undefined` when that call's tool has no activity text (or nothing
+     * has been recorded yet) -- the caller then falls back to the task description.
+     */
+    activity?: string;
+}
+export interface ChildHandle {
+    readonly record: ChildSessionRecord;
+    status(): ChildStatus;
+    steer(msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    resume(msg: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    result(): Promise<ChildResult>;
+    stop(): Promise<void>;
+    /**
+     * Review r1 finding 4: the CURRENT generation's live usage counters (the same numbers
+     * `ChildResult.usage` settles with). Optional -- a hand-built test handle has none. The agent
+     * task's registry row reads it, so a TaskStop that finalizes the row before the child's own result
+     * arrives still reports usage.
+     */
+    usage?(): ChildResult["usage"];
+}
+export type ResolvedAgentDefinition = RuntimeAgentDefinition;
+export interface SpawnChildRequest {
+    parentToolUseId: string;
+    definition?: ResolvedAgentDefinition;
+    fork?: true;
+    prompt: string;
+    model?: string;
+    runInBackground: boolean;
+    isolation?: "worktree";
+    name?: string;
+    /**
+     * SDK 0.0.16 Lane P (R3b §5): the RESOLVED `subagent_type`, set ONLY when the definition
+     * `tools/impl/agent.ts` resolved came from `_source === "builtin"` -- i.e. Winter's own shipped
+     * definition, never a same-named user/project/plugin/programmatic override that merely shadows
+     * one. `SourcedAgentDefinition._source` (subagents/definitions.ts) does not survive onto
+     * `ResolvedAgentDefinition`/`RuntimeAgentDefinition` (a wire shape with no such field), so this is
+     * the one channel by which engine.ts's own `resolveChildModel` -- which sees only this request,
+     * never the definitions map -- can tell "this child IS the built-in Explore" from "this child is
+     * merely named 'Explore'" for the Explore model cap (R3b §5). Absent for every fork, every
+     * non-built-in definition, and every hand-built request in a test fixture that predates this
+     * field -- byte-identical to before it existed.
+     */
+    builtinAgentType?: string;
+    /**
+     * WS-23: the `subagent_type` this child was spawned as (whatever its source), for the
+     * `agent_type` field of its SubagentStart/SubagentStop hook input -- and the subject those events'
+     * matchers are tested against. Absent from a hand-built request; child-engine.ts then falls back
+     * to `builtinAgentType`, `"fork"` for a fork, else `"general-purpose"`.
+     */
+    agentType?: string;
+    outputFormat?: OutputFormat;
+    /**
+     * Task-frames parity (2026-09-17 contract §4): fired synchronously after each child ASSISTANT
+     * message whose content holds at least one `tool_use` block -- foreground and background alike.
+     * `tools/impl/agent.ts` is the one caller with a `ctx.emitFrame` to turn this into a real
+     * `task_progress` frame (a `task_id` only exists once agent.ts has spawned and, for a background
+     * task, called `createBackgroundTask` -- this request is built and handed to `spawnChild` BEFORE
+     * either of those, so the callback closes over a variable assigned once they are known, rather
+     * than the id being a field of the request itself).
+     *
+     * child-engine.ts is the one caller: its own pump already counts `tool_use` blocks per assistant
+     * message (`ChildResult.totalToolUseCount`'s own producer) and already wraps the child's
+     * `ContextAccountant` (for `ChildResult.usage`'s own identical counting) -- this is that SAME
+     * bookkeeping, surfaced per qualifying message instead of only once at settle().
+     */
+    onProgress?: (progress: ChildTaskProgress) => void;
+    /**
+     * Review r1 finding 9: fired ONCE, synchronously, with the real handle, after the child's record
+     * exists and BEFORE its first generation starts -- so a caller (tools/impl/agent.ts) can register
+     * the task and emit `task_started` before any child frame or `task_progress` for that task can
+     * exist. A throw from it is swallowed here (the caller records its own failure and decides what to
+     * do with the child once `spawn` returns). A spawner that never calls it (a hand-built test
+     * double) is fine: the caller falls back to registering after `spawn` resolves.
+     */
+    onSpawned?: (handle: ChildHandle) => void;
+}
+export interface ChildInheritance {
+    policy: ChildPolicyResult;
+    tools: string[];
+    model: string;
+    effort: string;
+    thinking: unknown;
+    systemPrompt: string;
+    /**
+     * Phase 5 Task 8 (rider 12, WS-11 §6.5 "dispatch-children inherit the parent's style"): the
+     * parent's resolved output-style NAME.
+     *
+     * Lane C's report named this exactly: the assembler already applies whatever arrives on
+     * `input.outputStyle`/`config.outputStyle`, so the MECHANISM was ready and only the CHANNEL was
+     * missing -- `ChildInheritance` carried policy/tools/model/effort/thinking/systemPrompt/messages/
+     * sessionRoot and nothing about style, and `buildChildInheritance` set none of it on the child's
+     * `RuntimeConfig`. A child therefore silently ran under the default style however the parent was
+     * configured.
+     *
+     * Absent when the parent configured none, which is the same thing as "the default" -- never a
+     * fabricated `"default"` string, so a child of a parent with no style is byte-identical to a
+     * pre-P5 child.
+     */
+    outputStyle?: string;
+    messages?: ProviderMessage[];
+    sessionRoot: string;
+    /**
+     * Phase 6 Task 3 (R6-17): the PARENT's RESOLVED provider identity.
+     *
+     * `model` above is the child's own bare string (a definition's override, or the parent's). This is
+     * what that string resolves AGAINST: `AgentDefinition.model` goes through the same selection path
+     * as the session's, against the PARENT's provider unless the id is itself qualified. Without this
+     * field a child with a bare model id had no provider to resolve against at all and would either
+     * pick the host's default or fail -- neither of which is "the parent's provider".
+     *
+     * It is also what makes a child's own provider-state records identify themselves: a child writes
+     * its own sidecar beside its own transcript, and `provider`/`model`/`family` on those records come
+     * from here.
+     *
+     * Absent when the parent has not resolved one (every pre-P6 session and every test double), which
+     * reads as "no provider identity to inherit" -- never a fabricated one.
+     */
+    provider?: {
+        providerId: string;
+        modelKey: string;
+        family: string;
+        continuationDomain?: string;
+    };
+    /**
+     * R6-17 / P4 carry: the parent's EFFECTIVE reasoning configuration, from real session concepts.
+     *
+     * `effort` above is a `string` and its base value was the literal `"inherit"` -- an honest
+     * placeholder written when `RuntimeConfig` carried no session-level effort concept at all. It does
+     * now (`config.effort`/`config.thinking`, T2's option mirrors), so these two fields carry the real
+     * resolved values a definition's own override is layered on top of. Kept SEPARATE from `effort`/
+     * `thinking` above rather than replacing them: those are the REQUESTED values (a definition's, or
+     * the placeholder), and WS-10 §3.4's recorded-resolution fields want both halves.
+     */
+    effectiveEffort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
+    effectiveThinking?: {
+        type: "disabled";
+    } | {
+        type: "enabled";
+        budgetTokens?: number;
+        display?: "summarized" | "omitted";
+    } | {
+        type: "adaptive";
+        display?: "summarized" | "omitted";
+    };
+    /**
+     * WS-13c §3 (recorded on the child, extending WS-10 §3.4): the SLOT the parent's `AgentInput.model`
+     * named, and where that slot came from.
+     *
+     * `model` above is the bare string as sent; this says what it MEANT — `{ family: "gpt", name:
+     * "astra", source: "family-default" }`. Without it a child's record cannot distinguish a slot the
+     * session advertised from a unique foreign name the model copied out of older context (§3
+     * acceptance (b)), which is exactly the case §8's cross-family resume has to reason about.
+     *
+     * `source` is the FULL four-member `ActiveSlotSet["source"]` union, not a narrowed copy: this is
+     * assigned straight from `SlotProviderResolution`, and a three-member twin here would make
+     * `claude-pinned` unrepresentable on the very record that documents a cross-family spawn.
+     *
+     * Absent when the parent resolved no slot (every pre-P6.6 session, every test double, and every
+     * child whose model came from `AgentDefinition.model` host-side rather than from the tool).
+     */
+    slot?: {
+        family: string;
+        name: string;
+        source: ActiveSlotSet["source"];
+    };
+    /**
+     * SDK 0.0.16 (P16-7, R3a §2): a FORK's exact inherited request layout -- the parent's LAST rendered
+     * system prompt/blocks, its exact advertised tool specs (names/order/schemas), and its userContext
+     * entries, all captured verbatim from `context/request-layout.ts`'s own per-session memo
+     * (`getSessionRequestLayout`) at the moment this fork was spawned. `subagents/child-engine.ts`
+     * hands this straight to the child's own `runEngine()` as `EngineOptions.exactRequestLayout`, which
+     * bypasses that engine's OWN system-prompt assembly, tool-spec rendering and userContext build
+     * entirely -- the byte-exactness WS-10 §3.5 ("inherits... system prompt... tool pool... verbatim")
+     * needs cannot survive a second independent render, however faithful.
+     *
+     * Fork-only, mirroring `messages` above -- never set for a definition-backed or bare child, which
+     * render their own system prompt/tools normally (WS-10 §2's own per-child restriction concept has
+     * no equivalent for "send the parent's exact bytes").
+     */
+    requestLayout?: SessionRequestLayout;
+}
+export interface ChildEngineDeps {
+    spawn(req: SpawnChildRequest, inherit: ChildInheritance): Promise<ChildHandle>;
+}
+export interface ChildEngineRunContext {
+    parentSessionId: string;
+    parentAgentId?: string;
+    forwardChildFrame(frame: WinterFrame, correlation: {
+        parentToolUseId: string;
+        agentId: string;
+    }): void;
+    registerChildResponseHandler?(handle: (frame: ControlResponseFrame) => boolean): () => void;
+    /**
+     * RULING P5-J (Phase 5 fix wave): fold a DESCENDANT's provider usage into the OWNING session's
+     * cumulative spend.
+     *
+     * A per-run accessor rather than a construction-time mirror, for the reason every other live
+     * accessor on this interface exists: a registered factory is built once and the accountant belongs
+     * to a RUN. Without it a workflow's `budget` bounded only the parent's own turns while every agent
+     * it spawned spent freely -- which is what made `budget.spent()` report an honest but useless 0.
+     *
+     * Adds to the cumulative counter ONLY, never to `contextTokens()`: a child's tokens are spend the
+     * session is responsible for, and they are not part of the parent's own next request.
+     */
+    recordDescendantUsage?(usage: {
+        inputTokens: number;
+        outputTokens: number;
+    }): void;
+    /**
+     * The COST roll-up, beside the token one above: one PRICED generation of a descendant, folded into
+     * the owning run's cost ledger. Separate because a price is per MODEL and the token roll-up carries
+     * no model key. Without it a subagent's spend was invisible to `total_cost_usd` and `maxBudgetUsd`.
+     */
+    recordDescendantCost?(entry: import("../engine.js").PricedGenerationEntry): void;
+    /**
+     * Has the OWNING run (or any run above it) crossed its `maxBudgetUsd`? The child engine ORs this
+     * into its own budget check, so a descendant's main loop -- and any inner-model pass inside it,
+     * through `WebSessionRuntime.budgetExceeded` -- stops at its next request. `maxBudgetUsd` itself is
+     * deliberately NOT threaded into a child's config: a child's ledger is only its own subtree.
+     * Optional and additive: absent reads as "no".
+     */
+    budgetExceeded?(): boolean;
+    getParentPolicy?(): {
+        mode: PermissionMode;
+        version: number;
+        hash: string;
+    };
+    getParentRules?(): ParentRuleMirror;
+    getParentMcpState?(): ParentMcpState;
+    getParentAgents?(): Record<string, unknown> | undefined;
+}
+export interface ParentMcpState {
+    stateSource?: McpServerStateSource;
+    controlSeam?: McpControlSeam;
+    declaredServers?: Record<string, McpServerConfigForProcessTransport>;
+    /**
+     * Fix round 21: every MCP server the parent run can see -- its own board, its declared servers and,
+     * recursively, what IT inherited -- read at call time. A child's advertised partition keeps a live
+     * server's tools for these servers plus its own (engine.ts's `computeAdvertisedPartition`), so every
+     * descendant is offered the session's servers as claude's are (the Agent tool's pool is
+     * `JP($n, Y2(yr.mcp.tools.concat(pn)))`, dump byte 18016381).
+     */
+    visibleServerNames?: () => readonly string[];
+}
+export interface ParentRuleMirror {
+    allow: string[];
+    ask: string[];
+    deny: string[];
+}
+export type ChildEngineFactory = (runCtx: ChildEngineRunContext) => ChildEngineDeps;
+export declare function registerChildEngineFactory(factory: ChildEngineFactory): void;
+export declare function getChildEngineFactory(): ChildEngineFactory | undefined;
+export declare function resetChildEngineFactoryForTest(): void;
+export declare function transformChildFrame(frame: WinterFrame, correlation: {
+    parentToolUseId: string;
+    agentId: string;
+}, forwardSubagentText: boolean): WinterFrame | null;