@dogpile/sdk 0.3.1 → 0.5.0

package/dist/runtime/coordinator.js

@@ -1,24 +1,89 @@
+import { DogpileError } from "../types.js";
 import { createRunId, elapsedMs, nowMs, providerCallIdFor } from "./ids.js";
-import { addCost, createReplayTraceBudget, createReplayTraceBudgetStateChanges, createReplayTraceFinalOutput, createReplayTraceProtocolDecision, createReplayTraceRunInputs, createReplayTraceSeed, createRunAccounting, createRunEventLog, createRunMetadata, createRunUsage, createTranscriptLink, emptyCost, nextProviderCallId } from "./defaults.js";
-import { throwIfAborted } from "./cancellation.js";
-import { parseAgentDecision } from "./decisions.js";
+import { addCost, createReplayTraceBudget, createReplayTraceBudgetStateChanges, createReplayTraceFinalOutput, createReplayTraceProtocolDecision, createReplayTraceRunInputs, createReplayTraceSeed, createRunAccounting, createRunEventLog, createRunMetadata, createRunUsage, createTranscriptLink, emptyCost, lastCostBearingEventCost, nextProviderCallId } from "./defaults.js";
+import { computeHealth, DEFAULT_HEALTH_THRESHOLDS } from "./health.js";
+import { classifyAbortReason, classifyChildTimeoutSource, createAbortErrorFromSignal, createEngineDeadlineTimeoutError, throwIfAborted } from "./cancellation.js";
+import { assertDepthWithinLimit, parseAgentDecision } from "./decisions.js";
 import { generateModelTurn } from "./model.js";
 import { evaluateTerminationStop, warnOnProtocolTerminationMisconfiguration } from "./termination.js";
 import { createRuntimeToolExecutor, executeModelResponseToolRequests, runtimeToolAvailability } from "./tools.js";
 import { createWrapUpHintController } from "./wrap-up.js";
