@dogpile/sdk 0.3.0 → 0.4.0

package/dist/browser/index.js

@@ -67,6 +67,39 @@ function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
+//#region src/runtime/ids.ts
+/**
+* Repo-internal id and timing helpers used across all four protocols.
+*
+* Centralized here so a change to id format or fallback semantics happens in
+* exactly one place — switching `protocol` must not change the run-id contract.
+*/
+/**
+* Generates a fresh run id using `globalThis.crypto.randomUUID`.
+*
+* Throws a `DogpileError` when no UUID source is available rather than falling
+* back to a millisecond-based id (which collides under back-to-back runs in
+* the same tick). Node 22+, Bun latest, and modern browsers all expose
+* `crypto.randomUUID`; environments without it are unsupported by Dogpile.
+*/
+function createRunId() {
+	const random = globalThis.crypto?.randomUUID?.();
+	if (typeof random === "string" && random.length > 0) return random;
+	throw new DogpileError({
+		code: "invalid-configuration",
+		message: "Dogpile requires globalThis.crypto.randomUUID to mint a run id. Run on Node 22+, Bun latest, or a modern browser ESM environment."
+	});
+}
+function nowMs() {
+	return globalThis.performance?.now() ?? Date.now();
+}
+function elapsedMs(startedAtMs) {
+	return Math.max(0, nowMs() - startedAtMs);
+}
+function providerCallIdFor(runId, oneBasedIndex) {
+	return `${runId}:provider-call:${oneBasedIndex}`;
+}
+//#endregion
 //#region src/runtime/defaults.ts
 function normalizeProtocol(protocol) {
 	if (typeof protocol !== "string") return protocol;
@@ -160,6 +193,27 @@ function addCost(left, right) {
 		totalTokens: left.totalTokens + right.totalTokens
 	};
 }
+function resolveOnChildFailure(runOption, engineOption) {
+	return runOption ?? engineOption ?? "continue";
+}
+/**
+* Walk a parent's events and accumulate the cost contributed by every
+* sub-run (BUDGET-03 / D-06). Internal helper — not part of the public surface.
+*
+* - `sub-run-completed` events contribute `event.subResult.cost`.
+* - `sub-run-failed` events contribute `event.partialCost` (real provider
+*   spend captured before the throw).
+*
+* Used by the `parent-rollup-drift` parity check in
+* {@link recomputeAccountingFromTrace} to verify the parent's recorded
+* accounting equals `localOnly + Σ children` recursively.
+*/
+function accumulateSubRunCost(events) {
+	let total = emptyCost();
+	for (const event of events) if (event.type === "sub-run-completed") total = addCost(total, event.subResult.cost);
+	else if (event.type === "sub-run-failed") total = addCost(total, event.partialCost);
+	return total;
+}
 function createTranscriptLink(transcript) {
 	return {
 		kind: "trace-transcript",
@@ -258,7 +312,14 @@ function createReplayTraceBudgetStateChanges(events) {
 			case "model-response":
 			case "model-output-chunk":
 			case "tool-call":
-			case "tool-result": return [];
+			case "tool-result":
+			case "sub-run-started":
+			case "sub-run-completed":
+			case "sub-run-failed":
+			case "sub-run-parent-aborted":
+			case "sub-run-budget-clamped":
+			case "sub-run-queued":
+			case "sub-run-concurrency-clamped": return [];
 		}
 	});
 }
@@ -355,6 +416,24 @@ function createReplayTraceProtocolDecision(protocol, event, eventIndex, options
 			output: event.output,
 			cost: event.cost
 		};