+/**
+ * Hard-coded loop guard for the delegate dispatch in the coordinator plan
+ * turn. After this many consecutive delegate decisions the coordinator throws
+ * `invalid-configuration` (T-03-01). Not a public option.
+ */
+const MAX_DISPATCH_PER_TURN = 8;
+const DEFAULT_MAX_CONCURRENT_CHILDREN = 4;
+function createSemaphore(maxConcurrent) {
+    let inFlight = 0;
+    const waiters = [];
+    return {
+        acquire() {
+            if (inFlight < maxConcurrent) {
+                inFlight += 1;
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                waiters.push(() => {
+                    inFlight += 1;
+                    resolve();
+                });
+            });
+        },
+        release() {
+            inFlight -= 1;
+            const next = waiters.shift();
+            if (next !== undefined) {
+                next();
+            }
+        },
+        get inFlight() {
+            return inFlight;
+        },
+        get queued() {
+            return waiters.length;
+        }
+    };
+}
+/**
+ * Walk the coordinator's active provider set and return the FIRST provider
+ * whose metadata.locality === "local", or undefined if none found.
+ *
+ * Walk order (forward-compat): options.model first, then options.agents in
+ * declaration order. AgentSpec has no `model` field today (Phase 3 D-11
+ * forward-compat scaffolding); the agent walk uses optional chaining and
+ * effectively no-ops until a future phase adds AgentSpec.model.
+ */
+function findFirstLocalProvider(options) {
+    if (options.model.metadata?.locality === "local") {
+        return options.model;
+    }
+    // Forward-compat: AgentSpec.model not yet declared (Phase 3 D-11). Walk no-ops today; ready for caller-defined trees in a future milestone.
+    for (const agent of options.agents) {
+        const agentModel = agent.model;
+        if (agentModel?.metadata?.locality === "local") {
+            return agentModel;
+        }
+    }
+    return undefined;
+}
 export async function runCoordinator(options) {
     const runId = createRunId();
     const events = [];
     const transcript = [];
     const protocolDecisions = [];
     const providerCalls = [];
+    const dispatchedChildren = new Map();
     let totalCost = emptyCost();
+    let concurrencyClampEmitted = false; // D-12: emit once per run, never per-engine.
     const maxTurns = options.protocol.maxTurns ?? options.agents.length;
     const activeAgents = options.agents.slice(0, maxTurns);
     const coordinator = activeAgents[0];
     const startedAtMs = nowMs();
     let stopped = false;
     let termination;
+    let triggeringFailureForAbortMode;
     const wrapUpHint = createWrapUpHintController({
         protocol: options.protocol,
         tier: options.tier,
@@ -34,6 +99,61 @@ export async function runCoordinator(options) {
     const recordProtocolDecision = (event, decisionOptions) => {
         protocolDecisions.push(createReplayTraceProtocolDecision("coordinator", event, events.length - 1, decisionOptions));
     };
+    const drainOnParentAbort = (reasonSource) => {
+        const reason = classifyAbortReason(reasonSource);
+        for (const child of dispatchedChildren.values()) {
+            if (child.closed) {
+                continue;
+            }
+            const partialCost = child.started
+                ? lastCostBearingEventCost(child.childEvents) ?? emptyCost()
+                : emptyCost();
+            const partialTrace = buildPartialTrace({
+                childRunId: child.childRunId,
+                events: [...child.childEvents],
+                startedAtMs: child.startedAtMs,
+                protocol: child.decision.protocol,
+                tier: options.tier,
+                modelProviderId: options.model.id,
+                agents: options.agents,
+                intent: child.decision.intent,
+                temperature: options.temperature,
+                ...(child.childTimeoutMs !== undefined ? { childTimeoutMs: child.childTimeoutMs } : {}),
+                ...(options.seed !== undefined ? { seed: options.seed } : {})
+            });
+            const failedEvent = {
+                type: "sub-run-failed",
+                runId,
+                at: new Date().toISOString(),
+                childRunId: child.childRunId,
+                parentRunId: runId,
+                parentDecisionId: child.parentDecisionId,
+                parentDecisionArrayIndex: child.parentDecisionArrayIndex,
+                error: child.started
+                    ? {
+                        code: "aborted",
+                        message: "Parent run aborted.",
+                        detail: {
+                            reason
+                        }
+                    }
+                    : {
+                        code: "aborted",
+                        message: "Sibling delegate failed; queued delegate never started.",
+                        detail: {
+                            reason: "sibling-failed"
+                        }
+                    },
+                partialTrace,
+                partialCost
+            };
+            child.closed = true;
+            totalCost = addCost(totalCost, partialCost);
+            emit(failedEvent);
+            recordProtocolDecision(failedEvent);
+        }
+    };
+    options.registerAbortDrain?.(drainOnParentAbort);
     const toolExecutor = createRuntimeToolExecutor({
         runId,
         protocol: "coordinator",
@@ -61,24 +181,265 @@ export async function runCoordinator(options) {
     }
     if (coordinator) {
         if (!stopIfNeeded()) {
-            totalCost = await runCoordinatorTurn({
-                agent: coordinator,
-                coordinator,
-                input: buildCoordinatorPlanInput(options.intent, coordinator),
-                phase: "plan",
-                options,
-                runId,
-                transcript,
-                totalCost,
-                providerCalls,
-                toolExecutor,
-                toolAvailability,
-                events,
-                startedAtMs,
-                wrapUpHint,
-                emit,
-                recordProtocolDecision
-            });
+            // Delegate dispatch loop (D-11/D-16/D-17/D-18). Phase 1 limits delegation
+            // to the coordinator's plan turn; workers cannot delegate. The loop
+            // re-issues the coordinator plan turn after each successful sub-run with
+            // the projected D-17 result tagged into the next prompt and a synthetic
+            // D-18 transcript entry already appended. `partialTrace` for failed
+            // sub-runs is captured via a tee'd emit buffer locally — `runProtocol`'s
+            // error contract is unchanged.
+            let dispatchInput = buildCoordinatorPlanInput(options.intent, coordinator);
+            let dispatchCount = 0;
+            while (true) {
+                const turnOutcome = await runCoordinatorTurn({
+                    agent: coordinator,
+                    coordinator,
+                    input: dispatchInput,
+                    phase: "plan",
+                    options,
+                    runId,
+                    transcript,
+                    totalCost,
+                    providerCalls,
+                    toolExecutor,
+                    toolAvailability,
+                    events,
+                    startedAtMs,
+                    wrapUpHint,
+                    emit,
+                    recordProtocolDecision
+                });
+                totalCost = turnOutcome.totalCost;
+                if (turnOutcome.decision === undefined) {
+                    break;
+                }
+                const delegates = Array.isArray(turnOutcome.decision)
+                    ? turnOutcome.decision
+                    : turnOutcome.decision.type === "delegate"
+                        ? [turnOutcome.decision]
+                        : [];
+                if (delegates.length === 0) {
+                    break;
+                }
+                if (dispatchCount + delegates.length > MAX_DISPATCH_PER_TURN) {
+                    throw new DogpileError({
+                        code: "invalid-configuration",
+                        message: `Coordinator plan turn delegated ${delegates.length} more children after ${dispatchCount}; max is ${MAX_DISPATCH_PER_TURN}.`,
+                        retryable: false,
+                        detail: {
+                            kind: "delegate-validation",
+                            path: "decision",
+                            reason: "loop-guard-exceeded",
+                            maxDispatchPerTurn: MAX_DISPATCH_PER_TURN
+                        }
+                    });
+                }
+                const parentDecisionId = String(events.length - 1);
+                const parentDepth = options.currentDepth ?? 0;
+                const decisionMax = delegates.reduce((max, delegate) => Math.min(max, delegate.maxConcurrentChildren ?? Number.POSITIVE_INFINITY), Number.POSITIVE_INFINITY);
+                let effectiveForTurn = Math.min(options.effectiveMaxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN, decisionMax);
+                const requestedMax = effectiveForTurn;
+                const localProvider = findFirstLocalProvider(options);
+                if (localProvider !== undefined) {
+                    effectiveForTurn = 1;
+                    if (!concurrencyClampEmitted) {
+                        const clampEvent = {
+                            type: "sub-run-concurrency-clamped",
+                            runId,
+                            at: new Date().toISOString(),
+                            requestedMax,
+                            effectiveMax: 1,
+                            reason: "local-provider-detected",
+                            providerId: localProvider.id
+                        };
+                        emit(clampEvent);
+                        recordProtocolDecision(clampEvent);
+                        concurrencyClampEmitted = true;
+                    }
+                }
+                const semaphore = createSemaphore(effectiveForTurn);
+                const childRunIds = delegates.map(() => createRunId());
+                const dispatchedForTurn = delegates.map((delegate, index) => {
+                    const childRunId = childRunIds[index];
+                    if (childRunId === undefined) {
+                        throw new Error("missing child run id");
+                    }
+                    const dispatchedChild = {
+                        childRunId,
+                        decision: delegate,
+                        parentDecisionId,
+                        parentDecisionArrayIndex: index,
+                        parentDepth,
+                        controller: new AbortController(),
+                        removeParentListener: undefined,
+                        childEvents: [],
+                        started: false,
+                        closed: false,
+                        startedAtMs: Date.now(),
+                        childTimeoutMs: undefined,
+                        failure: undefined
+                    };
+                    dispatchedChildren.set(childRunId, dispatchedChild);
+                    return dispatchedChild;
+                });
+                const dispatchResults = [];
+                let firstFailureIndex;
+                const tasks = delegates.map(async (delegate, index) => {
+                    const childRunId = childRunIds[index];
+                    if (childRunId === undefined) {
+                        throw new Error("missing child run id");
+                    }
+                    if (semaphore.inFlight >= effectiveForTurn) {
+                        const queuedEvent = {
+                            type: "sub-run-queued",
+                            runId,
+                            at: new Date().toISOString(),
+                            childRunId,
+                            parentRunId: runId,
+                            parentDecisionId,
+                            parentDecisionArrayIndex: index,
+                            protocol: delegate.protocol,
+                            intent: delegate.intent,
+                            depth: parentDepth + 1,
+                            queuePosition: semaphore.queued
+                        };
+                        emit(queuedEvent);
+                        recordProtocolDecision(queuedEvent);
+                    }
+                    await semaphore.acquire();
+                    try {
+                        const dispatchedChild = dispatchedForTurn[index];
+                        if (!dispatchedChild) {
+                            throw new Error("missing dispatched child");
+                        }
+                        if (firstFailureIndex !== undefined) {
+                            if (dispatchedChild.closed) {
+                                dispatchResults.push({
+                                    index,
+                                    result: {
+                                        nextInput: "",
+                                        taggedText: `[sub-run ${childRunId}]: skipped because the parent run aborted`,
+                                        completedAtMs: Date.now()
+                                    }
+                                });
+                                return;
+                            }
+                            const partialCost = emptyCost();
+                            const partialTrace = buildPartialTrace({
+                                childRunId,
+                                events: [],
+                                startedAtMs: Date.now(),
+                                protocol: delegate.protocol,
+                                tier: options.tier,
+                                modelProviderId: options.model.id,
+                                agents: options.agents,
+                                intent: delegate.intent,
+                                temperature: options.temperature,
+                                ...(options.seed !== undefined ? { seed: options.seed } : {})
+                            });
+                            const failedEvent = {
+                                type: "sub-run-failed",
+                                runId,
+                                at: new Date().toISOString(),
+                                childRunId,
+                                parentRunId: runId,
+                                parentDecisionId,
+                                parentDecisionArrayIndex: index,
+                                error: {
+                                    code: "aborted",
+                                    message: "Sibling delegate failed; queued delegate never started.",
+                                    detail: {
+                                        reason: "sibling-failed"
+                                    }
+                                },
+                                partialTrace,
+                                partialCost
+                            };
+                            emit(failedEvent);
+                            recordProtocolDecision(failedEvent);
+                            dispatchedChild.closed = true;
+                            dispatchResults.push({
+                                index,
+                                result: {
+                                    nextInput: "",
+                                    taggedText: `[sub-run ${childRunId}]: skipped because a sibling delegate failed`,
+                                    completedAtMs: Date.now()
+                                }
+                            });
+                            return;
+                        }
+                        const result = await dispatchDelegate({
+                            decision: delegate,
+                            childRunId,
+                            parentDecisionId,
+                            parentDecisionArrayIndex: index,
+                            parentDepth,
+                            parentRunId: runId,
+                            options,
+                            transcript,
+                            emit,
+                            recordProtocolDecision,
+                            recordSubRunCost: (cost) => {
+                                totalCost = addCost(totalCost, cost);
+                            },
+                            dispatchedChild
+                        });
+                        dispatchResults.push({ index, result });
+                    }
+                    catch (error) {
+                        firstFailureIndex ??= index;
+                        const dispatchedChild = dispatchedForTurn[index];
+                        const failure = dispatchedChild?.failure;
+                        if (delegates.length === 1 &&
+                            (options.onChildFailure === "abort" || failure === undefined || isDelegateValidationError(error))) {
+                            throw error;
+                        }
+                        const failureMessage = error instanceof Error ? error.message : String(error);
+                        let taggedText = `[sub-run ${childRunId} failed]: ${failureMessage}`;
+                        if (failure) {
+                            const error = failure.error;
+                            taggedText = `[sub-run ${childRunId} failed | code=${error.code} | spent=$${failure.partialCost.usd.toFixed(3)}]: ${error.message}`;
+                        }
+                        dispatchResults.push({
+                            index,
+                            result: {
+                                nextInput: "",
+                                taggedText,
+                                completedAtMs: Date.now()
+                            }
+                        });
+                    }
+                    finally {
+                        semaphore.release();
+                    }
+                });
+                const settled = await Promise.allSettled(tasks);
+                const firstRejected = settled.find((result) => result.status === "rejected");
+                if (firstRejected?.status === "rejected" &&
+                    delegates.length === 1 &&
+                    (options.onChildFailure === "abort" || dispatchResults.length === 0)) {
+                    throw firstRejected.reason;
+                }
+                dispatchResults.sort((a, b) => a.result.completedAtMs - b.result.completedAtMs);
+                const taggedResults = dispatchResults.map((entry) => entry.result.taggedText).join("\n\n");
+                const currentWaveFailures = dispatchedForTurn
+                    .map((child) => child.failure)
+                    .filter((failure) => failure !== undefined);
+                if (options.onChildFailure === "abort" && currentWaveFailures.length > 0) {
+                    triggeringFailureForAbortMode ??= currentWaveFailures[0];
+                    break;
+                }
+                const failuresSection = buildFailuresSection(currentWaveFailures);
+                const coordinatorAgent = options.agents[0] ?? { id: "coordinator", role: "coordinator" };
+                const baseInput = buildCoordinatorPlanInput(options.intent, coordinatorAgent);
+                dispatchInput = [
+                    baseInput,
+                    taggedResults,
+                    failuresSection,
+                    "Using the sub-run results above, decide the next step (participate or delegate)."
+                ].filter((section) => Boolean(section)).join("\n\n");
+                dispatchCount += delegates.length;
+            }
             stopIfNeeded();
         }
         if (!stopIfNeeded()) {
@@ -136,7 +497,7 @@ export async function runCoordinator(options) {
             stopIfNeeded();
         }
         if (!stopIfNeeded()) {
-            totalCost = await runCoordinatorTurn({
+            const synthesisOutcome = await runCoordinatorTurn({
                 agent: coordinator,
                 coordinator,
                 input: buildFinalSynthesisInput(options.intent, transcript, coordinator),
@@ -154,6 +515,20 @@ export async function runCoordinator(options) {
                 emit,
                 recordProtocolDecision
             });
+            totalCost = synthesisOutcome.totalCost;
+            // Phase 1: final-synthesis turn cannot delegate.
+            if (Array.isArray(synthesisOutcome.decision) || synthesisOutcome.decision?.type === "delegate") {
+                throw new DogpileError({
+                    code: "invalid-configuration",
+                    message: "Coordinator final-synthesis turn cannot emit a delegate decision in Phase 1",
+                    retryable: false,
+                    detail: {
+                        kind: "delegate-validation",
+                        path: "decision",
+                        phase: "final-synthesis"
+                    }
+                });
+            }
             stopIfNeeded();
         }
     }
@@ -173,44 +548,46 @@ export async function runCoordinator(options) {
         transcriptEntryCount: transcript.length
     });
     const finalEvent = events.at(-1);
+    const trace = {
+        schemaVersion: "1.0",
+        runId,
+        protocol: "coordinator",
+        tier: options.tier,
+        modelProviderId: options.model.id,
+        agentsUsed: activeAgents,
+        inputs: createReplayTraceRunInputs({
+            intent: options.intent,
+            protocol: options.protocol,
+            tier: options.tier,
+            modelProviderId: options.model.id,
+            agents: activeAgents,
+            temperature: options.temperature
+        }),
+        budget: createReplayTraceBudget({
+            tier: options.tier,
+            ...(options.budget ? { caps: options.budget } : {}),
+            ...(options.terminate ? { termination: options.terminate } : {})
+        }),
+        budgetStateChanges: createReplayTraceBudgetStateChanges(events),
+        seed: createReplayTraceSeed(options.seed),
+        protocolDecisions,
+        providerCalls,
+        finalOutput: createReplayTraceFinalOutput(output, finalEvent ?? {
+            type: "final",
+            runId,
+            at: "",
+            output,
+            cost: totalCost,
+            transcript: createTranscriptLink(transcript)
+        }),
+        ...(triggeringFailureForAbortMode !== undefined ? { triggeringFailureForAbortMode } : {}),
+        events,
+        transcript
+    };
     return {
         output,
         eventLog: createRunEventLog(runId, "coordinator", events),
-        trace: {
-            schemaVersion: "1.0",
-            runId,
-            protocol: "coordinator",
-            tier: options.tier,
-            modelProviderId: options.model.id,
-            agentsUsed: activeAgents,
-            inputs: createReplayTraceRunInputs({
-                intent: options.intent,
-                protocol: options.protocol,
-                tier: options.tier,
-                modelProviderId: options.model.id,
-                agents: activeAgents,
-                temperature: options.temperature
-            }),
-            budget: createReplayTraceBudget({
-                tier: options.tier,
-                ...(options.budget ? { caps: options.budget } : {}),
-                ...(options.terminate ? { termination: options.terminate } : {})
-            }),
-            budgetStateChanges: createReplayTraceBudgetStateChanges(events),
-            seed: createReplayTraceSeed(options.seed),
-            protocolDecisions,
-            providerCalls,
-            finalOutput: createReplayTraceFinalOutput(output, finalEvent ?? {
-                type: "final",
-                runId,
-                at: "",
-                output,
-                cost: totalCost,
-                transcript: createTranscriptLink(transcript)
-            }),
-            events,
-            transcript
-        },
+        trace,
         transcript,
         usage: createRunUsage(totalCost),
         metadata: createRunMetadata({
@@ -228,7 +605,8 @@ export async function runCoordinator(options) {
             cost: totalCost,
             events
         }),
-        cost: totalCost
+        cost: totalCost,
+        health: computeHealth(trace, DEFAULT_HEALTH_THRESHOLDS)
     };
     function stopIfNeeded() {
         throwIfAborted(options.signal, options.model.id);
@@ -273,6 +651,10 @@ export async function runCoordinator(options) {
         });
     }
 }
+function isDelegateValidationError(error) {
+    return DogpileError.isInstance(error) && error.code === "invalid-configuration" &&
+        error.detail?.["kind"] === "delegate-validation";
+}
 async function runCoordinatorTurn(turn) {
     throwIfAborted(turn.options.signal, turn.options.model.id);
     const request = {
@@ -319,7 +701,11 @@ async function runCoordinatorTurn(turn) {
             turn.providerCalls.push(call);
         }
     });
-    const decision = parseAgentDecision(response.text);
+    const decision = parseAgentDecision(response.text, {
+        parentProviderId: turn.options.model.id,
+        currentDepth: turn.options.currentDepth ?? 0,
+        maxDepth: turn.options.effectiveMaxDepth ?? Number.POSITIVE_INFINITY
+    });
     const totalCost = addCost(turn.totalCost, responseCost(response));
     const toolCalls = await executeModelResponseToolRequests({
         response,
@@ -357,7 +743,7 @@ async function runCoordinatorTurn(turn) {
         phase: turn.phase,
         transcriptEntryCount: turn.transcript.length
     });
-    return totalCost;
+    return { totalCost, decision };
 }
 async function runCoordinatorWorkerTurn(turn) {
     throwIfAborted(turn.options.signal, turn.options.model.id);
@@ -405,7 +791,23 @@ async function runCoordinatorWorkerTurn(turn) {
             turn.providerCallSlots[turn.providerCallIndex] = call;
         }
     });
-    const decision = parseAgentDecision(response.text);
+    const decision = parseAgentDecision(response.text, {
+        parentProviderId: turn.options.model.id,
+        currentDepth: turn.options.currentDepth ?? 0,
+        maxDepth: turn.options.effectiveMaxDepth ?? Number.POSITIVE_INFINITY
+    });
+    if (Array.isArray(decision) || decision?.type === "delegate") {
+        throw new DogpileError({
+            code: "invalid-configuration",
+            message: "Workers cannot emit delegate decisions in Phase 1",
+            retryable: false,
+            detail: {
+                kind: "delegate-validation",
+                path: "decision",
+                phase: "worker"
+            }
+        });
+    }
     const toolCalls = await executeModelResponseToolRequests({
         response,
         executor: turn.toolExecutor,
@@ -436,6 +838,34 @@ function buildSystemPrompt(agent, coordinator) {
 function buildCoordinatorPlanInput(intent, coordinator) {
     return `Mission: ${intent}\nCoordinator ${coordinator.id}: assign the work, name the plan, and provide the first contribution.`;
 }
+function buildFailuresSection(failures) {
+    if (failures.length === 0) {
+        return null;
+    }
+    return [
+        "## Sub-run failures since last decision",
+        "",
+        "```json",
+        JSON.stringify(failures, null, 2),
+        "```"
+    ].join("\n");
+}
+function dispatchWaveFailureFromEvent(intent, event) {
+    const reason = typeof event.error.detail?.["reason"] === "string" ? event.error.detail["reason"] : undefined;
+    if (reason === "sibling-failed" || reason === "parent-aborted") {
+        return undefined;
+    }
+    return {
+        childRunId: event.childRunId,
+        intent,
+        error: {
+            code: event.error.code,
+            message: event.error.message,
+            ...(reason !== undefined ? { detail: { reason } } : {})
+        },
+        partialCost: { usd: event.partialCost.usd }
+    };
+}
 function buildWorkerInput(intent, transcript, coordinator) {
     const prior = transcript
         .map((entry) => `${entry.role} (${entry.agentId}): ${entry.output}`)
@@ -456,4 +886,492 @@ function responseCost(response) {
         totalTokens: response.usage?.totalTokens ?? 0
     };
 }
+/**
+ * Dispatch a single delegate decision as a recursive sub-run.
+ *
+ * D-11: child reuses the parent provider object verbatim.
+ * D-16: `recursive: true` flag set when both parent and child protocol are
+ *   `coordinator`.
+ * D-17: tagged result text appended to the next coordinator prompt.
+ * D-18: synthetic transcript entry pushed for replay/provenance.
+ *
+ * On thrown error from the child engine, builds `partialTrace` from a locally
+ * tee'd `childEvents` buffer — `runProtocol`'s error contract is unchanged.
+ */
+async function dispatchDelegate(input) {
+    const { decision, options } = input;
+    // Dispatcher-time depth gate (D-14). Same error shape as the parser; this
+    // is the TOCTOU defense for any state mutation between parse and dispatch.
+    // Fires BEFORE sub-run-started is emitted so failed dispatches do not show
+    // up in the trace as half-started sub-runs.
+    if (options.effectiveMaxDepth !== undefined) {
+        assertDepthWithinLimit(input.parentDepth, options.effectiveMaxDepth);
+    }
+    const childRunId = input.childRunId ?? createRunId();
+    const recursive = decision.protocol === "coordinator";
+    const decisionTimeoutMs = decision.budget?.timeoutMs;
+    const parentDeadlineMs = options.parentDeadlineMs;
+    // BUDGET-02 / D-12: deadline-based remaining-time math. Children inherit
+    // `parentDeadlineMs - now()`, not a static `parent.budget.timeoutMs`. If the
+    // parent's deadline has already elapsed, throw `code: "aborted"` with
+    // `detail.reason: "timeout"` BEFORE `sub-run-started` is emitted.
+    const remainingMs = parentDeadlineMs !== undefined ? Math.max(0, parentDeadlineMs - Date.now()) : undefined;
+    if (parentDeadlineMs !== undefined && remainingMs === 0) {
+        throw new DogpileError({
+            code: "aborted",
+            message: "Parent deadline elapsed before sub-run dispatch.",
+            retryable: false,
+            providerId: options.model.id,
+            detail: { reason: "timeout" }
+        });
+    }
+    // Resolve child timeout with precedence (D-12 / D-14):
+    //   decision.budget.timeoutMs > parent's remaining > defaultSubRunTimeoutMs > undefined.
+    // When the decision-level timeout exceeds the parent's remaining, CLAMP
+    // (no longer throw) and emit a `sub-run-budget-clamped` event below.
+    let childTimeoutMs;
+    let clampedFrom;
+    if (remainingMs !== undefined) {
+        if (decisionTimeoutMs !== undefined) {
+            if (decisionTimeoutMs > remainingMs) {
+                clampedFrom = decisionTimeoutMs;
+                childTimeoutMs = remainingMs;
+            }
+            else {
+                childTimeoutMs = decisionTimeoutMs;
+            }
+        }
+        else {
+            childTimeoutMs = remainingMs;
+        }
+    }
+    else if (decisionTimeoutMs !== undefined) {
+        childTimeoutMs = decisionTimeoutMs;
+    }
+    else if (options.defaultSubRunTimeoutMs !== undefined) {
+        childTimeoutMs = options.defaultSubRunTimeoutMs;
+    }
+    if (!options.runProtocol) {
+        throw new DogpileError({
+            code: "invalid-configuration",
+            message: "Coordinator delegate dispatch requires the engine `runProtocol` callback. " +
+                "Use `Dogpile.run` / `createEngine` rather than calling `runCoordinator` directly when delegate is in play.",
+            retryable: false,
+            detail: {
+                kind: "delegate-validation",
+                path: "runProtocol"
+            }
+        });
+    }
+    // Buffered tee for partialTrace capture — see Plan 03 step 8.
+    const childEvents = input.dispatchedChild.childEvents;
+    const parentEmit = input.emit;
+    const teedEmit = (event) => {
+        childEvents.push(event);
+        if (input.dispatchedChild.closed) {
+            return;
+        }
+        if (options.streamEvents && options.emit) {
+            const inbound = event.parentRunIds;
+            options.emit({
+                ...event,
+                parentRunIds: [input.parentRunId, ...(inbound ?? [])]
+            });
+        }
+    };
+    const childStartedAt = Date.now();
+    input.dispatchedChild.startedAtMs = childStartedAt;
+    // BUDGET-02 / D-12: emit clamp event BEFORE sub-run-started so the trace
+    // records "this child's requested timeout was reduced to fit parent's
+    // remaining deadline." Skipped on the happy path (no clamp, no event).
+    if (clampedFrom !== undefined && childTimeoutMs !== undefined) {
+        const clampEvent = {
+            type: "sub-run-budget-clamped",
+            runId: input.parentRunId,
+            at: new Date().toISOString(),
+            childRunId,
+            parentRunId: input.parentRunId,
+            parentDecisionId: input.parentDecisionId,
+            requestedTimeoutMs: clampedFrom,
+            clampedTimeoutMs: childTimeoutMs,
+            reason: "exceeded-parent-remaining"
+        };
+        input.emit(clampEvent);
+        input.recordProtocolDecision(clampEvent);
+    }
+    const startEvent = {
+        type: "sub-run-started",
+        runId: input.parentRunId,
+        at: new Date().toISOString(),
+        childRunId,
+        parentRunId: input.parentRunId,
+        parentDecisionId: input.parentDecisionId,
+        parentDecisionArrayIndex: input.parentDecisionArrayIndex,
+        protocol: decision.protocol,
+        intent: decision.intent,
+        depth: input.parentDepth + 1,
+        ...(recursive ? { recursive: true } : {})
+    };
+    parentEmit(startEvent);
+    input.recordProtocolDecision(startEvent);
+    // BUDGET-01 / D-07: derive a per-child AbortController so child engines see
+    // their own signal. Listener forwards parent.signal.reason verbatim, so
+    // detail.reason classification (parent-aborted vs timeout) is preserved.
+    // Phase 4 STREAM-03 hook: per-child cancel handle attaches here.
+    const parentSignal = options.signal;
+    let removeParentAbortListener;
+    if (parentSignal !== undefined) {
+        if (parentSignal.aborted) {
+            input.dispatchedChild.controller.abort(parentSignal.reason);
+        }
+        else {
+            const handler = () => {
+                input.dispatchedChild.controller.abort(parentSignal.reason);
+            };
+            parentSignal.addEventListener("abort", handler, { once: true });
+            removeParentAbortListener = () => {
+                parentSignal.removeEventListener("abort", handler);
+            };
+        }
+    }
+    input.dispatchedChild.removeParentListener = removeParentAbortListener;
+    input.dispatchedChild.started = true;
+    input.dispatchedChild.childTimeoutMs = childTimeoutMs;
+    const childDeadlineReason = childTimeoutMs !== undefined && parentDeadlineMs === undefined
+        ? createEngineDeadlineTimeoutError(options.model.id, childTimeoutMs)
+        : undefined;
+    const childDeadlineTimer = childDeadlineReason !== undefined
+        ? setTimeout(() => {
+            input.dispatchedChild.controller.abort(childDeadlineReason);
+        }, childTimeoutMs)
+        : undefined;
+    const childOptions = {
+        runId: childRunId,
+        intent: decision.intent,
+        protocol: decision.protocol,
+        tier: options.tier,
+        model: options.model, // D-11: same provider instance verbatim
+        agents: options.agents,
+        tools: options.tools,
+        temperature: options.temperature,
+        ...(childTimeoutMs !== undefined ? { budget: { timeoutMs: childTimeoutMs } } : {}),
+        signal: input.dispatchedChild.controller.signal,
+        emit: teedEmit,
+        ...(options.streamEvents !== undefined ? { streamEvents: options.streamEvents } : {}),
+        currentDepth: input.parentDepth + 1,
+        ...(options.effectiveMaxDepth !== undefined ? { effectiveMaxDepth: options.effectiveMaxDepth } : {}),
+        ...(options.effectiveMaxConcurrentChildren !== undefined
+            ? { effectiveMaxConcurrentChildren: options.effectiveMaxConcurrentChildren }
+            : {}),
+        ...(options.onChildFailure !== undefined ? { onChildFailure: options.onChildFailure } : {}),
+        // BUDGET-02 / D-12: forward the ROOT deadline so depth-N grandchildren
+        // see the same `parentDeadlineMs` rather than a fresh per-level snapshot.
+        ...(parentDeadlineMs !== undefined ? { parentDeadlineMs } : {}),
+        ...(options.defaultSubRunTimeoutMs !== undefined
+            ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs }
+            : {})
+    };
+    let subResult;
+    try {
+        subResult = await options.runProtocol(childOptions);
+    }
+    catch (error) {
+        if (childDeadlineTimer !== undefined) {
+            clearTimeout(childDeadlineTimer);
+        }
+        removeParentAbortListener?.();
+        if (input.dispatchedChild.closed) {
+            const enrichedError = enrichAbortErrorWithParentReason(error, parentSignal);
+            if (DogpileError.isInstance(enrichedError)) {
+                throw enrichedError;
+            }
+            throw error;
+        }
+        const failedDecision = {
+            type: "delegate",
+            protocol: decision.protocol,
+            intent: decision.intent,
+            ...(decision.model !== undefined ? { model: decision.model } : {}),
+            ...(decision.budget !== undefined ? { budget: decision.budget } : {})
+        };
+        const partialTrace = buildPartialTrace({
+            childRunId,
+            events: childEvents,
+            startedAtMs: childStartedAt,
+            protocol: decision.protocol,
+            tier: options.tier,
+            modelProviderId: options.model.id,
+            agents: options.agents,
+            intent: decision.intent,
+            temperature: options.temperature,
+            ...(childTimeoutMs !== undefined ? { childTimeoutMs } : {}),
+            ...(options.seed !== undefined ? { seed: options.seed } : {})
+        });
+        // BUDGET-01 / D-08: when the child aborted because the parent.signal
+        // aborted, lock detail.reason on the surfaced error. Upstream engine
+        // wrapping (e.g., createStreamCancellationError) attaches its own
+        // detail.status; we add detail.reason so consumers can discriminate
+        // parent-aborted vs timeout regardless of which engine path produced the
+        // abort error.
+        const enrichedError = enrichProviderTimeoutSource(enrichAbortErrorWithParentReason(error, parentSignal), {
+            ...(decisionTimeoutMs !== undefined ? { decisionTimeoutMs } : {}),
+            ...(options.defaultSubRunTimeoutMs !== undefined
+                ? { engineDefaultTimeoutMs: options.defaultSubRunTimeoutMs }
+                : {})
+        });
+        if (DogpileError.isInstance(enrichedError)) {
+            options.failureInstancesByChildRunId?.set(childRunId, enrichedError);
+        }
+        const errorPayload = errorPayloadFromUnknown(enrichedError, failedDecision);
+        // BUDGET-03 / D-02: capture real provider spend before the throw and
+        // roll it into the parent's totalCost BEFORE emitting sub-run-failed.
+        const partialCost = lastCostBearingEventCost(childEvents) ?? emptyCost();
+        input.recordSubRunCost(partialCost);
+        const failEvent = {
+            type: "sub-run-failed",
+            runId: input.parentRunId,
+            at: new Date().toISOString(),
+            childRunId,
+            parentRunId: input.parentRunId,
+            parentDecisionId: input.parentDecisionId,
+            parentDecisionArrayIndex: input.parentDecisionArrayIndex,
+            error: errorPayload,
+            partialTrace,
+            partialCost
+        };
+        parentEmit(failEvent);
+        input.recordProtocolDecision(failEvent);
+        input.dispatchedChild.closed = true;
+        input.dispatchedChild.failure = dispatchWaveFailureFromEvent(decision.intent, failEvent);
+        // Re-throw a DogpileError so the parent run terminates with a typed error.
+        if (DogpileError.isInstance(enrichedError)) {
+            throw enrichedError;
+        }
+        throw new DogpileError({
+            code: "invalid-configuration",
+            message: error instanceof Error ? error.message : String(error),
+            retryable: false,
+            detail: {
+                kind: "delegate-validation",
+                path: "decision",
+                reason: "child-run-failed"
+            }
+        });
+    }
+    if (childDeadlineTimer !== undefined) {
+        clearTimeout(childDeadlineTimer);
+    }
+    removeParentAbortListener?.();
+    // BUDGET-03 / D-01: roll child's full cost into the parent's totalCost
+    // BEFORE emitting sub-run-completed. The next agent-turn / final event will
+    // read totalCost from the closure scope, preserving the existing
+    // "last cost-bearing event === final.cost" invariant.
+    input.recordSubRunCost(subResult.cost);
+    const completedEvent = {
+        type: "sub-run-completed",
+        runId: input.parentRunId,
+        at: new Date().toISOString(),
+        childRunId,
+        parentRunId: input.parentRunId,
+        parentDecisionId: input.parentDecisionId,
+        parentDecisionArrayIndex: input.parentDecisionArrayIndex,
+        subResult
+    };
+    parentEmit(completedEvent);
+    input.recordProtocolDecision(completedEvent);
+    input.dispatchedChild.closed = true;
+    // BUDGET-01 / D-10: parent.signal aborted AFTER the child completed but
+    // before we advance to the next coordinator turn. Emit a marker event so
+    // streaming subscribers see "parent gave up after sub-run" provenance,
+    // then re-throw the parent's abort reason. Non-streaming run() rejects with
+    // the thrown error and does NOT preserve the marker — engine.ts does not
+    // attach the parent events array to the rejected error (verified at
+    // engine.ts:230-239). Streaming-subscriber observability is the contract.
+    if (parentSignal?.aborted) {
+        const abortMarker = {
+            type: "sub-run-parent-aborted",
+            runId: input.parentRunId,
+            at: new Date().toISOString(),
+            childRunId,
+            parentRunId: input.parentRunId,
+            reason: "parent-aborted"
+        };
+        parentEmit(abortMarker);
+        input.recordProtocolDecision(abortMarker);
+        throw enrichAbortErrorWithParentReason(createAbortErrorFromSignal(parentSignal, options.model.id), parentSignal);
+    }
+    // D-18 synthetic transcript entry.
+    const decisionAsJson = {
+        type: "delegate",
+        protocol: decision.protocol,
+        intent: decision.intent,
+        ...(decision.model !== undefined ? { model: decision.model } : {}),
+        ...(decision.budget !== undefined ? { budget: decision.budget } : {})
+    };
+    const taggedText = renderSubRunResult(childRunId, subResult);
+    input.transcript.push({
+        agentId: `sub-run:${childRunId}`,
+        role: "delegate-result",
+        input: JSON.stringify(decisionAsJson),
+        output: taggedText
+    });
+    // Build the next coordinator prompt by appending the D-17 tagged block.
+    const coordinatorAgent = options.agents[0];
+    const baseInput = buildCoordinatorPlanInput(input.options.intent, coordinatorAgent ?? {
+        id: "coordinator",
+        role: "coordinator"
+    });
+    return {
+        nextInput: `${baseInput}\n\n${taggedText}\n\nUsing the sub-run result above, decide the next step (participate or delegate).`,
+        taggedText,
+        completedAtMs: Date.now()
+    };
+}
+/**
+ * D-17 prompt-injection helper. Renders a child `RunResult` as the canonical
+ * tagged-result block injected into the parent coordinator's next prompt.
+ *
+ * Format:
+ *   `[sub-run <childRunId>]: <output>`
+ *   `[sub-run <childRunId> stats]: turns=<N> costUsd=<X> durationMs=<Y>`
+ *
+ * The stats line is a soft contract — field names stable, ordering stable.
+ */
+function renderSubRunResult(childRunId, subResult) {
+    const turns = subResult.transcript.length;
+    const costUsd = subResult.cost.usd ?? 0;
+    const startedAt = eventTimestamp(subResult.trace.events[0]);
+    const endedAt = eventTimestamp(subResult.trace.events.at(-1));
+    const durationMs = startedAt && endedAt
+        ? Math.max(0, Date.parse(endedAt) - Date.parse(startedAt))
+        : 0;
+    return [
+        `[sub-run ${childRunId}]: ${subResult.output}`,
+        `[sub-run ${childRunId} stats]: turns=${turns} costUsd=${costUsd} durationMs=${durationMs}`
+    ].join("\n");
+}
+function eventTimestamp(event) {
+    if (event === undefined)
+        return undefined;
+    if ("at" in event)
+        return event.at;
+    return event.type === "model-response" ? event.completedAt : event.startedAt;
+}
+/**
+ * Build a JSON-serializable {@link Trace} for `sub-run-failed.partialTrace`
+ * from a buffered tee of child emits. Keeps `runProtocol`'s error contract
+ * unchanged — Plan 03 step 8.
+ */
+function buildPartialTrace(input) {
+    const protocolName = typeof input.protocol === "string" ? input.protocol : input.protocol.kind;
+    const protocolConfig = typeof input.protocol === "string"
+        ? { kind: input.protocol }
+        : input.protocol;
+    return {
+        schemaVersion: "1.0",
+        runId: input.childRunId,
+        protocol: protocolName,
+        tier: input.tier,
+        modelProviderId: input.modelProviderId,
+        agentsUsed: input.agents,
+        inputs: createReplayTraceRunInputs({
+            intent: input.intent,
+            protocol: protocolConfig,
+            tier: input.tier,
+            modelProviderId: input.modelProviderId,
+            agents: input.agents,
+            temperature: input.temperature
+        }),
+        budget: createReplayTraceBudget({
+            tier: input.tier,
+            ...(input.childTimeoutMs !== undefined ? { caps: { timeoutMs: input.childTimeoutMs } } : {})
+        }),
+        budgetStateChanges: createReplayTraceBudgetStateChanges(input.events),
+        seed: createReplayTraceSeed(input.seed),
+        protocolDecisions: [],
+        providerCalls: [],
+        finalOutput: {
+            kind: "replay-trace-final-output",
+            output: "",
+            cost: emptyCost(),
+            completedAt: new Date().toISOString(),
+            transcript: createTranscriptLink([])
+        },
+        events: input.events,
+        transcript: []
+    };
+}
+/**
+ * BUDGET-01 / D-08: when a child sub-run threw because the parent's signal
+ * aborted, lock the `detail.reason` discriminator on the resulting
+ * `code: "aborted"` error. Preserves any pre-existing detail keys (e.g.,
+ * `detail.status: "cancelled"` attached by `createStreamCancellationError`).
+ *
+ * No-op when:
+ *   - parent.signal is undefined or not aborted (child failure was unrelated)
+ *   - error is not a DogpileError with `code: "aborted"`
+ *   - error already has a `detail.reason` set (preserve upstream classification)
+ */
+function enrichAbortErrorWithParentReason(error, parentSignal) {
+    if (parentSignal === undefined || !parentSignal.aborted) {
+        return error;
+    }
+    if (!DogpileError.isInstance(error) || error.code !== "aborted") {
+        return error;
+    }
+    const existingDetail = error.detail ?? {};
+    if (existingDetail["reason"] !== undefined) {
+        return error;
+    }
+    const reason = classifyAbortReason(parentSignal.reason);
+    return new DogpileError({
+        code: "aborted",
+        message: error.message,
+        retryable: error.retryable ?? false,
+        ...(error.providerId !== undefined ? { providerId: error.providerId } : {}),
+        detail: { ...existingDetail, reason },
+        ...(error.cause !== undefined ? { cause: error.cause } : {})
+    });
+}
+function enrichProviderTimeoutSource(error, context) {
+    if (!DogpileError.isInstance(error) || error.code !== "provider-timeout") {
+        return error;
+    }
+    const existingDetail = error.detail ?? {};
+    if (existingDetail["source"] !== undefined) {
+        return error;
+    }
+    const source = classifyChildTimeoutSource(error, {
+        ...context,
+        isProviderError: true
+    });
+    return new DogpileError({
+        code: "provider-timeout",
+        message: error.message,
+        retryable: error.retryable ?? true,
+        ...(error.providerId !== undefined ? { providerId: error.providerId } : {}),
+        detail: { ...existingDetail, source },
+        ...(error.cause !== undefined ? { cause: error.cause } : {})
+    });
+}
+function errorPayloadFromUnknown(error, failedDecision) {
+    if (DogpileError.isInstance(error)) {
+        const detail = {
+            ...(error.detail ?? {}),
+            failedDecision
+        };
+        return {
+            code: error.code,
+            message: error.message,
+            ...(error.providerId !== undefined ? { providerId: error.providerId } : {}),
+            detail
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: "invalid-configuration",
+        message,
+        detail: { failedDecision }
+    };
+}
 //# sourceMappingURL=coordinator.js.map