+		case "sub-run-started": return {
+			...base,
+			input: event.intent
+		};
+		case "sub-run-completed": return {
+			...base,
+			output: event.subResult.output,
+			cost: event.subResult.cost
+		};
+		case "sub-run-failed": return { ...base };
+		case "sub-run-parent-aborted": return { ...base };
+		case "sub-run-budget-clamped": return { ...base };
+		case "sub-run-queued": return {
+			...base,
+			childRunId: event.childRunId,
+			queuePosition: event.queuePosition
+		};
+		case "sub-run-concurrency-clamped": return { ...base };
 	}
 }
 function defaultProtocolDecision(event) {
@@ -369,6 +448,13 @@ function defaultProtocolDecision(event) {
 		case "broadcast": return "collect-broadcast-round";
 		case "budget-stop": return "stop-for-budget";
 		case "final": return "finalize-output";
+		case "sub-run-started": return "start-sub-run";
+		case "sub-run-completed": return "complete-sub-run";
+		case "sub-run-failed": return "fail-sub-run";
+		case "sub-run-parent-aborted": return "mark-sub-run-parent-aborted";
+		case "sub-run-budget-clamped": return "mark-sub-run-budget-clamped";
+		case "sub-run-queued": return "queue-sub-run";
+		case "sub-run-concurrency-clamped": return "mark-sub-run-concurrency-clamped";
 	}
 }
 function eventAgentScope(event) {
@@ -434,6 +520,216 @@ function canonicalizeRunResult(result) {
 function stableJsonStringify(value) {
 	return JSON.stringify(canonicalizeSerializable(value));
 }
+/**
+* The eight numeric fields recursively verified by `recomputeAccountingFromTrace`.
+*
+* These are the only summable scalars on `RunAccounting`. Non-numeric fields
+* (`kind`, `tier`, `budget`, `termination`, `budgetStateChanges`) and derived
+* ratios (`usdCapUtilization`, `totalTokenCapUtilization`) are NOT in this set.
+*/
+var RECOMPUTE_FIELD_ORDER = [
+	"cost.usd",
+	"cost.inputTokens",
+	"cost.outputTokens",
+	"cost.totalTokens",
+	"usage.usd",
+	"usage.inputTokens",
+	"usage.outputTokens",
+	"usage.totalTokens"
+];
+var USD_FIELDS = new Set(["cost.usd", "usage.usd"]);
+var FLOAT_EPSILON = 1e-9;
+function readNumericField(accounting, field) {
+	switch (field) {
+		case "cost.usd": return accounting.cost.usd;
+		case "cost.inputTokens": return accounting.cost.inputTokens;
+		case "cost.outputTokens": return accounting.cost.outputTokens;
+		case "cost.totalTokens": return accounting.cost.totalTokens;
+		case "usage.usd": return accounting.usage.usd;
+		case "usage.inputTokens": return accounting.usage.inputTokens;
+		case "usage.outputTokens": return accounting.usage.outputTokens;
+		case "usage.totalTokens": return accounting.usage.totalTokens;
+	}
+}
+function fieldsEqual(field, a, b) {
+	if (USD_FIELDS.has(field)) return Math.abs(a - b) < FLOAT_EPSILON;
+	return a === b;
+}
+function firstDifferingField(recorded, recomputed) {
+	for (const field of RECOMPUTE_FIELD_ORDER) {
+		const a = readNumericField(recorded, field);
+		const b = readNumericField(recomputed, field);
+		if (!fieldsEqual(field, a, b)) return {
+			field,
+			recorded: a,
+			recomputed: b
+		};
+	}
+	return null;
+}
+function buildLocalAccounting(trace) {
+	return createRunAccounting({
+		tier: trace.tier,
+		...trace.budget.caps ? { budget: trace.budget.caps } : {},
+		...trace.budget.termination ? { termination: trace.budget.termination } : {},
+		cost: trace.finalOutput.cost,
+		events: trace.events
+	});
+}
+function lastCostBearingEventCost(events) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event === void 0) continue;
+		if (event.type === "final" || event.type === "agent-turn" || event.type === "broadcast" || event.type === "budget-stop") return event.cost;
+	}
+	return null;
+}
+/**
+* Recompute a parent's `RunAccounting` from a saved `Trace` for replay-time
+* tamper detection.
+*
+* @remarks
+* Returns the parent's local `RunAccounting` (built the same way `replay()`
+* builds it today, from `trace.finalOutput.cost` and `trace.events`). While
+* walking events, every `sub-run-completed` is recursed into and the
+* recomputed child accounting is compared field-by-field to the recorded
+* `event.subResult.accounting`. A mismatch on any of the eight enumerated
+* numeric fields throws `DogpileError({ code: "invalid-configuration" })`
+* with `detail.reason: "trace-accounting-mismatch"` and a concrete
+* `detail.field` identifying the first differing numeric.
+*
+* Pure: no provider calls, no I/O, no clock reads.
+*
+* Non-summed fields (`kind`, `tier`, `budget`, `termination`,
+* `budgetStateChanges`) and derived ratios (`usdCapUtilization`,
+* `totalTokenCapUtilization`) are not in the comparison set.
+*/
+function recomputeAccountingFromTrace(trace) {
+	const local = buildLocalAccounting(trace);
+	const lastEventCost = lastCostBearingEventCost(trace.events);
+	if (lastEventCost !== null) {
+		const drift = firstDifferingField(local, createRunAccounting({
+			tier: trace.tier,
+			...trace.budget.caps ? { budget: trace.budget.caps } : {},
+			...trace.budget.termination ? { termination: trace.budget.termination } : {},
+			cost: lastEventCost,
+			events: trace.events
+		}));
+		if (drift !== null) throw new DogpileError({
+			code: "invalid-configuration",
+			message: `Trace accounting mismatch at parent run ${trace.runId}: field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed}.`,
+			retryable: false,
+			detail: {
+				kind: "trace-validation",
+				reason: "trace-accounting-mismatch",
+				eventIndex: -1,
+				childRunId: trace.runId,
+				field: drift.field,
+				recorded: drift.recorded,
+				recomputed: drift.recomputed
+			}
+		});
+	}
+	for (let eventIndex = 0; eventIndex < trace.events.length; eventIndex += 1) {
+		const event = trace.events[eventIndex];
+		if (event === void 0) continue;
+		if (event.type === "sub-run-completed") {
+			const childRecordedRollup = createRunAccounting({
+				tier: trace.tier,
+				cost: event.subResult.cost,
+				events: []
+			});
+			const childRecordedAccounting = event.subResult.accounting;
+			const drift = firstDifferingField(childRecordedAccounting, childRecordedRollup);
+			if (drift !== null) throw new DogpileError({
+				code: "invalid-configuration",
+				message: `Trace parent-rollup mismatch at sub-run ${event.childRunId}: field "${drift.field}" recorded ${drift.recorded} on accounting, ${drift.recomputed} on subResult.cost.`,
+				retryable: false,
+				detail: {
+					kind: "trace-validation",
+					reason: "trace-accounting-mismatch",
+					subReason: "parent-rollup-drift",
+					eventIndex,
+					childRunId: event.childRunId,
+					field: drift.field,
+					recorded: drift.recorded,
+					recomputed: drift.recomputed
+				}
+			});
+		} else if (event.type === "sub-run-failed") {
+			const partialFromTrace = lastCostBearingEventCost(event.partialTrace.events) ?? emptyCost();
+			const drift = firstDifferingField(createRunAccounting({
+				tier: trace.tier,
+				cost: event.partialCost,
+				events: []
+			}), createRunAccounting({
+				tier: trace.tier,
+				cost: partialFromTrace,
+				events: []
+			}));
+			if (drift !== null) throw new DogpileError({
+				code: "invalid-configuration",
+				message: `Trace parent-rollup mismatch at sub-run ${event.childRunId}: partialCost field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed} from partialTrace events.`,
+				retryable: false,
+				detail: {
+					kind: "trace-validation",
+					reason: "trace-accounting-mismatch",
+					subReason: "parent-rollup-drift",
+					eventIndex,
+					childRunId: event.childRunId,
+					field: drift.field,
+					recorded: drift.recorded,
+					recomputed: drift.recomputed
+				}
+			});
+		}
+	}
+	const subRunTotal = accumulateSubRunCost(trace.events);
+	const parentTotal = trace.finalOutput.cost;
+	for (const field of RECOMPUTE_FIELD_ORDER) {
+		if (field.startsWith("usage.")) continue;
+		const [, key] = field.split(".");
+		const parentValue = parentTotal[key];
+		const childValue = subRunTotal[key];
+		if (childValue - parentValue > FLOAT_EPSILON) throw new DogpileError({
+			code: "invalid-configuration",
+			message: `Trace parent-rollup mismatch at run ${trace.runId}: field "${field}" Σ children ${childValue} exceeds parent recorded ${parentValue}.`,
+			retryable: false,
+			detail: {
+				kind: "trace-validation",
+				reason: "trace-accounting-mismatch",
+				subReason: "parent-rollup-drift",
+				eventIndex: -1,
+				childRunId: trace.runId,
+				field,
+				recorded: parentValue,
+				recomputed: childValue
+			}
+		});
+	}
+	for (let eventIndex = 0; eventIndex < trace.events.length; eventIndex += 1) {
+		const event = trace.events[eventIndex];
+		if (event === void 0 || event.type !== "sub-run-completed") continue;
+		const childRecomputed = recomputeAccountingFromTrace(event.subResult.trace);
+		const childRecorded = event.subResult.accounting;
+		const drift = firstDifferingField(childRecorded, childRecomputed);
+		if (drift !== null) throw new DogpileError({
+			code: "invalid-configuration",
+			message: `Trace accounting mismatch at sub-run ${event.childRunId}: field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed}.`,
+			retryable: false,
+			detail: {
+				kind: "trace-validation",
+				reason: "trace-accounting-mismatch",
+				eventIndex,
+				childRunId: event.childRunId,
+				field: drift.field,
+				recorded: drift.recorded,
+				recomputed: drift.recomputed
+			}
+		});
+	}
+	return local;
+}
 function canonicalizeSerializable(value) {
 	if (Array.isArray(value)) return value.map((item) => canonicalizeSerializable(item));
 	if (typeof value === "number") {
@@ -452,6 +748,24 @@ function canonicalizeSerializable(value) {
 }
 //#endregion
 //#region src/runtime/cancellation.ts
+/**
+* Classify an abort signal's reason into the BUDGET-01 / BUDGET-02
+* `detail.reason` discriminator.
+*
+* - `"timeout"` when the reason is a {@link DogpileError} with `code === "timeout"`
+*   (matches the parent-deadline abort path in `engine.ts:createTimeoutAbortLifecycle`).
+* - `"parent-aborted"` for every other reason — explicit caller abort, plain
+*   `Error`, `undefined`, or arbitrary primitive.
+*/
+function classifyAbortReason(signalReasonOrError) {
+	if (DogpileError.isInstance(signalReasonOrError) && signalReasonOrError.code === "timeout") return "timeout";
+	return "parent-aborted";
+}
+function classifyChildTimeoutSource(_error, context) {
+	if (context.isProviderError) return "provider";
+	if (context.decisionTimeoutMs !== void 0 || context.engineDefaultTimeoutMs !== void 0) return "engine";
+	return "provider";
+}
 function throwIfAborted(signal, providerId) {
 	if (!signal?.aborted) return;
 	throw createAbortErrorFromSignal(signal, providerId);
@@ -468,7 +782,7 @@ function createAbortError(providerId, detail, cause) {
 }
 function createAbortErrorFromSignal(signal, providerId) {
 	if (DogpileError.isInstance(signal.reason)) return signal.reason;
-	return createAbortError(providerId, void 0, signal.reason);
+	return createAbortError(providerId, { reason: classifyAbortReason(signal.reason) }, signal.reason);
 }
 function createTimeoutError(providerId, timeoutMs) {
 	return new DogpileError({
@@ -479,23 +793,223 @@ function createTimeoutError(providerId, timeoutMs) {
 		detail: { timeoutMs }
 	});
 }
+function createEngineDeadlineTimeoutError(providerId, timeoutMs) {
+	return new DogpileError({
+		code: "provider-timeout",
+		message: `The child engine deadline expired after ${timeoutMs}ms.`,
+		retryable: true,
+		providerId,
+		detail: {
+			timeoutMs,
+			source: "engine"
+		}
+	});
+}
 //#endregion
 //#region src/runtime/decisions.ts
-function parseAgentDecision(output) {
+var PROTOCOL_NAMES = [
+	"coordinator",
+	"sequential",
+	"broadcast",
+	"shared"
+];
+function parseAgentDecision(output, context = {}) {
+	const delegateBlock = matchDelegateBlock(output);
+	if (delegateBlock !== void 0) return parseDelegateDecision(delegateBlock, context);
+	return parseParticipateDecision(output);
+}
+function isParticipatingDecision(decision) {
+	if (decision === void 0 || isDelegateDecisionArray(decision) || decision.type !== "participate") return false;
+	return decision.participation !== "abstain";
+}
+function isDelegateDecisionArray(decision) {
+	return Array.isArray(decision);
+}
+function parseParticipateDecision(output) {
 	const selectedRole = matchLine(output, /^role_selected:\s*(.+)$/imu);
 	const participation = matchLine(output, /^participation:\s*(contribute|abstain)$/imu);
 	const rationale = matchLine(output, /^rationale:\s*(.+)$/imu);
 	const contribution = matchContribution(output);
 	if (!selectedRole || !participation || !isAgentParticipation(participation) || !rationale || !contribution) return;
 	return {
+		type: "participate",
 		selectedRole,
 		participation,
 		rationale,
 		contribution
 	};
 }
-function isParticipatingDecision(decision) {
-	return decision?.participation !== "abstain";
+/**
+* Locate a `delegate:` line followed by a fenced JSON block in the agent's
+* output. Returns the raw JSON text inside the fence, or `undefined` when no
+* delegate block is present. Tolerates ```` ```json ```` and bare ```` ``` ````.
+*/
+function matchDelegateBlock(output) {
+	return output.match(/^delegate:\s*\r?\n\s*```(?:json)?\s*\r?\n([\s\S]*?)\r?\n\s*```/imu)?.[1];
+}
+function parseDelegateDecision(jsonText, context) {
+	let parsed;
+	try {
+		parsed = JSON.parse(jsonText);
+	} catch (error) {
+		throwInvalidDelegate({
+			path: "decision",
+			message: `delegate JSON did not parse: ${error instanceof Error ? error.message : String(error)}`,
+			expected: "valid JSON object",
+			received: truncate(jsonText)
+		});
+	}
+	if (Array.isArray(parsed)) {
+		if (parsed.length === 0) throwInvalidDelegate({
+			path: "decision",
+			message: "delegate array must not be empty.",
+			expected: "array with 1..8 delegate objects",
+			received: "empty array"
+		});
+		return parsed.map((item) => parseSingleDelegateObject(item, context));
+	}
+	return parseSingleDelegateObject(parsed, context);
+}
+function parseSingleDelegateObject(parsed, context) {
+	if (parsed === null || typeof parsed !== "object") throwInvalidDelegate({
+		path: "decision",
+		message: "delegate decision must be a JSON object.",
+		expected: "object",
+		received: describe(parsed)
+	});
+	const record = parsed;
+	const protocol = record["protocol"];
+	if (typeof protocol !== "string" || !PROTOCOL_NAMES.includes(protocol)) throwInvalidDelegate({
+		path: "decision.protocol",
+		message: `protocol "${describe(protocol)}" is not a known coordination protocol.`,
+		expected: PROTOCOL_NAMES.join(" | "),
+		received: describe(protocol)
+	});
+	const intentRaw = record["intent"];
+	const intent = typeof intentRaw === "string" ? intentRaw.trim() : "";
+	if (intent.length === 0) throwInvalidDelegate({
+		path: "decision.intent",
+		message: "delegate decision must include a non-empty intent string.",
+		expected: "non-empty string",
+		received: describe(intentRaw)
+	});
+	const result = {
+		type: "delegate",
+		protocol,
+		intent
+	};
+	if (record["model"] !== void 0) {
+		const model = record["model"];
+		if (typeof model !== "string" || model.length === 0) throwInvalidDelegate({
+			path: "decision.model",
+			message: "delegate decision model must be a non-empty string when present.",
+			expected: "non-empty string",
+			received: describe(model)
+		});
+		if (context.parentProviderId !== void 0 && model !== context.parentProviderId) throwInvalidDelegate({
+			path: "decision.model",
+			message: `delegate decision model "${model}" does not match parent provider id "${context.parentProviderId}".`,
+			expected: context.parentProviderId,
+			received: model
+		});
+		result.model = model;
+	}
+	if (record["budget"] !== void 0) result.budget = parseDelegateBudget(record["budget"]);
+	if (record["maxConcurrentChildren"] !== void 0) {
+		const value = record["maxConcurrentChildren"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throwInvalidDelegate({
+			path: "decision.maxConcurrentChildren",
+			message: "delegate decision maxConcurrentChildren must be a positive integer when present.",
+			expected: "integer >= 1",
+			received: describe(value)
+		});
+		result.maxConcurrentChildren = value;
+	}
+	if (context.currentDepth !== void 0 && context.maxDepth !== void 0) {
+		if (context.currentDepth + 1 > context.maxDepth) throw depthOverflowError(context.currentDepth, context.maxDepth);
+	}
+	return result;
+}
+/**
+* Build the canonical depth-overflow `DogpileError`. Used by the parser (this
+* file) and the coordinator dispatcher; kept here so both call sites produce
+* the exact same error shape (D-14, D-15).
+*/
+function depthOverflowError(currentDepth, maxDepth) {
+	return new DogpileError({
+		code: "invalid-configuration",
+		message: `Depth overflow: cannot dispatch sub-run at depth ${currentDepth + 1} (maxDepth = ${maxDepth}).`,
+		retryable: false,
+		detail: {
+			kind: "delegate-validation",
+			path: "decision.protocol",
+			reason: "depth-overflow",
+			currentDepth,
+			maxDepth
+		}
+	});
+}
+/**
+* Dispatcher-time depth gate. Throws the same error shape the parser uses; the
+* dual gate (parser + dispatcher) defends against any TOCTOU window between
+* decision parsing and child-run spin-up (D-14).
+*/
+function assertDepthWithinLimit(currentDepth, maxDepth) {
+	if (currentDepth + 1 > maxDepth) throw depthOverflowError(currentDepth, maxDepth);
+}
+function parseDelegateBudget(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throwInvalidDelegate({
+		path: "decision.budget",
+		message: "delegate decision budget must be an object.",
+		expected: "object",
+		received: describe(raw)
+	});
+	const record = raw;
+	const budget = {};
+	if (record["timeoutMs"] !== void 0) {
+		const value = record["timeoutMs"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throwInvalidDelegate({
+			path: "decision.budget.timeoutMs",
+			message: "delegate decision budget.timeoutMs must be a non-negative integer.",
+			expected: "integer >= 0",
+			received: describe(value)
+		});
+		budget.timeoutMs = value;
+	}
+	if (record["maxTokens"] !== void 0) {
+		const value = record["maxTokens"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throwInvalidDelegate({
+			path: "decision.budget.maxTokens",
+			message: "delegate decision budget.maxTokens must be a non-negative integer.",
+			expected: "integer >= 0",
+			received: describe(value)
+		});
+		budget.maxTokens = value;
+	}
+	if (record["maxIterations"] !== void 0) {
+		const value = record["maxIterations"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throwInvalidDelegate({
+			path: "decision.budget.maxIterations",
+			message: "delegate decision budget.maxIterations must be a non-negative integer.",
+			expected: "integer >= 0",
+			received: describe(value)
+		});
+		budget.maxIterations = value;
+	}
+	return budget;
+}
+function throwInvalidDelegate(failure) {
+	throw new DogpileError({
+		code: "invalid-configuration",
+		message: `Invalid Dogpile configuration at ${failure.path}: ${failure.message}`,
+		retryable: false,
+		detail: {
+			kind: "delegate-validation",
+			path: failure.path,
+			expected: failure.expected,
+			received: failure.received
+		}
+	});
 }
 function matchLine(output, pattern) {
 	return output.match(pattern)?.[1]?.trim();
@@ -507,6 +1021,15 @@ function matchContribution(output) {
 function isAgentParticipation(value) {
 	return value === "contribute" || value === "abstain";
 }
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	if (typeof value === "string") return JSON.stringify(value).slice(0, 200);
+	return typeof value;
+}
+function truncate(value) {
+	return value.length > 200 ? `${value.slice(0, 200)}…` : value;
+}
 //#endregion
 //#region src/runtime/model.ts
 async function generateModelTurn(options) {
@@ -964,6 +1487,7 @@ var budgetTiers = [
 	"balanced",
 	"quality"
 ];
+var onChildFailureModes = ["continue", "abort"];
 /**
 * Validate high-level caller options before any protocol execution starts.
 */
@@ -982,11 +1506,25 @@ function validateDogpileOptions(options) {
 	validateOptionalFunction(options.evaluate, "evaluate");
 	validateOptionalSeed(options.seed, "seed");
 	validateOptionalAbortSignal(options.signal, "signal");
+	validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
+	validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+	validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
+	validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }
 function validateMissionIntent(intent, path = "intent") {
 	validateNonEmptyString(intent, path, "intent is required.");
 }
 /**
+* Validate per-call run/stream options (`Engine.run(intent, options)` / `Engine.stream(...)`).
+*/
+function validateRunCallOptions(options, path = "options") {
+	if (options === void 0) return;
+	const record = requireRecord(options, path);
+	validateOptionalNonNegativeInteger(record.maxDepth, `${path}.maxDepth`);
+	validateOptionalPositiveInteger(record.maxConcurrentChildren, `${path}.maxConcurrentChildren`);
+	validateOptionalOnChildFailure(record.onChildFailure, `${path}.onChildFailure`);
+}
+/**
 * Validate low-level engine configuration before normalizing reusable controls.
 */
 function validateEngineOptions(options) {
@@ -1003,6 +1541,10 @@ function validateEngineOptions(options) {
 	validateOptionalFunction(options.evaluate, "evaluate");
 	validateOptionalSeed(options.seed, "seed");
 	validateOptionalAbortSignal(options.signal, "signal");
+	validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
+	validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+	validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
+	validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }
 function validateProtocolSelection(value, path) {
 	if (typeof value === "string") {
@@ -1050,6 +1592,23 @@ function validateBudgetTier(value, path) {
 		actual: value
 	});
 }
+function validateOptionalOnChildFailure(value, path) {
+	if (value === void 0) return;
+	if (value === "continue" || value === "abort") return;
+	throw new DogpileError({
+		code: "invalid-configuration",
+		message: `Invalid onChildFailure: expected "continue" or "abort", got ${JSON.stringify(value)}`,
+		retryable: false,
+		detail: {
+			kind: "configuration-validation",
+			path,
+			rule: "enum",
+			expected: onChildFailureModes.join(" | "),
+			received: describeValue(value),
+			reason: "invalid-on-child-failure"
+		}
+	});
+}
 /**
 * Validate configured model provider definitions at registration boundaries.
 */
@@ -1059,6 +1618,21 @@ function validateModelProviderRegistration(value, path = "model") {
 	validateFunction(record.generate, `${path}.generate`);
 	validateOptionalFunction(record.stream, `${path}.stream`);
 }
+/**
+* Engine-time defense-in-depth check that a provider's optional
+* `metadata.locality` is one of the two valid values when present (Phase 3 D-03).
+* Catches user-implemented providers that bypass TypeScript checks.
+*/
+function validateProviderLocality(provider, pathPrefix = "model") {
+	const loc = provider.metadata?.locality;
+	if (loc !== void 0 && loc !== "local" && loc !== "remote") invalidConfiguration({
+		path: `${pathPrefix}.metadata.locality`,
+		rule: "enum",
+		message: `${pathPrefix}.metadata.locality must be "local" or "remote" when provided.`,
+		expected: "\"local\" | \"remote\"",
+		actual: loc
+	});
+}
 function validateOptionalAgents(value, path) {
 	if (value === void 0) return;
 	if (!Array.isArray(value)) invalidConfiguration({
@@ -1338,6 +1912,16 @@ function validateOptionalNonNegativeInteger(value, path) {
 		actual: value
 	});
 }
+function validateOptionalPositiveFiniteNumber(value, path) {
+	if (value === void 0) return;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) invalidConfiguration({
+		path,
+		rule: "positive-finite-number",
+		message: "value must be a positive finite number.",
+		expected: "finite number > 0",
+		actual: value
+	});
+}
 function validateOptionalNonNegativeNumber(value, path) {
 	if (value === void 0) return;
 	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) invalidConfiguration({
@@ -1402,7 +1986,7 @@ function describeValue(value) {
 	return typeof value;
 }
 //#endregion
-//#region src/runtime/tools.ts
+//#region src/runtime/tools/built-in.ts
 var webSearchIdentity = {
 	id: "dogpile.tools.webSearch",
 	namespace: "dogpile",
@@ -1488,9 +2072,6 @@ function builtInDogpileToolIdentity(name) {
 function builtInDogpileToolInputSchema(name) {
 	return name === "webSearch" ? webSearchInputSchema : codeExecInputSchema;
 }
-/**
-* Return the default permission declarations for one built-in tool name.
-*/
 function builtInDogpileToolPermissions(name) {
 	return name === "webSearch" ? webSearchPermissions : codeExecPermissions;
 }
@@ -1501,276 +2082,28 @@ function validateBuiltInDogpileToolInput(name, input) {
 		issues
 	};
 }
-/**
-* Create the shared runtime tool executor used by every first-party protocol.
-*
-* @remarks
-* The executor owns call id generation, read-only trace context construction,
-* adapter validation, error normalization, and matched `tool-call` /
-* `tool-result` events. Protocols only supply a normalized
-* {@link RuntimeToolExecutionRequest}, which keeps tool execution independent
-* of Coordinator, Sequential, Broadcast, or Shared control flow.
-*/
-function createRuntimeToolExecutor(options) {
-	validateRuntimeToolRegistrations(options.tools);
-	const tools = Array.from(options.tools);
-	let callCount = 0;
-	return {
-		tools,
-		async execute(request) {
-			const tool = tools.find((candidate) => candidate.identity.id === request.toolId);
-			const identity = tool?.identity ?? {
-				id: request.toolId,
-				name: request.toolId
-			};
-			const callIndex = callCount;
-			callCount += 1;
-			const toolCallId = request.toolCallId ?? options.makeToolCallId?.(identity, callIndex) ?? defaultToolCallId(options.runId, callIndex);
-			const context = createExecutionContext(options, request, toolCallId);
-			options.emit?.({
-				type: "tool-call",
-				runId: options.runId,
-				at: (/* @__PURE__ */ new Date()).toISOString(),
-				toolCallId,
-				tool: identity,
-				input: request.input,
-				...request.agentId ? { agentId: request.agentId } : {},
-				...request.role ? { role: request.role } : {}
-			});
-			const result = await executeRuntimeTool(tool, identity, request.input, context);
-			options.emit?.({
-				type: "tool-result",
-				runId: options.runId,
-				at: (/* @__PURE__ */ new Date()).toISOString(),
-				toolCallId,
+function createWebSearchToolAdapter(options) {
+	const identity = mergeIdentity(webSearchIdentity, options.identity);
+	return normalizeBuiltInDogpileTool({
+		name: "webSearch",
+		...options.identity ? { identity: options.identity } : {},
+		...options.permissions ? { permissions: options.permissions } : {},
+		async execute(input, context) {
+			const fetchImplementation = options.fetch ?? globalThis.fetch;
+			if (!fetchImplementation) return {
+				type: "error",
+				toolCallId: context.toolCallId,
 				tool: identity,
-				result,
-				...request.agentId ? { agentId: request.agentId } : {},
-				...request.role ? { role: request.role } : {}
-			});
-			return result;
-		}
-	};
-}
-/**
-* Return a JSON-serializable manifest for tools visible to a protocol run.
-*/
-function runtimeToolManifest(tools) {
-	return tools.map((tool) => {
-		const inputSchema = {
-			kind: tool.inputSchema.kind,
-			schema: tool.inputSchema.schema,
-			...tool.inputSchema.description ? { description: tool.inputSchema.description } : {}
-		};
-		return {
-			identity: runtimeToolIdentityManifest(tool.identity),
-			inputSchema,
-			permissions: Array.from(tool.permissions ?? []).map(runtimeToolPermissionManifest)
-		};
-	});
-}
-/**
-* Return request metadata that makes runtime tools visible to provider
-* adapters, or an empty object when no tools are available.
-*/
-function runtimeToolAvailability(tools) {
-	const manifest = runtimeToolManifest(tools);
-	return manifest.length > 0 ? { tools: manifest } : {};
-}
-/**
-* Execute normalized tool requests returned by a provider response.
-*/
-async function executeModelResponseToolRequests(options) {
-	const toolCalls = [];
-	for (const request of options.response.toolRequests ?? []) {
-		const result = await options.executor.execute({
-			...request,
-			agentId: request.agentId ?? options.agentId,
-			role: request.role ?? options.role,
-			turn: request.turn ?? options.turn,
-			metadata: mergeToolMetadata(options.metadata, request.metadata)
-		});
-		toolCalls.push({
-			toolCallId: result.toolCallId,
-			tool: result.tool,
-			input: request.input,
-			result
-		});
-	}
-	return toolCalls;
-}
-function runtimeToolIdentityManifest(identity) {
-	return {
-		id: identity.id,
-		name: identity.name,
-		...identity.namespace ? { namespace: identity.namespace } : {},
-		...identity.version ? { version: identity.version } : {},
-		...identity.description ? { description: identity.description } : {}
-	};
-}
-function runtimeToolPermissionManifest(permission) {
-	if (permission.kind === "network") return {
-		kind: permission.kind,
-		...permission.allowHosts ? { allowHosts: Array.from(permission.allowHosts) } : {},
-		...permission.allowPrivateNetwork === void 0 ? {} : { allowPrivateNetwork: permission.allowPrivateNetwork }
-	};
-	if (permission.kind === "code-execution") return {
-		kind: permission.kind,
-		sandbox: permission.sandbox,
-		...permission.languages ? { languages: Array.from(permission.languages) } : {},
-		...permission.allowNetwork === void 0 ? {} : { allowNetwork: permission.allowNetwork }
-	};
-	return {
-		kind: permission.kind,
-		name: permission.name,
-		...permission.description ? { description: permission.description } : {},
-		...permission.metadata ? { metadata: permission.metadata } : {}
-	};
-}
-function validateCodeExecAdapterInput(input, options) {
-	const issues = [...validateCodeExecInput(input)];
-	const languages = options.languages ?? codeExecLanguages;
-	if (typeof input.language === "string" && isCodeExecLanguage(input.language) && !languages.includes(input.language)) issues.push({
-		code: "invalid-value",
-		path: "language",
-		message: "codeExec.language is not enabled for this adapter.",
-		detail: { allowed: Array.from(languages) }
-	});
-	const effectiveTimeoutMs = input.timeoutMs ?? options.defaultTimeoutMs;
-	if (effectiveTimeoutMs !== void 0 && options.maxTimeoutMs !== void 0 && Number.isFinite(effectiveTimeoutMs) && Number.isFinite(options.maxTimeoutMs) && effectiveTimeoutMs > options.maxTimeoutMs) issues.push({
-		code: "out-of-range",
-		path: input.timeoutMs === void 0 ? "defaultTimeoutMs" : "timeoutMs",
-		message: `codeExec.timeoutMs must be less than or equal to ${options.maxTimeoutMs}.`,
-		detail: { maximum: options.maxTimeoutMs }
-	});
-	return issues.length === 0 ? { type: "valid" } : {
-		type: "invalid",
-		issues
-	};
-}
-function createExecutionContext(options, request, toolCallId) {
-	return {
-		runId: options.runId,
-		toolCallId,
-		protocol: options.protocol,
-		tier: options.tier,
-		...request.agentId ? { agentId: request.agentId } : {},
-		...request.role ? { role: request.role } : {},
-		...request.turn !== void 0 ? { turn: request.turn } : {},
-		...options.getTrace ? { trace: options.getTrace() } : {},
-		...request.abortSignal ?? options.abortSignal ? { abortSignal: request.abortSignal ?? options.abortSignal } : {},
-		...options.metadata || request.metadata ? { metadata: mergeToolMetadata(options.metadata, request.metadata) } : {}
-	};
-}
-async function executeRuntimeTool(tool, identity, input, context) {
-	if (!tool) return {
-		type: "error",
-		toolCallId: context.toolCallId,
-		tool: identity,
-		error: {
-			code: "unavailable",
-			message: `Runtime tool "${identity.id}" is not registered.`,
-			retryable: false
-		}
-	};
-	const validation = validateRuntimeToolInput(tool, input);
-	if (validation.type === "invalid") return {
-		type: "error",
-		toolCallId: context.toolCallId,
-		tool: identity,
-		error: {
-			code: "invalid-input",
-			message: "Runtime tool input failed validation.",
-			retryable: false,
-			detail: { issues: validation.issues.map((issue) => ({
-				code: issue.code,
-				path: issue.path,
-				message: issue.message,
-				...issue.detail ? { detail: issue.detail } : {}
-			})) }
-		}
-	};
-	try {
-		return await tool.execute(input, context);
-	} catch (error) {
-		return {
-			type: "error",
-			toolCallId: context.toolCallId,
-			tool: identity,
-			error: normalizeRuntimeToolAdapterError(error)
-		};
-	}
-}
-function validateRuntimeToolInput(tool, input) {
-	if (typeof tool.validateInput !== "function") return { type: "valid" };
-	return tool.validateInput(input);
-}
-function mergeToolMetadata(base, request) {
-	return {
-		...base ?? {},
-		...request ?? {}
-	};
-}
-function defaultToolCallId(runId, callIndex) {
-	return `${runId}:tool-${callIndex + 1}`;
-}
-/**
-* Convert an unknown adapter failure into Dogpile's serializable error data.
-*/
-function normalizeRuntimeToolAdapterError(error) {
-	if (isRuntimeToolAdapterError(error)) return error;
-	if (error instanceof DOMException && error.name === "AbortError") return {
-		code: "aborted",
-		message: error.message || "Tool execution was aborted.",
-		retryable: true,
-		detail: { name: error.name }
-	};
-	if (error instanceof Error) return {
-		code: "backend-error",
-		message: error.message,
-		retryable: false,
-		detail: { name: error.name }
-	};
-	return {
-		code: "unknown",
-		message: "Tool execution failed with a non-Error value.",
-		retryable: false,
-		detail: { valueType: typeof error }
-	};
-}
-/**
-* Create Dogpile's built-in fetch-based web search adapter.
-*
-* @remarks
-* The adapter is backend-neutral: by default it sends a GET request with
-* `q` and `limit` query parameters, then accepts either `{ results: [...] }`
-* or a bare array of result objects from the response JSON. Callers can replace
-* request construction or response parsing for a specific search API while
-* keeping Dogpile's shared runtime tool contract, identity, permissions, input
-* validation, and serializable errors.
-*/
-function createWebSearchToolAdapter(options) {
-	const identity = mergeIdentity(webSearchIdentity, options.identity);
-	return normalizeBuiltInDogpileTool({
-		name: "webSearch",
-		...options.identity ? { identity: options.identity } : {},
-		...options.permissions ? { permissions: options.permissions } : {},
-		async execute(input, context) {
-			const fetchImplementation = options.fetch ?? globalThis.fetch;
-			if (!fetchImplementation) return {
-				type: "error",
-				toolCallId: context.toolCallId,
-				tool: identity,
-				error: {
-					code: "unavailable",
-					message: "No fetch implementation is available for webSearch.",
-					retryable: false
-				}
-			};
-			const request = options.buildRequest ? options.buildRequest(input, context) : defaultWebSearchRequest(options, input, context);
-			const response = await fetchImplementation(request.url, {
-				...request.init,
-				...context.abortSignal ? { signal: context.abortSignal } : {}
+				error: {
+					code: "unavailable",
+					message: "No fetch implementation is available for webSearch.",
+					retryable: false
+				}
+			};
+			const request = options.buildRequest ? options.buildRequest(input, context) : defaultWebSearchRequest(options, input, context);
+			const response = await fetchImplementation(request.url, {
+				...request.init,
+				...context.abortSignal ? { signal: context.abortSignal } : {}
 			});
 			if (!response.ok) throw {
 				code: response.status >= 500 ? "unavailable" : "backend-error",
@@ -1791,15 +2124,6 @@ function createWebSearchToolAdapter(options) {
 		}
 	});
 }
-/**
-* Create Dogpile's built-in code execution adapter around a caller-owned sandbox.
-*
-* @remarks
-* Dogpile core stays runtime-portable and never evaluates code itself. This
-* adapter supplies the stable `codeExec` identity, schema, permissions,
-* validation, timeout defaults, abort handling, and serializable errors while
-* the host application owns the sandbox boundary.
-*/
 function createCodeExecToolAdapter(options) {
 	const identity = mergeIdentity(codeExecIdentity, options.identity);
 	const permissions = options.permissions ?? codeExecPermissionsFor(options.languages ?? codeExecLanguages, options.allowNetwork ?? false);
@@ -1818,7 +2142,7 @@ function createCodeExecToolAdapter(options) {
 					code: "invalid-input",
 					message: "Invalid codeExec tool input.",
 					retryable: false,
-					detail: { issues: validation.issues }
+					detail: { issues: serializeValidationIssues(validation.issues) }
 				}
 			};
 			const timeoutMs = input.timeoutMs ?? options.defaultTimeoutMs;
@@ -1871,9 +2195,6 @@ function normalizeBuiltInDogpileTool(definition) {
 		}
 	}
 }
-/**
-* Normalize configured built-in Dogpile tool executors into runtime tools.
-*/
 function normalizeBuiltInDogpileTools(tools) {
 	const normalized = [];
 	if (tools.webSearch) normalized.push(normalizeBuiltInDogpileTool(asWebSearchDefinition(tools.webSearch)));
@@ -1890,7 +2211,7 @@ async function executeBuiltInTool(identity, execute, input, context, name) {
 			code: "invalid-input",
 			message: `Invalid ${name} tool input.`,
 			retryable: false,
-			detail: { issues: validation.issues }
+			detail: { issues: serializeValidationIssues(validation.issues) }
 		}
 	};
 	try {
@@ -1925,6 +2246,27 @@ function mergeIdentity(defaultIdentity, options) {
 		...options.description !== void 0 ? { description: options.description } : {}
 	};
 }
+function validateCodeExecAdapterInput(input, options) {
+	const issues = [...validateCodeExecInput(input)];
+	const languages = options.languages ?? codeExecLanguages;
+	if (typeof input.language === "string" && isCodeExecLanguage(input.language) && !languages.includes(input.language)) issues.push({
+		code: "invalid-value",
+		path: "language",
+		message: "codeExec.language is not enabled for this adapter.",
+		detail: { allowed: Array.from(languages) }
+	});
+	const effectiveTimeoutMs = input.timeoutMs ?? options.defaultTimeoutMs;
+	if (effectiveTimeoutMs !== void 0 && options.maxTimeoutMs !== void 0 && Number.isFinite(effectiveTimeoutMs) && Number.isFinite(options.maxTimeoutMs) && effectiveTimeoutMs > options.maxTimeoutMs) issues.push({
+		code: "out-of-range",
+		path: input.timeoutMs === void 0 ? "defaultTimeoutMs" : "timeoutMs",
+		message: `codeExec.timeoutMs must be less than or equal to ${options.maxTimeoutMs}.`,
+		detail: { maximum: options.maxTimeoutMs }
+	});
+	return issues.length === 0 ? { type: "valid" } : {
+		type: "invalid",
+		issues
+	};
+}
 function defaultWebSearchRequest(options, input, _context) {
 	const url = new URL(String(options.endpoint));
 	url.searchParams.set("q", input.query);
@@ -2024,122 +2366,341 @@ function normalizeWebSearchResult(value) {
 		message: "Web search result must be a JSON object.",
 		retryable: false
 	};
-	const title = jsonString(value.title, "title");
-	const url = jsonString(value.url, "url");
-	const snippet = optionalJsonString(value.snippet, "snippet");
-	const metadata = optionalJsonObject(value.metadata, "metadata");
+	const title = jsonString(value.title, "title");
+	const url = jsonString(value.url, "url");
+	const snippet = optionalJsonString(value.snippet, "snippet");
+	const metadata = optionalJsonObject(value.metadata, "metadata");
+	return {
+		title,
+		url,
+		...snippet !== void 0 ? { snippet } : {},
+		...metadata !== void 0 ? { metadata } : {}
+	};
+}
+function jsonString(value, fieldName) {
+	if (typeof value !== "string" || value.trim().length === 0) throw {
+		code: "backend-error",
+		message: `Web search result ${fieldName} must be a non-empty string.`,
+		retryable: false
+	};
+	return value;
+}
+function optionalJsonString(value, fieldName) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "string") throw {
+		code: "backend-error",
+		message: `Web search result ${fieldName} must be a string when present.`,
+		retryable: false
+	};
+	return value;
+}
+function optionalJsonObject(value, fieldName) {
+	if (value === void 0) return void 0;
+	if (!isJsonObject(value)) throw {
+		code: "backend-error",
+		message: `Web search result ${fieldName} must be a JSON object when present.`,
+		retryable: false
+	};
+	return value;
+}
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateWebSearchInput(input) {
+	const issues = [];
+	if (typeof input.query !== "string") issues.push({
+		code: input.query === void 0 ? "missing-field" : "invalid-type",
+		path: "query",
+		message: "webSearch.query must be a string."
+	});
+	else if (input.query.trim().length === 0) issues.push({
+		code: "invalid-value",
+		path: "query",
+		message: "webSearch.query must not be empty."
+	});
+	if (input.maxResults !== void 0) {
+		if (typeof input.maxResults !== "number" || !Number.isFinite(input.maxResults)) issues.push({
+			code: "invalid-type",
+			path: "maxResults",
+			message: "webSearch.maxResults must be a finite number."
+		});
+		else if (input.maxResults < 1) issues.push({
+			code: "out-of-range",
+			path: "maxResults",
+			message: "webSearch.maxResults must be greater than or equal to 1.",
+			detail: { minimum: 1 }
+		});
+	}
+	return issues;
+}
+function validateCodeExecInput(input) {
+	const issues = [];
+	if (typeof input.language !== "string") issues.push({
+		code: input.language === void 0 ? "missing-field" : "invalid-type",
+		path: "language",
+		message: "codeExec.language must be a string."
+	});
+	else if (!isCodeExecLanguage(input.language)) issues.push({
+		code: "invalid-value",
+		path: "language",
+		message: "codeExec.language must be one of javascript, typescript, python, bash, or shell.",
+		detail: { allowed: [
+			"javascript",
+			"typescript",
+			"python",
+			"bash",
+			"shell"
+		] }
+	});
+	if (typeof input.code !== "string") issues.push({
+		code: input.code === void 0 ? "missing-field" : "invalid-type",
+		path: "code",
+		message: "codeExec.code must be a string."
+	});
+	if (input.timeoutMs !== void 0) {
+		if (typeof input.timeoutMs !== "number" || !Number.isFinite(input.timeoutMs)) issues.push({
+			code: "invalid-type",
+			path: "timeoutMs",
+			message: "codeExec.timeoutMs must be a finite number."
+		});
+		else if (input.timeoutMs < 1) issues.push({
+			code: "out-of-range",
+			path: "timeoutMs",
+			message: "codeExec.timeoutMs must be greater than or equal to 1.",
+			detail: { minimum: 1 }
+		});
+	}
+	return issues;
+}
+function isCodeExecLanguage(value) {
+	return value === "javascript" || value === "typescript" || value === "python" || value === "bash" || value === "shell";
+}
+function normalizeRuntimeToolAdapterError(error) {
+	if (isRuntimeToolAdapterError(error)) return error;
+	if (error instanceof DOMException && error.name === "AbortError") return {
+		code: "aborted",
+		message: error.message || "Tool execution was aborted.",
+		retryable: true,
+		detail: { name: error.name }
+	};
+	if (error instanceof Error) return {
+		code: "backend-error",
+		message: error.message,
+		retryable: false,
+		detail: { name: error.name }
+	};
+	return {
+		code: "unknown",
+		message: "Tool execution failed with a non-Error value.",
+		retryable: false,
+		detail: { valueType: typeof error }
+	};
+}
+function isRuntimeToolAdapterError(error) {
+	if (typeof error !== "object" || error === null || !("code" in error) || !("message" in error)) return false;
+	const candidate = error;
+	return isRuntimeToolAdapterErrorCode(candidate.code) && typeof candidate.message === "string";
+}
+function isRuntimeToolAdapterErrorCode(value) {
+	return value === "invalid-input" || value === "permission-denied" || value === "timeout" || value === "aborted" || value === "unavailable" || value === "backend-error" || value === "unknown";
+}
+function serializeValidationIssues(issues) {
+	return issues.map((issue) => ({
+		code: issue.code,
+		path: issue.path,
+		message: issue.message,
+		...issue.detail !== void 0 ? { detail: issue.detail } : {}
+	}));
+}
+//#endregion
+//#region src/runtime/tools.ts
+/**
+* Create the shared runtime tool executor used by every first-party protocol.
+*
+* @remarks
+* The executor owns call id generation, read-only trace context construction,
+* adapter validation, error normalization, and matched `tool-call` /
+* `tool-result` events. Protocols only supply a normalized
+* {@link RuntimeToolExecutionRequest}, which keeps tool execution independent
+* of Coordinator, Sequential, Broadcast, or Shared control flow.
+*/
+function createRuntimeToolExecutor(options) {
+	validateRuntimeToolRegistrations(options.tools);
+	const tools = Array.from(options.tools);
+	let callCount = 0;
+	return {
+		tools,
+		async execute(request) {
+			const tool = tools.find((candidate) => candidate.identity.id === request.toolId);
+			const identity = tool?.identity ?? {
+				id: request.toolId,
+				name: request.toolId
+			};
+			const callIndex = callCount;
+			callCount += 1;
+			const toolCallId = request.toolCallId ?? options.makeToolCallId?.(identity, callIndex) ?? defaultToolCallId(options.runId, callIndex);
+			const context = createExecutionContext(options, request, toolCallId);
+			options.emit?.({
+				type: "tool-call",
+				runId: options.runId,
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				toolCallId,
+				tool: identity,
+				input: request.input,
+				...request.agentId ? { agentId: request.agentId } : {},
+				...request.role ? { role: request.role } : {}
+			});
+			const result = await executeRuntimeTool(tool, identity, request.input, context);
+			options.emit?.({
+				type: "tool-result",
+				runId: options.runId,
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				toolCallId,
+				tool: identity,
+				result,
+				...request.agentId ? { agentId: request.agentId } : {},
+				...request.role ? { role: request.role } : {}
+			});
+			return result;
+		}
+	};
+}
+/**
+* Return a JSON-serializable manifest for tools visible to a protocol run.
+*/
+function runtimeToolManifest(tools) {
+	return tools.map((tool) => {
+		const inputSchema = {
+			kind: tool.inputSchema.kind,
+			schema: tool.inputSchema.schema,
+			...tool.inputSchema.description ? { description: tool.inputSchema.description } : {}
+		};
+		return {
+			identity: runtimeToolIdentityManifest(tool.identity),
+			inputSchema,
+			permissions: Array.from(tool.permissions ?? []).map(runtimeToolPermissionManifest)
+		};
+	});
+}
+/**
+* Return request metadata that makes runtime tools visible to provider
+* adapters, or an empty object when no tools are available.
+*/
+function runtimeToolAvailability(tools) {
+	const manifest = runtimeToolManifest(tools);
+	return manifest.length > 0 ? { tools: manifest } : {};
+}
+/**
+* Execute normalized tool requests returned by a provider response.
+*/
+async function executeModelResponseToolRequests(options) {
+	const toolCalls = [];
+	for (const request of options.response.toolRequests ?? []) {
+		const result = await options.executor.execute({
+			...request,
+			agentId: request.agentId ?? options.agentId,
+			role: request.role ?? options.role,
+			turn: request.turn ?? options.turn,
+			metadata: mergeToolMetadata(options.metadata, request.metadata)
+		});
+		toolCalls.push({
+			toolCallId: result.toolCallId,
+			tool: result.tool,
+			input: request.input,
+			result
+		});
+	}
+	return toolCalls;
+}
+function runtimeToolIdentityManifest(identity) {
+	return {
+		id: identity.id,
+		name: identity.name,
+		...identity.namespace ? { namespace: identity.namespace } : {},
+		...identity.version ? { version: identity.version } : {},
+		...identity.description ? { description: identity.description } : {}
+	};
+}
+function runtimeToolPermissionManifest(permission) {
+	if (permission.kind === "network") return {
+		kind: permission.kind,
+		...permission.allowHosts ? { allowHosts: Array.from(permission.allowHosts) } : {},
+		...permission.allowPrivateNetwork === void 0 ? {} : { allowPrivateNetwork: permission.allowPrivateNetwork }
+	};
+	if (permission.kind === "code-execution") return {
+		kind: permission.kind,
+		sandbox: permission.sandbox,
+		...permission.languages ? { languages: Array.from(permission.languages) } : {},
+		...permission.allowNetwork === void 0 ? {} : { allowNetwork: permission.allowNetwork }
+	};
 	return {
-		title,
-		url,
-		...snippet !== void 0 ? { snippet } : {},
-		...metadata !== void 0 ? { metadata } : {}
+		kind: permission.kind,
+		name: permission.name,
+		...permission.description ? { description: permission.description } : {},
+		...permission.metadata ? { metadata: permission.metadata } : {}
 	};
 }
-function jsonString(value, fieldName) {
-	if (typeof value !== "string" || value.trim().length === 0) throw {
-		code: "backend-error",
-		message: `Web search result ${fieldName} must be a non-empty string.`,
-		retryable: false
+function createExecutionContext(options, request, toolCallId) {
+	return {
+		runId: options.runId,
+		toolCallId,
+		protocol: options.protocol,
+		tier: options.tier,
+		...request.agentId ? { agentId: request.agentId } : {},
+		...request.role ? { role: request.role } : {},
+		...request.turn !== void 0 ? { turn: request.turn } : {},
+		...options.getTrace ? { trace: options.getTrace() } : {},
+		...request.abortSignal ?? options.abortSignal ? { abortSignal: request.abortSignal ?? options.abortSignal } : {},
+		...options.metadata || request.metadata ? { metadata: mergeToolMetadata(options.metadata, request.metadata) } : {}
 	};
-	return value;
 }
-function optionalJsonString(value, fieldName) {
-	if (value === void 0) return;
-	if (typeof value !== "string") throw {
-		code: "backend-error",
-		message: `Web search result ${fieldName} must be a string when present.`,
-		retryable: false
+async function executeRuntimeTool(tool, identity, input, context) {
+	if (!tool) return {
+		type: "error",
+		toolCallId: context.toolCallId,
+		tool: identity,
+		error: {
+			code: "unavailable",
+			message: `Runtime tool "${identity.id}" is not registered.`,
+			retryable: false
+		}
 	};
-	return value;
-}
-function optionalJsonObject(value, fieldName) {
-	if (value === void 0) return;
-	if (!isJsonObject(value)) throw {
-		code: "backend-error",
-		message: `Web search result ${fieldName} must be a JSON object when present.`,
-		retryable: false
+	const validation = tool.validateInput?.(input);
+	if (validation?.type === "invalid") return {
+		type: "error",
+		toolCallId: context.toolCallId,
+		tool: identity,
+		error: {
+			code: "invalid-input",
+			message: "Runtime tool input failed validation.",
+			retryable: false,
+			detail: { issues: validation.issues.map((issue) => ({
+				code: issue.code,
+				path: issue.path,
+				message: issue.message,
+				...issue.detail ? { detail: issue.detail } : {}
+			})) }
+		}
 	};
-	return value;
-}
-function isJsonObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function validateWebSearchInput(input) {
-	const issues = [];
-	if (typeof input.query !== "string") issues.push({
-		code: input.query === void 0 ? "missing-field" : "invalid-type",
-		path: "query",
-		message: "webSearch.query must be a string."
-	});
-	else if (input.query.trim().length === 0) issues.push({
-		code: "invalid-value",
-		path: "query",
-		message: "webSearch.query must not be empty."
-	});
-	if (input.maxResults !== void 0) {
-		if (typeof input.maxResults !== "number" || !Number.isFinite(input.maxResults)) issues.push({
-			code: "invalid-type",
-			path: "maxResults",
-			message: "webSearch.maxResults must be a finite number."
-		});
-		else if (input.maxResults < 1) issues.push({
-			code: "out-of-range",
-			path: "maxResults",
-			message: "webSearch.maxResults must be greater than or equal to 1.",
-			detail: { minimum: 1 }
-		});
-	}
-	return issues;
-}
-function validateCodeExecInput(input) {
-	const issues = [];
-	if (typeof input.language !== "string") issues.push({
-		code: input.language === void 0 ? "missing-field" : "invalid-type",
-		path: "language",
-		message: "codeExec.language must be a string."
-	});
-	else if (!isCodeExecLanguage(input.language)) issues.push({
-		code: "invalid-value",
-		path: "language",
-		message: "codeExec.language must be one of javascript, typescript, python, bash, or shell.",
-		detail: { allowed: [
-			"javascript",
-			"typescript",
-			"python",
-			"bash",
-			"shell"
-		] }
-	});
-	if (typeof input.code !== "string") issues.push({
-		code: input.code === void 0 ? "missing-field" : "invalid-type",
-		path: "code",
-		message: "codeExec.code must be a string."
-	});
-	if (input.timeoutMs !== void 0) {
-		if (typeof input.timeoutMs !== "number" || !Number.isFinite(input.timeoutMs)) issues.push({
-			code: "invalid-type",
-			path: "timeoutMs",
-			message: "codeExec.timeoutMs must be a finite number."
-		});
-		else if (input.timeoutMs < 1) issues.push({
-			code: "out-of-range",
-			path: "timeoutMs",
-			message: "codeExec.timeoutMs must be greater than or equal to 1.",
-			detail: { minimum: 1 }
-		});
+	try {
+		return await tool.execute(input, context);
+	} catch (error) {
+		return {
+			type: "error",
+			toolCallId: context.toolCallId,
+			tool: identity,
+			error: normalizeRuntimeToolAdapterError(error)
+		};
 	}
-	return issues;
-}
-function isCodeExecLanguage(value) {
-	return value === "javascript" || value === "typescript" || value === "python" || value === "bash" || value === "shell";
 }
-function isRuntimeToolAdapterError(error) {
-	if (typeof error !== "object" || error === null || !("code" in error) || !("message" in error)) return false;
-	const candidate = error;
-	return isRuntimeToolAdapterErrorCode(candidate.code) && typeof candidate.message === "string";
+function mergeToolMetadata(base, request) {
+	return {
+		...base ?? {},
+		...request ?? {}
+	};
 }
-function isRuntimeToolAdapterErrorCode(value) {
-	return value === "invalid-input" || value === "permission-denied" || value === "timeout" || value === "aborted" || value === "unavailable" || value === "backend-error" || value === "unknown";
+function defaultToolCallId(runId, callIndex) {
+	return `${runId}:tool-${callIndex + 1}`;
 }
 //#endregion
 //#region src/runtime/wrap-up.ts
@@ -2289,7 +2850,7 @@ function minCap(left, right) {
 //#endregion
 //#region src/runtime/broadcast.ts
 async function runBroadcast(options) {
-	const runId = createRunId$3();
+	const runId = createRunId();
 	const events = [];
 	const transcript = [];
 	const protocolDecisions = [];
@@ -2298,7 +2859,7 @@ async function runBroadcast(options) {
 	const maxRounds = options.protocol.maxRounds ?? 2;
 	let firstRoundContributions = [];
 	let lastContributions = [];
-	const startedAtMs = nowMs$3();
+	const startedAtMs = nowMs();
 	let stopped = false;
 	let termination;
 	const wrapUpHint = createWrapUpHintController({
@@ -2375,7 +2936,7 @@ async function runBroadcast(options) {
 					events,
 					transcript,
 					iteration: transcript.length,
-					elapsedMs: elapsedMs$3(startedAtMs)
+					elapsedMs: elapsedMs(startedAtMs)
 				})
 			};
 			const response = await generateModelTurn({
@@ -2385,7 +2946,7 @@ async function runBroadcast(options) {
 				agent,
 				input,
 				emit,
-				callId: providerCallIdFor$2(runId, providerCalls.length + agentIndex + 1),
+				callId: providerCallIdFor(runId, providerCalls.length + agentIndex + 1),
 				onProviderCall(call) {
 					providerCallSlots[agentIndex] = call;
 				}
@@ -2550,7 +3111,7 @@ async function runBroadcast(options) {
 			events,
 			transcript,
 			iteration: transcript.length,
-			elapsedMs: elapsedMs$3(startedAtMs)
+			elapsedMs: elapsedMs(startedAtMs)
 		}));
 		if (!stopRecord) return false;
 		stopped = true;
@@ -2566,7 +3127,7 @@ async function runBroadcast(options) {
 			reason: record.budgetReason ?? "cost",
 			cost: totalCost,
 			iteration: transcript.length,
-			elapsedMs: elapsedMs$3(startedAtMs),
+			elapsedMs: elapsedMs(startedAtMs),
 			detail: record.detail ?? {}
 		};
 		emit(event);
@@ -2596,33 +3157,76 @@ function responseCost$3(response) {
 		totalTokens: response.usage?.totalTokens ?? 0
 	};
 }
-function createRunId$3() {
-	return globalThis.crypto?.randomUUID?.() ?? `run-${Date.now().toString(36)}`;
-}
-function nowMs$3() {
-	return globalThis.performance?.now() ?? Date.now();
-}
-function elapsedMs$3(startedAtMs) {
-	return Math.max(0, nowMs$3() - startedAtMs);
-}
-function providerCallIdFor$2(runId, oneBasedIndex) {
-	return `${runId}:provider-call:${oneBasedIndex}`;
-}
 //#endregion
 //#region src/runtime/coordinator.ts
+/**
+* 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.
+*/
+var MAX_DISPATCH_PER_TURN = 8;
+var DEFAULT_MAX_CONCURRENT_CHILDREN$1 = 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 !== void 0) 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;
+	for (const agent of options.agents) {
+		const agentModel = agent.model;
+		if (agentModel?.metadata?.locality === "local") return agentModel;
+	}
+}
 async function runCoordinator(options) {
-	const runId = createRunId$2();
+	const runId = createRunId();
 	const events = [];
 	const transcript = [];
 	const protocolDecisions = [];
 	const providerCalls = [];
+	const dispatchedChildren = /* @__PURE__ */ new Map();
 	let totalCost = emptyCost();
+	let concurrencyClampEmitted = false;
 	const maxTurns = options.protocol.maxTurns ?? options.agents.length;
 	const activeAgents = options.agents.slice(0, maxTurns);
 	const coordinator = activeAgents[0];
-	const startedAtMs = nowMs$2();
+	const startedAtMs = nowMs();
 	let stopped = false;
 	let termination;
+	let triggeringFailureForAbortMode;
 	const wrapUpHint = createWrapUpHintController({
 		protocol: options.protocol,
 		tier: options.tier,
@@ -2638,6 +3242,51 @@ 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 !== void 0 ? { childTimeoutMs: child.childTimeoutMs } : {},
+				...options.seed !== void 0 ? { seed: options.seed } : {}
+			});
+			const failedEvent = {
+				type: "sub-run-failed",
+				runId,
+				at: (/* @__PURE__ */ 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",
@@ -2668,24 +3317,231 @@ 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
-			});
+			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 === void 0) 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$1, decisionMax);
+				const requestedMax = effectiveForTurn;
+				const localProvider = findFirstLocalProvider(options);
+				if (localProvider !== void 0) {
+					effectiveForTurn = 1;
+					if (!concurrencyClampEmitted) {
+						const clampEvent = {
+							type: "sub-run-concurrency-clamped",
+							runId,
+							at: (/* @__PURE__ */ 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 === void 0) throw new Error("missing child run id");
+					const dispatchedChild = {
+						childRunId,
+						decision: delegate,
+						parentDecisionId,
+						parentDecisionArrayIndex: index,
+						parentDepth,
+						controller: new AbortController(),
+						removeParentListener: void 0,
+						childEvents: [],
+						started: false,
+						closed: false,
+						startedAtMs: Date.now(),
+						childTimeoutMs: void 0,
+						failure: void 0
+					};
+					dispatchedChildren.set(childRunId, dispatchedChild);
+					return dispatchedChild;
+				});
+				const dispatchResults = [];
+				let firstFailureIndex;
+				const tasks = delegates.map(async (delegate, index) => {
+					const childRunId = childRunIds[index];
+					if (childRunId === void 0) throw new Error("missing child run id");
+					if (semaphore.inFlight >= effectiveForTurn) {
+						const queuedEvent = {
+							type: "sub-run-queued",
+							runId,
+							at: (/* @__PURE__ */ 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 !== void 0) {
+							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 !== void 0 ? { seed: options.seed } : {}
+							});
+							const failedEvent = {
+								type: "sub-run-failed",
+								runId,
+								at: (/* @__PURE__ */ 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 failure = dispatchedForTurn[index]?.failure;
+						if (delegates.length === 1 && (options.onChildFailure === "abort" || failure === void 0 || isDelegateValidationError(error))) throw error;
+						let taggedText = `[sub-run ${childRunId} failed]: ${error instanceof Error ? error.message : String(error)}`;
+						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 firstRejected = (await Promise.allSettled(tasks)).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 !== void 0);
+				if (options.onChildFailure === "abort" && currentWaveFailures.length > 0) {
+					triggeringFailureForAbortMode ??= currentWaveFailures[0];
+					break;
+				}
+				const failuresSection = buildFailuresSection(currentWaveFailures);
+				const coordinatorAgent = options.agents[0] ?? {
+					id: "coordinator",
+					role: "coordinator"
+				};
+				dispatchInput = [
+					buildCoordinatorPlanInput(options.intent, coordinatorAgent),
+					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()) {
@@ -2699,7 +3555,7 @@ async function runCoordinator(options) {
 				options,
 				runId,
 				turn: transcript.length + index + 1,
-				providerCallId: providerCallIdFor$1(runId, providerCalls.length + index + 1),
+				providerCallId: providerCallIdFor(runId, providerCalls.length + index + 1),
 				providerCallIndex: index,
 				providerCallSlots,
 				toolExecutor,
@@ -2743,7 +3599,7 @@ async function runCoordinator(options) {
 			stopIfNeeded();
 		}
 		if (!stopIfNeeded()) {
-			totalCost = await runCoordinatorTurn({
+			const synthesisOutcome = await runCoordinatorTurn({
 				agent: coordinator,
 				coordinator,
 				input: buildFinalSynthesisInput(options.intent, transcript, coordinator),
@@ -2761,6 +3617,17 @@ async function runCoordinator(options) {
 				emit,
 				recordProtocolDecision
 			});
+			totalCost = synthesisOutcome.totalCost;
+			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();
 		}
 	}
@@ -2813,6 +3680,7 @@ async function runCoordinator(options) {
 				cost: totalCost,
 				transcript: createTranscriptLink(transcript)
 			}),
+			...triggeringFailureForAbortMode !== void 0 ? { triggeringFailureForAbortMode } : {},
 			events,
 			transcript
 		},
@@ -2847,7 +3715,7 @@ async function runCoordinator(options) {
 			events,
 			transcript,
 			iteration: transcript.length,
-			elapsedMs: elapsedMs$2(startedAtMs)
+			elapsedMs: elapsedMs(startedAtMs)
 		}));
 		if (!stopRecord) return false;
 		stopped = true;
@@ -2863,13 +3731,16 @@ async function runCoordinator(options) {
 			reason: record.budgetReason ?? "cost",
 			cost: totalCost,
 			iteration: transcript.length,
-			elapsedMs: elapsedMs$2(startedAtMs),
+			elapsedMs: elapsedMs(startedAtMs),
 			detail: record.detail ?? {}
 		};
 		emit(event);
 		recordProtocolDecision(event, { transcriptEntryCount: transcript.length });
 	}
 }
+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 = {
@@ -2898,7 +3769,7 @@ async function runCoordinatorTurn(turn) {
 			events: turn.events,
 			transcript: turn.transcript,
 			iteration: turn.transcript.length,
-			elapsedMs: elapsedMs$2(turn.startedAtMs)
+			elapsedMs: elapsedMs(turn.startedAtMs)
 		})
 	};
 	const response = await generateModelTurn({
@@ -2913,7 +3784,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$2(response));
 	const toolCalls = await executeModelResponseToolRequests({
 		response,
@@ -2949,7 +3824,10 @@ 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);
@@ -2979,7 +3857,7 @@ async function runCoordinatorWorkerTurn(turn) {
 			events: turn.events,
 			transcript: turn.transcript,
 			iteration: turn.turn - 1,
-			elapsedMs: elapsedMs$2(turn.startedAtMs)
+			elapsedMs: elapsedMs(turn.startedAtMs)
 		})
 	};
 	const response = await generateModelTurn({
@@ -2994,7 +3872,21 @@ 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,
@@ -3021,6 +3913,30 @@ function buildSystemPrompt$2(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"] : void 0;
+	if (reason === "sibling-failed" || reason === "parent-aborted") return;
+	return {
+		childRunId: event.childRunId,
+		intent,
+		error: {
+			code: event.error.code,
+			message: event.error.message,
+			...reason !== void 0 ? { detail: { reason } } : {}
+		},
+		partialCost: { usd: event.partialCost.usd }
+	};
+}
 function buildWorkerInput(intent, transcript, coordinator) {
 	const prior = transcript.map((entry) => `${entry.role} (${entry.agentId}): ${entry.output}`).join("\n\n");
 	return `Mission: ${intent}\n\nCoordinator: ${coordinator.id}\nPrior contributions:\n${prior}\n\nFollow the coordinator-managed plan and provide your assigned contribution.`;
@@ -3037,22 +3953,386 @@ function responseCost$2(response) {
 		totalTokens: response.usage?.totalTokens ?? 0
 	};
 }
-function createRunId$2() {
-	return globalThis.crypto?.randomUUID?.() ?? `run-${Date.now().toString(36)}`;
+/**
+* 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;
+	if (options.effectiveMaxDepth !== void 0) assertDepthWithinLimit(input.parentDepth, options.effectiveMaxDepth);
+	const childRunId = input.childRunId ?? createRunId();
+	const recursive = decision.protocol === "coordinator";
+	const decisionTimeoutMs = decision.budget?.timeoutMs;
+	const parentDeadlineMs = options.parentDeadlineMs;
+	const remainingMs = parentDeadlineMs !== void 0 ? Math.max(0, parentDeadlineMs - Date.now()) : void 0;
+	if (parentDeadlineMs !== void 0 && remainingMs === 0) throw new DogpileError({
+		code: "aborted",
+		message: "Parent deadline elapsed before sub-run dispatch.",
+		retryable: false,
+		providerId: options.model.id,
+		detail: { reason: "timeout" }
+	});
+	let childTimeoutMs;
+	let clampedFrom;
+	if (remainingMs !== void 0) if (decisionTimeoutMs !== void 0) if (decisionTimeoutMs > remainingMs) {
+		clampedFrom = decisionTimeoutMs;
+		childTimeoutMs = remainingMs;
+	} else childTimeoutMs = decisionTimeoutMs;
+	else childTimeoutMs = remainingMs;
+	else if (decisionTimeoutMs !== void 0) childTimeoutMs = decisionTimeoutMs;
+	else if (options.defaultSubRunTimeoutMs !== void 0) 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"
+		}
+	});
+	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;
+	if (clampedFrom !== void 0 && childTimeoutMs !== void 0) {
+		const clampEvent = {
+			type: "sub-run-budget-clamped",
+			runId: input.parentRunId,
+			at: (/* @__PURE__ */ 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: (/* @__PURE__ */ 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);
+	const parentSignal = options.signal;
+	let removeParentAbortListener;
+	if (parentSignal !== void 0) 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 !== void 0 && parentDeadlineMs === void 0 ? createEngineDeadlineTimeoutError(options.model.id, childTimeoutMs) : void 0;
+	const childDeadlineTimer = childDeadlineReason !== void 0 ? setTimeout(() => {
+		input.dispatchedChild.controller.abort(childDeadlineReason);
+	}, childTimeoutMs) : void 0;
+	const childOptions = {
+		intent: decision.intent,
+		protocol: decision.protocol,
+		tier: options.tier,
+		model: options.model,
+		agents: options.agents,
+		tools: options.tools,
+		temperature: options.temperature,
+		...childTimeoutMs !== void 0 ? { budget: { timeoutMs: childTimeoutMs } } : {},
+		signal: input.dispatchedChild.controller.signal,
+		emit: teedEmit,
+		...options.streamEvents !== void 0 ? { streamEvents: options.streamEvents } : {},
+		currentDepth: input.parentDepth + 1,
+		...options.effectiveMaxDepth !== void 0 ? { effectiveMaxDepth: options.effectiveMaxDepth } : {},
+		...options.effectiveMaxConcurrentChildren !== void 0 ? { effectiveMaxConcurrentChildren: options.effectiveMaxConcurrentChildren } : {},
+		...options.onChildFailure !== void 0 ? { onChildFailure: options.onChildFailure } : {},
+		...parentDeadlineMs !== void 0 ? { parentDeadlineMs } : {},
+		...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {}
+	};
+	let subResult;
+	try {
+		subResult = await options.runProtocol(childOptions);
+	} catch (error) {
+		if (childDeadlineTimer !== void 0) 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 !== void 0 ? { model: decision.model } : {},
+			...decision.budget !== void 0 ? { 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 !== void 0 ? { childTimeoutMs } : {},
+			...options.seed !== void 0 ? { seed: options.seed } : {}
+		});
+		const enrichedError = enrichProviderTimeoutSource(enrichAbortErrorWithParentReason(error, parentSignal), {
+			...decisionTimeoutMs !== void 0 ? { decisionTimeoutMs } : {},
+			...options.defaultSubRunTimeoutMs !== void 0 ? { engineDefaultTimeoutMs: options.defaultSubRunTimeoutMs } : {}
+		});
+		if (DogpileError.isInstance(enrichedError)) options.failureInstancesByChildRunId?.set(childRunId, enrichedError);
+		const errorPayload = errorPayloadFromUnknown(enrichedError, failedDecision);
+		const partialCost = lastCostBearingEventCost(childEvents) ?? emptyCost();
+		input.recordSubRunCost(partialCost);
+		const failEvent = {
+			type: "sub-run-failed",
+			runId: input.parentRunId,
+			at: (/* @__PURE__ */ 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);
+		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 !== void 0) clearTimeout(childDeadlineTimer);
+	removeParentAbortListener?.();
+	input.recordSubRunCost(subResult.cost);
+	const completedEvent = {
+		type: "sub-run-completed",
+		runId: input.parentRunId,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		childRunId,
+		parentRunId: input.parentRunId,
+		parentDecisionId: input.parentDecisionId,
+		parentDecisionArrayIndex: input.parentDecisionArrayIndex,
+		subResult
+	};
+	parentEmit(completedEvent);
+	input.recordProtocolDecision(completedEvent);
+	input.dispatchedChild.closed = true;
+	if (parentSignal?.aborted) {
+		const abortMarker = {
+			type: "sub-run-parent-aborted",
+			runId: input.parentRunId,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			childRunId,
+			parentRunId: input.parentRunId,
+			reason: "parent-aborted"
+		};
+		parentEmit(abortMarker);
+		input.recordProtocolDecision(abortMarker);
+		throw enrichAbortErrorWithParentReason(createAbortErrorFromSignal(parentSignal, options.model.id), parentSignal);
+	}
+	const decisionAsJson = {
+		type: "delegate",
+		protocol: decision.protocol,
+		intent: decision.intent,
+		...decision.model !== void 0 ? { model: decision.model } : {},
+		...decision.budget !== void 0 ? { budget: decision.budget } : {}
+	};
+	const taggedText = renderSubRunResult(childRunId, subResult);
+	input.transcript.push({
+		agentId: `sub-run:${childRunId}`,
+		role: "delegate-result",
+		input: JSON.stringify(decisionAsJson),
+		output: taggedText
+	});
+	const coordinatorAgent = options.agents[0];
+	return {
+		nextInput: `${buildCoordinatorPlanInput(input.options.intent, coordinatorAgent ?? {
+			id: "coordinator",
+			role: "coordinator"
+		})}\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 = subResult.trace.events[0]?.at;
+	const endedAt = subResult.trace.events.at(-1)?.at;
+	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 nowMs$2() {
-	return globalThis.performance?.now() ?? Date.now();
+/**
+* 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 !== void 0 ? { caps: { timeoutMs: input.childTimeoutMs } } : {}
+		}),
+		budgetStateChanges: createReplayTraceBudgetStateChanges(input.events),
+		seed: createReplayTraceSeed(input.seed),
+		protocolDecisions: [],
+		providerCalls: [],
+		finalOutput: {
+			kind: "replay-trace-final-output",
+			output: "",
+			cost: emptyCost(),
+			completedAt: (/* @__PURE__ */ 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 === void 0 || !parentSignal.aborted) return error;
+	if (!DogpileError.isInstance(error) || error.code !== "aborted") return error;
+	const existingDetail = error.detail ?? {};
+	if (existingDetail["reason"] !== void 0) return error;
+	const reason = classifyAbortReason(parentSignal.reason);
+	return new DogpileError({
+		code: "aborted",
+		message: error.message,
+		retryable: error.retryable ?? false,
+		...error.providerId !== void 0 ? { providerId: error.providerId } : {},
+		detail: {
+			...existingDetail,
+			reason
+		},
+		...error.cause !== void 0 ? { cause: error.cause } : {}
+	});
 }
-function elapsedMs$2(startedAtMs) {
-	return Math.max(0, nowMs$2() - startedAtMs);
+function enrichProviderTimeoutSource(error, context) {
+	if (!DogpileError.isInstance(error) || error.code !== "provider-timeout") return error;
+	const existingDetail = error.detail ?? {};
+	if (existingDetail["source"] !== void 0) return error;
+	const source = classifyChildTimeoutSource(error, {
+		...context,
+		isProviderError: true
+	});
+	return new DogpileError({
+		code: "provider-timeout",
+		message: error.message,
+		retryable: error.retryable ?? true,
+		...error.providerId !== void 0 ? { providerId: error.providerId } : {},
+		detail: {
+			...existingDetail,
+			source
+		},
+		...error.cause !== void 0 ? { cause: error.cause } : {}
+	});
 }
-function providerCallIdFor$1(runId, oneBasedIndex) {
-	return `${runId}:provider-call:${oneBasedIndex}`;
+function errorPayloadFromUnknown(error, failedDecision) {
+	if (DogpileError.isInstance(error)) {
+		const detail = {
+			...error.detail ?? {},
+			failedDecision
+		};
+		return {
+			code: error.code,
+			message: error.message,
+			...error.providerId !== void 0 ? { providerId: error.providerId } : {},
+			detail
+		};
+	}
+	return {
+		code: "invalid-configuration",
+		message: error instanceof Error ? error.message : String(error),
+		detail: { failedDecision }
+	};
 }
 //#endregion
 //#region src/runtime/sequential.ts
 async function runSequential(options) {
-	const runId = createRunId$1();
+	const runId = createRunId();
 	const events = [];
 	const transcript = [];
 	const protocolDecisions = [];
@@ -3060,7 +4340,7 @@ async function runSequential(options) {
 	let totalCost = emptyCost();
 	const maxTurns = options.protocol.maxTurns ?? options.agents.length;
 	const activeAgents = options.agents.slice(0, maxTurns);
-	const startedAtMs = nowMs$1();
+	const startedAtMs = nowMs();
 	let stopped = false;
 	let termination;
 	const wrapUpHint = createWrapUpHintController({
@@ -3135,7 +4415,7 @@ async function runSequential(options) {
 				events,
 				transcript,
 				iteration: transcript.length,
-				elapsedMs: elapsedMs$1(startedAtMs)
+				elapsedMs: elapsedMs(startedAtMs)
 			})
 		};
 		const response = await generateModelTurn({
@@ -3187,7 +4467,8 @@ async function runSequential(options) {
 		});
 		if (stopIfNeeded()) break;
 	}
-	const output = [...transcript].reverse().find((entry) => isParticipatingDecision(entry.decision))?.output ?? "";
+	const reversed = [...transcript].reverse();
+	const output = reversed.find((entry) => isParticipatingDecision(entry.decision))?.output ?? reversed.find((entry) => entry.decision === void 0)?.output ?? "";
 	throwIfAborted(options.signal, options.model.id);
 	const final = {
 		type: "final",
@@ -3270,7 +4551,7 @@ async function runSequential(options) {
 			events,
 			transcript,
 			iteration: transcript.length,
-			elapsedMs: elapsedMs$1(startedAtMs)
+			elapsedMs: elapsedMs(startedAtMs)
 		}));
 		if (!stopRecord) return false;
 		stopped = true;
@@ -3286,7 +4567,7 @@ async function runSequential(options) {
 			reason: record.budgetReason ?? "cost",
 			cost: totalCost,
 			iteration: transcript.length,
-			elapsedMs: elapsedMs$1(startedAtMs),
+			elapsedMs: elapsedMs(startedAtMs),
 			detail: record.detail ?? {}
 		};
 		emit(event);
@@ -3309,15 +4590,6 @@ function responseCost$1(response) {
 		totalTokens: response.usage?.totalTokens ?? 0
 	};
 }
-function createRunId$1() {
-	return globalThis.crypto?.randomUUID?.() ?? `run-${Date.now().toString(36)}`;
-}
-function nowMs$1() {
-	return globalThis.performance?.now() ?? Date.now();
-}
-function elapsedMs$1(startedAtMs) {
-	return Math.max(0, nowMs$1() - startedAtMs);
-}
 //#endregion
 //#region src/runtime/shared.ts
 async function runShared(options) {
@@ -3594,20 +4866,10 @@ function responseCost(response) {
 		totalTokens: response.usage?.totalTokens ?? 0
 	};
 }
-function createRunId() {
-	return globalThis.crypto?.randomUUID?.() ?? `run-${Date.now().toString(36)}`;
-}
-function nowMs() {
-	return globalThis.performance?.now() ?? Date.now();
-}
-function elapsedMs(startedAtMs) {
-	return Math.max(0, nowMs() - startedAtMs);
-}
-function providerCallIdFor(runId, oneBasedIndex) {
-	return `${runId}:provider-call:${oneBasedIndex}`;
-}
 //#endregion
 //#region src/runtime/engine.ts
+var DEFAULT_MAX_DEPTH = 4;
+var DEFAULT_MAX_CONCURRENT_CHILDREN = 4;
 var defaultHighLevelProtocol = "sequential";
 var defaultHighLevelTier = "balanced";
 /**
@@ -3628,9 +4890,20 @@ function createEngine(options) {
 	const temperature = options.temperature ?? tierTemperature(options.tier);
 	const agents = orderAgentsForTemperature(options.agents ?? defaultAgents(), temperature, options.seed);
 	const terminate = options.terminate ?? (options.budget ? conditionFromBudget(options.budget) : void 0);
+	const engineMaxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+	const engineMaxConcurrentChildren = options.maxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN;
+	const engineOnChildFailure = options.onChildFailure;
 	return {
-		run(intent) {
+		run(intent, runOptions) {
 			validateMissionIntent(intent);
+			validateRunCallOptions(runOptions);
+			validateProviderLocality(options.model, "model");
+			const effectiveMaxDepth = Math.min(engineMaxDepth, runOptions?.maxDepth ?? Number.POSITIVE_INFINITY);
+			assertRunDoesNotRaiseEngineMax("maxConcurrentChildren", runOptions?.maxConcurrentChildren, engineMaxConcurrentChildren);
+			const effectiveMaxConcurrentChildren = Math.min(engineMaxConcurrentChildren, runOptions?.maxConcurrentChildren ?? Number.POSITIVE_INFINITY);
+			const onChildFailure = resolveOnChildFailure(runOptions?.onChildFailure, engineOnChildFailure);
+			const startedAtMs = Date.now();
+			const parentDeadlineMs = options.budget?.timeoutMs !== void 0 ? startedAtMs + options.budget.timeoutMs : void 0;
 			return runNonStreamingProtocol({
 				intent,
 				protocol,
@@ -3644,11 +4917,23 @@ function createEngine(options) {
 				...options.signal !== void 0 ? { signal: options.signal } : {},
 				...terminate ? { terminate } : {},
 				...options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {},
-				...options.evaluate ? { evaluate: options.evaluate } : {}
+				...options.evaluate ? { evaluate: options.evaluate } : {},
+				currentDepth: 0,
+				effectiveMaxDepth,
+				effectiveMaxConcurrentChildren,
+				onChildFailure,
+				...parentDeadlineMs !== void 0 ? { parentDeadlineMs } : {},
+				...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {}
 			});
 		},
-		stream(intent) {
+		stream(intent, runOptions) {
 			validateMissionIntent(intent);
+			validateRunCallOptions(runOptions);
+			validateProviderLocality(options.model, "model");
+			const effectiveMaxDepth = Math.min(engineMaxDepth, runOptions?.maxDepth ?? Number.POSITIVE_INFINITY);
+			assertRunDoesNotRaiseEngineMax("maxConcurrentChildren", runOptions?.maxConcurrentChildren, engineMaxConcurrentChildren);
+			const effectiveMaxConcurrentChildren = Math.min(engineMaxConcurrentChildren, runOptions?.maxConcurrentChildren ?? Number.POSITIVE_INFINITY);
+			const onChildFailure = resolveOnChildFailure(runOptions?.onChildFailure, engineOnChildFailure);
 			const pendingEvents = [];
 			const pendingResolvers = [];
 			const emittedEvents = [];
@@ -3665,7 +4950,10 @@ function createEngine(options) {
 			const abortRace = createAbortRace(abortController.signal, options.model.id);
 			let complete = false;
 			let lastRunId = "";
+			let rootRunId;
 			let pendingFinalEvent;
+			let activeAbortDrain;
+			const failureInstancesByChildRunId = /* @__PURE__ */ new Map();
 			let status = "running";
 			let resolveResult;
 			let rejectResult;
@@ -3711,6 +4999,8 @@ function createEngine(options) {
 			async function execute() {
 				if (status !== "running") return;
 				try {
+					const streamStartedAtMs = Date.now();
+					const streamParentDeadlineMs = options.budget?.timeoutMs !== void 0 ? streamStartedAtMs + options.budget.timeoutMs : void 0;
 					const baseResult = await abortRace.run(runProtocol({
 						intent,
 						protocol,
@@ -3723,17 +5013,32 @@ function createEngine(options) {
 						...options.seed !== void 0 ? { seed: options.seed } : {},
 						signal: abortController.signal,
 						...terminate ? { terminate } : {},
+						currentDepth: 0,
+						effectiveMaxDepth,
+						effectiveMaxConcurrentChildren,
+						onChildFailure,
+						...streamParentDeadlineMs !== void 0 ? { parentDeadlineMs: streamParentDeadlineMs } : {},
+						...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {},
+						streamEvents: true,
 						emit(event) {
 							if (status !== "running") return;
+							const parentRunIds = event.parentRunIds;
+							if (rootRunId === void 0 && parentRunIds === void 0) rootRunId = event.runId;
 							lastRunId = event.runId;
-							if (event.type === "final") {
+							if (event.type === "final" && event.runId === rootRunId) {
 								pendingFinalEvent = event;
 								return;
 							}
 							publish(event);
-						}
+						},
+						registerAbortDrain(drain) {
+							activeAbortDrain = drain;
+						},
+						failureInstancesByChildRunId
 					}));
 					if (status !== "running") return;
+					const terminalThrow = resolveRuntimeTerminalThrow(baseResult.trace, failureInstancesByChildRunId);
+					if (terminalThrow) throw terminalThrow;
 					const finalizedResult = await abortRace.run(applyRunEvaluation(baseResult, options.evaluate));
 					if (status !== "running") return;
 					const finalEvent = finalizedResult.trace.events.at(-1);
@@ -3746,6 +5051,10 @@ function createEngine(options) {
 					if (isStreamHandleStatus(status, "cancelled")) return;
 					const runtimeError = timeoutLifecycle.translateError(error);
 					status = isCancellationError(runtimeError) ? "cancelled" : "failed";
+					if (shouldPublishAborted(runtimeError)) {
+						activeAbortDrain?.(runtimeError);
+						publish(createStreamAbortedEvent(runtimeError, lastRunId));
+					}
 					publish(createStreamErrorEvent(runtimeError, lastRunId));
 					closeStream();
 					rejectResult(runtimeError);
@@ -3754,15 +5063,18 @@ function createEngine(options) {
 			function cancelRun(cause) {
 				if (status !== "running") return;
 				const error = createStreamCancellationError(options.model.id, cause);
-				status = "cancelled";
 				abortController.abort(error);
+				activeAbortDrain?.(error);
+				publish(createStreamAbortedEvent(error, lastRunId));
 				publish(createStreamErrorEvent(error, lastRunId));
+				status = "cancelled";
 				closeStream();
 				rejectResult(error);
 			}
 			function closeStream() {
 				if (complete) return;
 				complete = true;
+				failureInstancesByChildRunId.clear();
 				removeCallerAbortListener();
 				timeoutLifecycle.cleanup();
 				abortRace.cleanup();
@@ -3818,7 +5130,8 @@ function createNonStreamingAbortLifecycle(options) {
 	const timeoutLifecycle = createTimeoutAbortLifecycle({
 		abortController,
 		timeoutMs: options.timeoutMs,
-		providerId: options.providerId
+		providerId: options.providerId,
+		timeoutErrorSource: options.timeoutErrorSource ?? "runtime"
 	});
 	const abortRace = createAbortRace(abortController.signal, options.providerId);
 	const removeCallerAbortListener = wireCallerAbortSignal(options.callerSignal, abortController, () => {
@@ -3846,7 +5159,11 @@ function createTimeoutAbortLifecycle(options) {
 		},
 		cleanup() {}
 	};
-	const timeoutError = createTimeoutError(options.providerId, options.timeoutMs);
+	const timeoutSource = classifyChildTimeoutSource(void 0, {
+		...options.timeoutErrorSource === "engine" ? { engineDefaultTimeoutMs: options.timeoutMs } : {},
+		isProviderError: false
+	});
+	const timeoutError = options.timeoutErrorSource === "engine" && timeoutSource === "engine" ? createEngineDeadlineTimeoutError(options.providerId, options.timeoutMs) : createTimeoutError(options.providerId, options.timeoutMs);
 	const timeoutId = setTimeout(() => {
 		options.abortController.abort(timeoutError);
 	}, options.timeoutMs);
@@ -3914,6 +5231,23 @@ function timeoutMsFromTermination(condition) {
 function readAbortSignalReason(signal) {
 	return signal?.aborted ? signal.reason : void 0;
 }
+function createStreamAbortedEvent(error, runId) {
+	return {
+		type: "aborted",
+		runId,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		reason: streamAbortedReason(error)
+	};
+}
+function shouldPublishAborted(error) {
+	return DogpileError.isInstance(error) && (error.code === "aborted" || error.code === "timeout");
+}
+function streamAbortedReason(error) {
+	if (DogpileError.isInstance(error)) {
+		if (error.code === "timeout" || error.detail?.["reason"] === "timeout") return "timeout";
+	}
+	return "parent-aborted";
+}
 function createStreamErrorEvent(error, runId) {
 	if (DogpileError.isInstance(error)) return {
 		type: "error",
@@ -3946,10 +5280,12 @@ function dogpileErrorStreamDetail(error) {
 	return detail;
 }
 async function runNonStreamingProtocol(options) {
+	const failureInstancesByChildRunId = /* @__PURE__ */ new Map();
 	const abortLifecycle = createNonStreamingAbortLifecycle({
 		callerSignal: options.signal,
 		timeoutMs: runtimeTimeoutMs(options),
-		providerId: options.model.id
+		providerId: options.model.id,
+		timeoutErrorSource: options.currentDepth !== void 0 && options.currentDepth > 0 && options.parentDeadlineMs === void 0 ? "engine" : "runtime"
 	});
 	try {
 		const emittedEvents = [];
@@ -3958,7 +5294,8 @@ async function runNonStreamingProtocol(options) {
 			...abortLifecycle.signal !== void 0 ? { signal: abortLifecycle.signal } : {},
 			emit(event) {
 				emittedEvents.push(event);
-			}
+			},
+			failureInstancesByChildRunId
 		}));
 		const events = emittedEvents.length > 0 ? emittedEvents : result.trace.events;
 		const trace = {
@@ -3979,10 +5316,13 @@ async function runNonStreamingProtocol(options) {
 			eventLog: createRunEventLog(trace.runId, trace.protocol, events),
 			trace
 		};
+		const terminalThrow = resolveRuntimeTerminalThrow(runResult.trace, failureInstancesByChildRunId);
+		if (terminalThrow) throw terminalThrow;
 		return canonicalizeRunResult(await abortLifecycle.run(applyRunEvaluation(runResult, options.evaluate)));
 	} catch (error) {
 		throw abortLifecycle.translateError(error);
 	} finally {
+		failureInstancesByChildRunId.clear();
 		abortLifecycle.cleanup();
 	}
 }
@@ -4057,7 +5397,20 @@ function runProtocol(options) {
 			...options.signal !== void 0 ? { signal: options.signal } : {},
 			...options.terminate ? { terminate: options.terminate } : {},
 			...options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {},
-			...options.emit ? { emit: options.emit } : {}
+			...options.emit ? { emit: options.emit } : {},
+			...options.streamEvents !== void 0 ? { streamEvents: options.streamEvents } : {},
+			currentDepth: options.currentDepth ?? 0,
+			effectiveMaxDepth: options.effectiveMaxDepth ?? Infinity,
+			effectiveMaxConcurrentChildren: options.effectiveMaxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN,
+			onChildFailure: options.onChildFailure ?? "continue",
+			...options.parentDeadlineMs !== void 0 ? { parentDeadlineMs: options.parentDeadlineMs } : {},
+			...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {},
+			...options.registerAbortDrain !== void 0 ? { registerAbortDrain: options.registerAbortDrain } : {},
+			...options.failureInstancesByChildRunId !== void 0 ? { failureInstancesByChildRunId: options.failureInstancesByChildRunId } : {},
+			runProtocol: (childInput) => runProtocol({
+				...childInput,
+				protocol: normalizeProtocol(childInput.protocol)
+			})
 		});
 		case "shared": return runShared({
 			intent: options.intent,
@@ -4124,6 +5477,9 @@ function stream(options) {
 function replay(trace) {
 	const cost = trace.finalOutput.cost;
 	const lastEvent = trace.events.at(-1);
+	const accounting = recomputeAccountingFromTrace(trace);
+	const replayThrow = resolveReplayTerminalThrow(trace);
+	if (replayThrow) throw replayThrow;
 	const baseResult = {
 		output: trace.finalOutput.output,
 		eventLog: createRunEventLog(trace.runId, trace.protocol, trace.events),
@@ -4138,13 +5494,7 @@ function replay(trace) {
 			agentsUsed: trace.agentsUsed,
 			events: trace.events
 		}),
-		accounting: createRunAccounting({
-			tier: trace.tier,
-			...trace.budget.caps ? { budget: trace.budget.caps } : {},
-			...trace.budget.termination ? { termination: trace.budget.termination } : {},
-			cost,
-			events: trace.events
-		}),
+		accounting,
 		cost
 	};
 	if (lastEvent?.type !== "final") return baseResult;
@@ -4154,6 +5504,64 @@ function replay(trace) {
 		...lastEvent.evaluation !== void 0 ? { evaluation: lastEvent.evaluation } : {}
 	};
 }
+function resolveRuntimeTerminalThrow(trace, failureInstancesByChildRunId) {
+	if (trace.triggeringFailureForAbortMode !== void 0) return failureInstancesByChildRunId.get(trace.triggeringFailureForAbortMode.childRunId) ?? null;
+	const finalEvent = trace.events.at(-1);
+	if (finalEvent?.type !== "final" || finalEvent.termination === void 0) return null;
+	const lastFailure = findLastRealFailure(trace.events, failureInstancesByChildRunId);
+	if (lastFailure === null) return null;
+	if (hasFinalSynthesisAfterEvent(trace, lastFailure.eventIndex)) return null;
+	return lastFailure.error;
+}
+function findLastRealFailure(events, failureInstancesByChildRunId) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event?.type !== "sub-run-failed") continue;
+		const instance = failureInstancesByChildRunId.get(event.childRunId);
+		if (instance) return {
+			error: instance,
+			eventIndex: index
+		};
+	}
+	return null;
+}
+function resolveReplayTerminalThrow(trace) {
+	if (trace.triggeringFailureForAbortMode !== void 0) return dogpileErrorFromSerializedPayload(trace.triggeringFailureForAbortMode.error);
+	const finalEvent = trace.events.at(-1);
+	if (finalEvent?.type !== "final" || finalEvent.termination === void 0) return null;
+	const lastFailure = reconstructLastRealFailure(trace.events);
+	if (lastFailure === null) return null;
+	if (hasFinalSynthesisAfterEvent(trace, lastFailure.eventIndex)) return null;
+	return lastFailure.error;
+}
+function reconstructLastRealFailure(events) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event?.type !== "sub-run-failed" || isSyntheticSubRunFailure(event)) continue;
+		return {
+			error: dogpileErrorFromSerializedPayload(event.error),
+			eventIndex: index
+		};
+	}
+	return null;
+}
+function hasFinalSynthesisAfterEvent(trace, eventIndex) {
+	return trace.protocolDecisions.some((decision) => {
+		return decision.phase === "final-synthesis" && decision.eventIndex > eventIndex;
+	});
+}
+function isSyntheticSubRunFailure(event) {
+	const reason = event.error.detail?.["reason"];
+	return reason === "sibling-failed" || reason === "parent-aborted";
+}
+function dogpileErrorFromSerializedPayload(input) {
+	return new DogpileError({
+		code: input.code,
+		message: input.message,
+		...input.providerId !== void 0 ? { providerId: input.providerId } : {},
+		...input.detail !== void 0 ? { detail: input.detail } : {}
+	});
+}
 /**
 * Replay a saved completed trace as a stream without invoking a model provider.
 *
@@ -4164,20 +5572,22 @@ function replay(trace) {
 * replay remains storage-free and provider-free.
 */
 function replayStream(trace) {
+	const result = Promise.resolve(replay(trace));
+	const replayEvents = replayStreamEvents(trace);
 	return {
 		get status() {
 			return "completed";
 		},
-		result: Promise.resolve(replay(trace)),
+		result,
 		cancel() {},
 		subscribe(subscriber) {
-			for (const event of trace.events) subscriber(event);
+			for (const event of replayEvents) subscriber(event);
 			return { unsubscribe() {} };
 		},
 		[Symbol.asyncIterator]() {
 			let index = 0;
 			return { next() {
-				const event = trace.events[index];
+				const event = replayEvents[index];
 				if (event) {
 					index += 1;
 					return Promise.resolve({
@@ -4193,6 +5603,22 @@ function replayStream(trace) {
 		}
 	};
 }
+function replayStreamEvents(trace, parentRunIds = []) {
+	const events = [];
+	for (const event of trace.events) {
+		if (event.type === "sub-run-completed") events.push(...replayStreamEvents(event.subResult.trace, [...parentRunIds, trace.runId]));
+		events.push(wrapReplayStreamEvent(event, parentRunIds));
+	}
+	return events;
+}
+function wrapReplayStreamEvent(event, parentRunIds) {
+	if (parentRunIds.length === 0) return event;
+	const inbound = event.parentRunIds;
+	return {
+		...event,
+		parentRunIds: [...parentRunIds, ...inbound ?? []]
+	};
+}
 function wireCallerAbortSignal(callerSignal, abortController, cancelRun) {
 	if (!callerSignal) return () => {};
 	const cancelFromCaller = () => {
@@ -4216,7 +5642,10 @@ function createStreamCancellationError(providerId, cause) {
 		retryable: false,
 		providerId,
 		...cause !== void 0 ? { cause } : {},
-		detail: { status: "cancelled" }
+		detail: {
+			status: "cancelled",
+			reason: "parent-aborted"
+		}
 	});
 }
 function isCancellationError(error) {
@@ -4230,6 +5659,20 @@ function withHighLevelDefaults(options) {
 		tier: options.tier ?? defaultHighLevelTier
 	};
 }
+function assertRunDoesNotRaiseEngineMax(path, runValue, engineValue) {
+	if (runValue === void 0 || runValue <= engineValue) return;
+	throw new DogpileError({
+		code: "invalid-configuration",
+		message: `${path} cannot raise the engine ceiling (${engineValue}).`,
+		retryable: false,
+		detail: {
+			kind: "configuration-validation",
+			path,
+			expected: `integer <= ${engineValue}`,
+			actual: runValue
+		}
+	});
+}
 /**
 * Branded high-level SDK namespace.
 *
@@ -4256,6 +5699,8 @@ function createOpenAICompatibleProvider(options) {
 	validateOptions(options);
 	const providerId = options.id ?? `openai-compatible:${options.model}`;
 	const fetchImplementation = options.fetch ?? globalThis.fetch?.bind(globalThis);
+	const detectedLocality = classifyHostLocality(new URL(String(options.baseURL ?? defaultBaseURL)).hostname);
+	const resolvedLocality = options.locality === "local" ? "local" : options.locality === "remote" ? "remote" : detectedLocality;
 	if (!fetchImplementation) throw new DogpileError({
 		code: "invalid-configuration",
 		message: "createOpenAICompatibleProvider() requires a fetch implementation in this runtime.",
@@ -4269,6 +5714,7 @@ function createOpenAICompatibleProvider(options) {
 	});
 	return {
 		id: providerId,
+		metadata: { locality: resolvedLocality },
 		async generate(request) {
 			let response;
 			try {
@@ -4281,9 +5727,11 @@ function createOpenAICompatibleProvider(options) {
 			} catch (error) {
 				throw normalizeFetchError(error, providerId);
 			}
-			const payload = await readJson(response, providerId);
-			if (!response.ok) throw createProviderError(response, payload, providerId);
-			const completion = asChatCompletionResponse(payload, providerId);
+			if (!response.ok) {
+				const payload = await readJsonLenient(response);
+				throw createProviderError(response, payload, providerId);
+			}
+			const completion = asChatCompletionResponse(await readJson(response, providerId), providerId);
 			const text = readAssistantText(completion, providerId);
 			const usage = normalizeUsage(completion.usage);
 			const finishReason = normalizeFinishReason(completion.choices?.[0]?.finish_reason);
@@ -4312,6 +5760,22 @@ function validateOptions(options) {
 	if (options.fetch !== void 0 && typeof options.fetch !== "function") throwInvalid("fetch", "a fetch-compatible function when provided");
 	if (options.maxOutputTokens !== void 0 && (!Number.isInteger(options.maxOutputTokens) || options.maxOutputTokens <= 0)) throwInvalid("maxOutputTokens", "a positive integer when provided");
 	if (options.costEstimator !== void 0 && typeof options.costEstimator !== "function") throwInvalid("costEstimator", "a function when provided");
+	if (options.locality !== void 0 && options.locality !== "local" && options.locality !== "remote") throwInvalid("locality", "\"local\" | \"remote\" when provided");
+	if (options.locality === "remote") {
+		const baseURL = new URL(String(options.baseURL ?? defaultBaseURL));
+		if (classifyHostLocality(baseURL.hostname) === "local") throw new DogpileError({
+			code: "invalid-configuration",
+			message: `locality "remote" cannot be set when baseURL resolves to a local host (${baseURL.hostname}).`,
+			retryable: false,
+			detail: {
+				kind: "configuration-validation",
+				path: "locality",
+				expected: "\"local\" (or omit to auto-detect)",
+				reason: "remote-override-on-local-host",
+				host: baseURL.hostname
+			}
+		});
+	}
 }
 function throwInvalid(path, expected) {
 	throw new DogpileError({
@@ -4325,6 +5789,38 @@ function throwInvalid(path, expected) {
 		}
 	});
 }
+/**
+* Classify a URL hostname as "local" or "remote" per Phase 3 D-02.
+* Local: localhost, *.local mDNS, IPv4 loopback (127.0.0.0/8), RFC1918
+* (10/8, 172.16/12, 192.168/16), link-local (169.254/16), IPv6 loopback (::1),
+* IPv6 ULA (fc00::/7), IPv6 link-local (fe80::/10).
+*
+* Pure function: no I/O, no side effects. Exported for tests and future reuse.
+*/
+function classifyHostLocality(host) {
+	const lower = host.toLowerCase().replace(/^\[|\]$/g, "");
+	const mappedIpv4 = ipv4MappedToDottedQuad(lower);
+	if (mappedIpv4 !== void 0) return classifyHostLocality(mappedIpv4);
+	if (lower === "localhost") return "local";
+	if (lower.endsWith(".local")) return "local";
+	if (/^127(?:\.\d{1,3}){3}$/.test(lower)) return "local";
+	if (/^10(?:\.\d{1,3}){3}$/.test(lower)) return "local";
+	if (/^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+	if (/^192\.168(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+	if (/^169\.254(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+	if (lower === "::1") return "local";
+	if (/^f[cd][0-9a-f]{2}:/.test(lower)) return "local";
+	if (/^fe[89ab][0-9a-f]?:/.test(lower)) return "local";
+	return "remote";
+}
+function ipv4MappedToDottedQuad(host) {
+	const match = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+	if (match === null) return;
+	const high = Number.parseInt(match[1] ?? "", 16);
+	const low = Number.parseInt(match[2] ?? "", 16);
+	if (!Number.isFinite(high) || !Number.isFinite(low)) return;
+	return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
 function createURL(options) {
 	const baseURL = new URL(String(options.baseURL ?? defaultBaseURL));
 	const path = options.path ?? defaultPath;
@@ -4374,6 +5870,13 @@ async function readJson(response, providerId) {
 		});
 	}
 }
+async function readJsonLenient(response) {
+	try {
+		return await response.json();
+	} catch {
+		return;
+	}
+}
 function asChatCompletionResponse(payload, providerId) {
 	if (!isRecord(payload)) throw new DogpileError({
 		code: "provider-invalid-response",
@@ -4444,14 +5947,17 @@ function responseMetadata(response) {
 	});
 }
 function createProviderError(response, payload, providerId) {
+	const code = codeForStatus(response.status);
+	const timeoutSource = code === "provider-timeout" ? { source: "provider" } : {};
 	return new DogpileError({
-		code: codeForStatus(response.status),
+		code,
 		message: providerResponseErrorMessage(response, payload),
 		retryable: response.status === 408 || response.status === 429 || response.status >= 500,
 		providerId,
 		detail: removeUndefined({
 			statusCode: response.status,
 			statusText: response.statusText,
+			...timeoutSource,
 			response: isJsonValue(payload) ? payload : void 0
 		})
 	});
@@ -4515,6 +6021,263 @@ function isJsonValue(value) {
 	return false;
 }
 //#endregion
-export { Dogpile, DogpileError, budget, builtInDogpileToolIdentity, builtInDogpileToolInputSchema, builtInDogpileToolPermissions, combineTerminationDecisions, convergence, createCodeExecToolAdapter, createEngine, createOpenAICompatibleProvider, createRuntimeToolExecutor, createWebSearchToolAdapter, evaluateBudget, evaluateConvergence, evaluateFirstOf, evaluateJudge, evaluateTermination, evaluateTerminationStop, firstOf, judge, normalizeBuiltInDogpileTool, normalizeBuiltInDogpileTools, normalizeRuntimeToolAdapterError, replay, replayStream, run, runtimeToolAvailability, runtimeToolManifest, stream, validateBuiltInDogpileToolInput };
+//#region src/runtime/logger.ts
+/** Logger that drops every call. The default when no logger is supplied. */
+var noopLogger = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {}
+};
+/**
+* Build a console-backed logger respecting a minimum level.
+*
+* The output format is JSON-on-one-line so it can be piped straight into log
+* collectors. Use `loggerFromEvents` to bridge it to a Dogpile stream handle.
+*/
+function consoleLogger(options = {}) {
+	const minLevel = options.level ?? "info";
+	const allowed = (level) => LEVEL_ORDER[level] >= LEVEL_ORDER[minLevel];
+	const emit = (level, message, fields) => {
+		if (!allowed(level)) return;
+		const payload = {
+			level,
+			message
+		};
+		if (fields !== void 0) payload.fields = fields;
+		(level === "error" ? console.error : level === "warn" ? console.warn : console.log)(JSON.stringify(payload));
+	};
+	return {
+		debug: (message, fields) => emit("debug", message, fields),
+		info: (message, fields) => emit("info", message, fields),
+		warn: (message, fields) => emit("warn", message, fields),
+		error: (message, fields) => emit("error", message, fields)
+	};
+}
+var LEVEL_ORDER = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+/**
+* Bridge a `Logger` to a Dogpile stream handle by returning a
+* `StreamEventSubscriber`. Pass it to `handle.subscribe(...)`.
+*
+* Logger throws are caught and routed to `logger.error` so a misbehaving
+* logger can never crash an in-flight run.
+*
+* @example
+* ```ts
+* const handle = Dogpile.stream({ intent, model });
+* handle.subscribe(loggerFromEvents(consoleLogger({ level: "info" })));
+* const result = await handle.result;
+* ```
+*/
+function loggerFromEvents(logger, options = {}) {
+	const includeSet = options.include ? new Set(options.include) : void 0;
+	return (event) => {
+		const eventType = event.type;
+		if (includeSet && !includeSet.has(eventType)) return;
+		const level = options.levelFor?.(event) ?? defaultLevel(event);
+		const message = describeEvent(event);
+		const fields = summarizeEvent(event);
+		try {
+			logger[level](message, fields);
+		} catch (cause) {
+			try {
+				logger.error("dogpile logger threw while handling event", {
+					eventType,
+					error: cause instanceof Error ? cause.message : String(cause)
+				});
+			} catch {}
+		}
+	};
+}
+function defaultLevel(event) {
+	switch (event.type) {
+		case "model-output-chunk": return "debug";
+		case "budget-stop": return "warn";
+		case "error": return "error";
+		case "tool-result": return event.result?.type === "error" ? "warn" : "info";
+		default: return "info";
+	}
+}
+function describeEvent(event) {
+	return `dogpile:${event.type}`;
+}
+function summarizeEvent(event) {
+	const fields = { eventType: event.type };
+	const at = event.at;
+	if (typeof at === "string") fields.at = at;
+	const runId = event.runId;
+	if (typeof runId === "string") fields.runId = runId;
+	const agentId = event.agentId;
+	if (typeof agentId === "string") fields.agentId = agentId;
+	const role = event.role;
+	if (typeof role === "string") fields.role = role;
+	return fields;
+}
+//#endregion
+//#region src/runtime/retry.ts
+/**
+* Default DogpileError codes that `withRetry` retries when no `retryOn`
+* predicate is supplied. These map to the transient provider failures listed
+* in `docs/developer-usage.md`.
+*/
+var DEFAULT_RETRYABLE_DOGPILE_CODES = [
+	"provider-rate-limited",
+	"provider-timeout",
+	"provider-unavailable"
+];
+var DEFAULTS = {
+	maxAttempts: 3,
+	baseDelayMs: 250,
+	maxDelayMs: 4e3,
+	jitter: "full"
+};
+/**
+* Wrap a `ConfiguredModelProvider` with a retry policy. The wrapper:
+*
+* - Preserves the provider `id` so traces remain stable.
+* - Retries `generate()` calls when the policy says the error is retryable.
+* - Propagates `AbortSignal` cancellation immediately — never retries after
+*   the caller cancels.
+* - Honors a `Retry-After`-style hint exposed via `error.detail.retryAfterMs`
+*   when present and the policy did not provide its own `delayForError`.
+* - Forwards `stream()` calls through unchanged — streaming retries cannot be
+*   safely automated because partial output may have already been observed.
+*
+* @example
+* ```ts
+* const robustProvider = withRetry(rawProvider, {
+*   maxAttempts: 4,
+*   baseDelayMs: 500,
+*   onRetry: ({ attempt, delayMs, error }) => {
+*     logger.warn("provider retry", { attempt, delayMs, error });
+*   }
+* });
+* ```
+*/
+function withRetry(provider, policy = {}) {
+	const settings = {
+		maxAttempts: policy.maxAttempts ?? DEFAULTS.maxAttempts,
+		baseDelayMs: policy.baseDelayMs ?? DEFAULTS.baseDelayMs,
+		maxDelayMs: policy.maxDelayMs ?? DEFAULTS.maxDelayMs,
+		jitter: policy.jitter ?? DEFAULTS.jitter,
+		retryOn: policy.retryOn ?? defaultRetryOn,
+		random: policy.random ?? Math.random,
+		sleep: policy.sleep ?? defaultSleep
+	};
+	if (settings.maxAttempts < 1) throw new DogpileError({
+		code: "invalid-configuration",
+		message: "withRetry: maxAttempts must be >= 1.",
+		detail: { maxAttempts: settings.maxAttempts }
+	});
+	if (settings.baseDelayMs < 0 || settings.maxDelayMs < 0) throw new DogpileError({
+		code: "invalid-configuration",
+		message: "withRetry: delay fields must be non-negative.",
+		detail: {
+			baseDelayMs: settings.baseDelayMs,
+			maxDelayMs: settings.maxDelayMs
+		}
+	});
+	const wrapped = {
+		id: provider.id,
+		async generate(request) {
+			let lastError;
+			for (let attempt = 1; attempt <= settings.maxAttempts; attempt++) {
+				if (request.signal?.aborted) throw abortReason(request.signal);
+				try {
+					return await provider.generate(request);
+				} catch (error) {
+					lastError = error;
+					if (isAbortError(error) || request.signal?.aborted) throw error;
+					if (attempt >= settings.maxAttempts || !settings.retryOn(error)) throw error;
+					const delayMs = chooseDelay({
+						attempt,
+						error,
+						settings,
+						policy
+					});
+					policy.onRetry?.({
+						attempt,
+						maxAttempts: settings.maxAttempts,
+						delayMs,
+						error,
+						providerId: provider.id
+					});
+					await settings.sleep(delayMs, request.signal);
+				}
+			}
+			throw lastError ?? new DogpileError({
+				code: "unknown",
+				message: "withRetry: exhausted attempts without throwing or returning."
+			});
+		}
+	};
+	if (typeof provider.stream === "function") {
+		const upstreamStream = provider.stream.bind(provider);
+		wrapped.stream = (request) => upstreamStream(request);
+	}
+	return wrapped;
+}
+function chooseDelay(args) {
+	const override = args.policy.delayForError?.(args.error) ?? retryAfterFromError(args.error);
+	if (override !== void 0 && Number.isFinite(override) && override >= 0) return Math.min(args.settings.maxDelayMs, override);
+	const exponential = args.settings.baseDelayMs * 2 ** (args.attempt - 1);
+	const capped = Math.min(args.settings.maxDelayMs, exponential);
+	if (args.settings.jitter === "none") return capped;
+	return Math.floor(capped * args.settings.random());
+}
+function defaultRetryOn(error) {
+	if (isAbortError(error)) return false;
+	if (DogpileError.isInstance(error)) {
+		if (error.code === "aborted" || error.code === "invalid-configuration") return false;
+		return DEFAULT_RETRYABLE_DOGPILE_CODES.includes(error.code);
+	}
+	if (error instanceof TypeError) return true;
+	return false;
+}
+function isAbortError(error) {
+	if (DogpileError.isInstance(error) && error.code === "aborted") return true;
+	if (typeof error === "object" && error !== null) {
+		if (error.name === "AbortError") return true;
+	}
+	return false;
+}
+function abortReason(signal) {
+	return signal.reason ?? new DogpileError({
+		code: "aborted",
+		message: "Request aborted."
+	});
+}
+function retryAfterFromError(error) {
+	if (!DogpileError.isInstance(error)) return void 0;
+	const detail = error.detail;
+	if (!detail || typeof detail !== "object") return void 0;
+	const candidate = detail.retryAfterMs;
+	if (typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0) return candidate;
+}
+function defaultSleep(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(abortReason(signal));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(abortReason(signal));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+export { DEFAULT_RETRYABLE_DOGPILE_CODES, Dogpile, DogpileError, budget, builtInDogpileToolIdentity, builtInDogpileToolInputSchema, builtInDogpileToolPermissions, combineTerminationDecisions, consoleLogger, convergence, createCodeExecToolAdapter, createEngine, createOpenAICompatibleProvider, createRuntimeToolExecutor, createWebSearchToolAdapter, evaluateBudget, evaluateConvergence, evaluateFirstOf, evaluateJudge, evaluateTermination, evaluateTerminationStop, firstOf, judge, loggerFromEvents, noopLogger, normalizeBuiltInDogpileTool, normalizeBuiltInDogpileTools, normalizeRuntimeToolAdapterError, replay, replayStream, run, runtimeToolAvailability, runtimeToolManifest, stream, validateBuiltInDogpileToolInput, withRetry };
 
 //# sourceMappingURL=index.js.map