@graphorin/agent 0.6.1 → 0.7.0

package/dist/factory.js

@@ -1,619 +1,28 @@
-import { AgentRuntimeError, ConcurrentRunError, InvalidAgentConfigError, InvalidPreferredModelError, MultipleHandoffsInStepError, ToolNotFoundError } from "./errors/index.js";
-import { isAgentFallbackEligible } from "./fallback/index.js";
-import { runFanOut } from "./fanout/index.js";
-import { filters } from "./filters/index.js";
+import { AgentRuntimeError, ConcurrentRunError, InvalidAgentConfigError, InvalidPreferredModelError, MultipleHandoffsInStepError } from "./errors/index.js";
 import { newId } from "./internal/ids.js";
 import { InMemoryUsageAccumulator } from "./internal/usage-accumulator.js";
 import { CausalityMonitor } from "./lateral-leak/causality-monitor.js";
-import { resolvePreferredModel } from "./preferred-model/index.js";
 import { createProgressIO } from "./progress/index.js";
-import { addModelUsage, createInitialRunState, serializeRunState } from "./run-state/index.js";
-import { buildMemoryGuard, buildSecretResolver, buildToolTokenCounter, createExecutorEventBridge, createMemoryRegionReader } from "./tooling/adapters.js";
-import { orderPromotedTools } from "./tooling/catalogue.js";
-import { buildDataFlowGuard } from "./tooling/dataflow.js";
-import { PLAN_TOOL_NAME, createPlanTool, renderPlanRecitation } from "./tooling/plan.js";
-import { buildToolArgumentPolicy } from "./tooling/policy.js";
-import { buildToolRegistry } from "./tooling/registry-build.js";
-import { createHash } from "node:crypto";
-import { NOOP_LOGGER, NOOP_TRACER, isStepCount, zeroUsage } from "@graphorin/core";
-import { composeGuardrails } from "@graphorin/security/guardrails";
-import { createReadResultTool, createToolSearchTool } from "@graphorin/tools/built-in";
-import { createCodeExecuteTool, createCodeSearchTool, projectToolApi } from "@graphorin/tools/code-mode";
-import { createToolExecutor } from "@graphorin/tools/executor";
-import { createDefaultSpillWriter, createFileResultReader } from "@graphorin/tools/result";
-import { projectSchemaToJsonSchema } from "@graphorin/tools/schema";
+import { addModelUsage, serializeRunState } from "./run-state/index.js";
+import { accumulateUsage, applyReasoningRetention, countLeadingSystemMessages } from "./runtime/messages.js";
+import { maybeAutoCompact, noopCompactionResult, tryEmergencyCompact } from "./runtime/run-compaction.js";
+import { createCompactMethod, createFanOutMethod, createProgressSurface, createRunMethods } from "./runtime/agent-surface.js";
+import { createToTool } from "./runtime/agent-to-tool.js";
+import { HANDOFF_TOOL_PREFIX, isDescribedFilter } from "./runtime/handoff.js";
+import { dispatchResumedApprovals, processResumeDirective, processSubRunResumes } from "./runtime/approvals.js";
+import { dispatchToolBatch } from "./runtime/dispatch.js";
+import { wireToolExecution } from "./runtime/executor-wiring.js";
+import { runProviderFallbackChain } from "./runtime/fallback-chain.js";
+import { createRunFinisher } from "./runtime/run-finish.js";
+import { buildStructuredInstruction, commitAssistantMessage, emitCancellation, finalizeRunOutput, runVerifierGate, screenInputGuardrails } from "./runtime/run-gates.js";
+import { initializeRunState, seedInitialMessages } from "./runtime/run-init.js";
+import { asMessages, isModelHintLike, isModelSpecLike, validatePreferredModel } from "./runtime/run-input.js";
+import { buildBaseRequest, resolveStepToolContext, toolToDefinition } from "./runtime/step-catalogue.js";
+import { processStepToolCalls } from "./runtime/tool-call-walk.js";
+import { NOOP_TRACER, isStepCount } from "@graphorin/core";
 
 //#region src/factory.ts
 /**
-* `createAgent({...})` - the agent factory entry point.
-*
-* Wires the typed `model -> tool calls -> model` loop, the streamed
-* event surface, the steering / followUp queues, durable HITL via
-* `RunState`, the multi-agent handoff layer, the agent-level model
-* fallback chain, and the per-tool preferred-model resolution.
-*
-* Custom adapters override behaviour by supplying alternative
-* `Provider` / `Memory` / `CheckpointStore` instances; the loop
-* never reaches into adapter internals.
-*
-* @packageDocumentation
-*/
-/**
-* Replacement content committed in place of assistant commentary the
-* causality monitor blocked (AG-10). Worded to not match any built-in
-* denial pattern, so the notice itself never re-triggers the monitor.
-*/
-const LATERAL_LEAK_BLOCKED_NOTICE = "[graphorin] assistant commentary withheld by the lateral-leak defense.";
-const sha256Hex = (input) => createHash("sha256").update(input, "utf8").digest("hex");
-const HANDOFF_TOOL_PREFIX = "transfer_to_";
-/** The built-in deferred-discovery tool's stable name (WI-05 / P0-3). */
-const TOOL_SEARCH_NAME = "tool_search";
-/**
-* Register the built-in `tool_search` into `registry` when - and only
-* when - the registry holds at least one deferred tool
-* (`defer_loading: true`). `tool_search` is itself eager (so it is
-* always advertised while a deferred pool exists) and resolvable by the
-* executor like any other tool, so a model can both *see* it in the
-* per-step catalogue and *call* it.
-*
-* No-op when nothing defers (zero overhead - the tool never appears) or
-* when a user tool already occupies the name (the user's tool wins; we
-* never clobber it). Because deferral is decided at registration time
-* (`normaliseTool`), the deferred set is fixed for the life of the
-* registry - this runs once per registry, not per step.
-*/
-function registerToolSearch(registry, availability) {
-	if (registry.listDeferred().length === 0) return;
-	if (registry.get(TOOL_SEARCH_NAME) !== void 0) return;
-	registry.register(createToolSearchTool({
-		registry,
-		...availability !== void 0 ? { availability } : {}
-	}), {
-		kind: "built-in",
-		subsystem: "tool-discovery"
-	});
-}
-/** The built-in result-handle reader tool's stable name (WI-10 / P1-4). */
-const READ_RESULT_NAME = "read_result";
-/**
-* Register the built-in `read_result` into `registry` when at least one
-* registered tool opts into the `'spill-to-file'` truncation strategy
-* (the sole producer of spill handles today) - or when `force` is set,
-* which the agent passes when an operator wires external result readers
-* (e.g. an MCP `resource_link` reader; WI-13). The tool is eager, so it
-* is advertised alongside the producing tool and the model can fetch a
-* handle back on demand instead of inlining the full blob. No-op when
-* nothing produces handles (zero overhead) or when a user tool already
-* occupies the name (the user's tool wins).
-*/
-function registerReadResult(registry, reader, opts) {
-	if (opts?.force !== true && !registry.list().some((entry) => entry.truncationStrategy === "spill-to-file")) return;
-	if (registry.get(READ_RESULT_NAME) !== void 0) return;
-	registry.register(createReadResultTool({ reader }), {
-		kind: "built-in",
-		subsystem: "result-handle"
-	});
-}
-/**
-* Compose result readers into one that tries each in order, returning
-* the first that resolves the handle (WI-13). The spill-file reader is
-* placed first so `graphorin-spill:` handles resolve locally; operator
-* readers (e.g. an MCP resource reader) resolve the rest. Each reader
-* rejects handles it does not own, so resolution falls through cleanly.
-*/
-function composeResultReaders(readers) {
-	return { async read(uri, range) {
-		let lastError;
-		for (const r of readers) try {
-			return await r.read(uri, range);
-		} catch (err) {
-			lastError = err;
-		}
-		throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error(`No result reader resolved handle ${JSON.stringify(uri)}.`);
-	} };
-}
-/** The code-mode meta-tools' stable names (WI-11 / P1-2). */
-const CODE_EXECUTE_NAME = "code_execute";
-const CODE_SEARCH_NAME = "code_search";
-/** Structural check: is this tool approval-gated (static or predicate form)? */
-const isApprovalGated = (t) => t.needsApproval === true || typeof t.needsApproval === "function";
-/**
-* Wire code-mode (P1-2) into `registry`: register the `code_search` /
-* `code_execute` meta-tools and return them as the tools to advertise in
-* place of the full catalogue. The model reaches every other tool through
-* `code_execute`, whose in-script `tools.<name>(args)` calls route back
-* through `quietExecutor.executeOne(...)` under the calling step's
-* `runContext` - so per-tool ACL / sanitization / truncation still apply,
-* exactly as in direct mode. `quietExecutor` carries no `streamingSink`,
-* so the inner calls do not interleave `tool.execute.*` events into the
-* outer stream.
-*
-* Excluded from the code API (`reservedNames`): the meta-tools, the
-* discovery / handle built-ins, handoff tools (which stay first-class
-* provider tools), and - supplied by the caller - any approval-gated
-* tool, since code-mode has no durable-HITL path to suspend mid-script.
-*
-* Returns `[]` (registering nothing) when no real tool is exposable.
-*/
-function registerCodeMode(registry, quietExecutor, reservedNames, getRunCapability) {
-	if (registry.get(CODE_EXECUTE_NAME) !== void 0) return [];
-	const codeTools = registry.list().filter((entry) => !reservedNames.has(entry.name) && !isApprovalGated(entry));
-	if (codeTools.length === 0) return [];
-	const approvalGatedTools = registry.list().filter((entry) => !reservedNames.has(entry.name) && isApprovalGated(entry)).map((entry) => entry.name);
-	const approvalGatedSet = new Set(approvalGatedTools);
-	const allowedTools = [...codeTools.map((entry) => entry.name), ...approvalGatedTools];
-	const allowedSet = new Set(codeTools.map((entry) => entry.name));
-	const projection = projectToolApi(codeTools.filter((entry) => entry.__effectiveDeferLoading !== true));
-	const executeTool = async (call, ctx) => {
-		if (approvalGatedSet.has(call.name)) throw new Error(`${call.name} requires human approval and cannot run inside code_execute - call it directly as a standalone tool call so the run can suspend for the approval.`);
-		const runCapability = getRunCapability?.();
-		const { outcome } = await quietExecutor.executeOne({
-			call: {
-				toolCallId: newId("codecall"),
-				toolName: call.name,
-				args: call.args
-			},
-			runContext: ctx.runContext,
-			stepNumber: ctx.runContext.stepNumber,
-			...runCapability !== void 0 ? { capability: runCapability } : {}
-		});
-		if ("kind" in outcome) throw new Error(`${call.name}: ${outcome.message}`);
-		return outcome.output;
-	};
-	const codeSearch = createCodeSearchTool({
-		projection,
-		approvalGatedTools,
-		searchDeferred: async (query, k) => (await registry.searchDeferred(query, k)).filter((match) => allowedSet.has(match.name))
-	});
-	const codeExecute = createCodeExecuteTool({
-		projection,
-		allowedTools,
-		executeTool,
-		approvalGatedTools
-	});
-	registry.register(codeSearch, {
-		kind: "built-in",
-		subsystem: "code-mode"
-	});
-	registry.register(codeExecute, {
-		kind: "built-in",
-		subsystem: "code-mode"
-	});
-	return [codeSearch, codeExecute];
-}
-/**
-* Fold a completed `tool_search` result into the per-run promotion set:
-* every matched tool name becomes advertised (and thus callable) on the
-* next step. Tolerant of unexpected shapes (e.g. a user-shadowed
-* `tool_search`) - only string `name`s inside a `matches` array promote.
-*/
-function recordToolSearchPromotions(output, promoted) {
-	if (typeof output !== "object" || output === null) return;
-	const matches = output.matches;
-	if (!Array.isArray(matches)) return;
-	for (const match of matches) {
-		const name = match?.name;
-		if (typeof name === "string") promoted.add(name);
-	}
-}
-function isModelHintLike(value) {
-	return value === "fast" || value === "balanced" || value === "smart";
-}
-function isModelSpecLike(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const v = value;
-	if (typeof v.modelId === "string" && typeof v.name === "string") return true;
-	if (typeof v.provider === "object" && v.provider !== null && typeof v.model === "string") return true;
-	return false;
-}
-function validatePreferredModel(value) {
-	if (value === void 0) return;
-	if (isModelHintLike(value)) return;
-	if (isModelSpecLike(value)) return;
-	throw new InvalidPreferredModelError(value);
-}
-function isMessageObject(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const role = value.role;
-	return role === "system" || role === "user" || role === "assistant" || role === "tool";
-}
-function isRunStateObject(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const v = value;
-	return typeof v.id === "string" && typeof v.agentId === "string" && Array.isArray(v.messages) && Array.isArray(v.steps);
-}
-function asMessages(input) {
-	if (typeof input === "string") return { seed: [{
-		role: "user",
-		content: input
-	}] };
-	if (Array.isArray(input)) return { seed: [...input] };
-	if (isMessageObject(input)) return { seed: [input] };
-	if (isRunStateObject(input)) return {
-		seed: [],
-		resumed: input
-	};
-	throw new InvalidAgentConfigError(`unrecognized AgentInput shape`);
-}
-/**
-* Strip a single Markdown code fence around a JSON payload (AG-3).
-* Models often wrap structured output in ```json fences even when told
-* not to. ReDoS-safe: the info string is matched with `[^\n]*`.
-*/
-function stripJsonFence(text) {
-	const trimmed = text.trim();
-	return /^```[^\n]*\n([\s\S]*?)\n?```$/.exec(trimmed)?.[1] ?? trimmed;
-}
-/**
-* The AG-3 fallback instruction: one trailing system message that
-* pins JSON-only output and embeds the wire schema / description.
-* This is the documented structured-output contract for adapters that
-* do not yet consume `ProviderRequest.outputType` natively (PS-24).
-*/
-function buildStructuredInstruction(spec) {
-	const parts = ["Respond with a single valid JSON value only - no prose, no Markdown code fences."];
-	if (spec.description !== void 0 && spec.description.length > 0) parts.push(spec.description);
-	if (spec.jsonSchema !== void 0) parts.push(`The JSON MUST conform to this JSON Schema:\n${JSON.stringify(spec.jsonSchema)}`);
-	return parts.join("\n");
-}
-/** Most-recent user-role text in `messages` (for context-engine auto-recall). */
-function lastUserText(messages) {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const m = messages[i];
-		if (m?.role !== "user") continue;
-		if (typeof m.content === "string") return m.content;
-		const text = m.content.filter((p) => p.type === "text").map((p) => p.text).join(" ");
-		return text.length > 0 ? text : void 0;
-	}
-}
-/**
-* AG-21: classify a **thrown** provider error into a {@link ProviderErrorKind}
-* so the fallback chain can act on it, instead of flattening every exception to
-* `'unknown'` (which is always fallback-ineligible). Structural - reads the
-* `kind` carried by `@graphorin/provider`'s `GraphorinProviderError` subclasses
-* without importing them, keeping the agent decoupled from the provider package.
-*/
-/** Canonical `ProviderErrorKind` values honoured off a thrown error's `errorKind`. */
-const CANONICAL_PROVIDER_ERROR_KINDS = new Set([
-	"rate-limit",
-	"capacity",
-	"context-length",
-	"transient",
-	"invalid-request",
-	"unauthorized",
-	"content-filter"
-]);
-function classifyThrownProviderErrorKind(cause) {
-	if (typeof cause === "object" && cause !== null) {
-		const errorKind = cause.errorKind;
-		if (typeof errorKind === "string" && CANONICAL_PROVIDER_ERROR_KINDS.has(errorKind)) return errorKind;
-		switch (cause.kind) {
-			case "rate-limit-exceeded": return "rate-limit";
-		}
-	}
-	return "unknown";
-}
-/** WARN-once keys for schemas the projection cannot read (per process). */
-const unprojectableSchemaWarned = /* @__PURE__ */ new Set();
-/**
-* Resolve a tool's declared schema - plain Zod (v3/v4), `toJSON()`-bearing,
-* or already-JSON-Schema data - to a JSON Schema record via the shared
-* projection (tools-01). Pre-fix this only honoured `toJSON()` and passed
-* everything else through verbatim, so every plain-Zod tool serialised as
-* `{"_def":...}` internals on OpenAI-shaped/Ollama/vercel wire bodies.
-* `undefined` when nothing usable can be projected (caller substitutes a
-* permissive `{}`), with a WARN so the degradation is never silent.
-*/
-function projectSchema(raw, toolName, slot) {
-	return projectSchemaToJsonSchema(raw, { onUnsupported: (detail) => {
-		const key = `${toolName}:${slot}:${detail}`;
-		if (unprojectableSchemaWarned.has(key)) return;
-		unprojectableSchemaWarned.add(key);
-		console.warn(`[graphorin/agent] tool '${toolName}' ${slot} schema: '${detail}' cannot be projected to JSON Schema - that fragment degrades to a permissive {} on the provider wire body.`);
-	} });
-}
-function toolToDefinition(tool) {
-	const ts = tool;
-	const inputSchema = projectSchema(ts.inputSchema, tool.name, "input") ?? {};
-	const outputSchema = projectSchema(ts.outputSchema, tool.name, "output");
-	const examples = renderToolExamples(tool);
-	return {
-		name: tool.name,
-		description: tool.description,
-		inputSchema,
-		...outputSchema !== void 0 ? { outputSchema } : {},
-		...examples !== void 0 ? { examples } : {}
-	};
-}
-/**
-* Project a tool's worked `examples` onto the provider wire contract
-* (WI-06 / P2-3). Examples are rendered only when the tool eagerly
-* renders them: the registry resolves the `defer_loading` auto-rule into
-* `examplesEagerlyRendered`, so a deferred tool resolves to `false` and is
-* skipped (its examples stay out of context even once `tool_search`
-* promotes it). `undefined` - the "runtime decides" case for a plain
-* eager tool - renders, since the tool is already advertised this step.
-*
-* Bounded to ≤5 to honour the `ToolExample` `[1,5]` contract even when a
-* tool slipped past the registry's overflow WARN (which does not truncate).
-*/
-function renderToolExamples(tool) {
-	const examples = tool.examples;
-	if (examples === void 0 || examples.length === 0) return void 0;
-	if (tool.examplesEagerlyRendered === false) return void 0;
-	return examples.slice(0, 5).map((ex) => ({
-		input: ex.input,
-		output: ex.output,
-		...ex.comment !== void 0 ? { comment: ex.comment } : {}
-	}));
-}
-const PASSTHROUGH_SCHEMA = {
-	parse: (value) => value,
-	safeParse: (value) => ({
-		success: true,
-		data: value
-	}),
-	toJSON: () => ({ type: "object" })
-};
-function isDescribedFilter(value) {
-	return typeof value === "function" && "descriptor" in value && typeof value.descriptor === "object";
-}
-function buildHandoffTool(target) {
-	const cfg = target.config;
-	return {
-		name: `${HANDOFF_TOOL_PREFIX}${cfg.name}`,
-		description: `Hand off control to agent '${cfg.name}'.`,
-		inputSchema: PASSTHROUGH_SCHEMA,
-		sideEffectClass: "pure",
-		async execute() {
-			return `[handoff: ${cfg.name}]`;
-		}
-	};
-}
-function specToProvider(spec) {
-	if ("provider" in spec) return spec.provider;
-	return spec;
-}
-function handleProviderEvent(ev, state) {
-	switch (ev.type) {
-		case "stream-start": return {};
-		case "reasoning-delta":
-			state.reasoningBuffer += ev.delta;
-			return { emit: {
-				type: "reasoning.delta",
-				delta: ev.delta
-			} };
-		case "text-delta":
-			state.textBuffer += ev.delta;
-			return { emit: {
-				type: "text.delta",
-				delta: ev.delta
-			} };
-		case "tool-call-start":
-			state.calls.set(ev.toolCallId, {
-				toolCallId: ev.toolCallId,
-				toolName: ev.toolName,
-				argsBuffer: ""
-			});
-			return { emit: {
-				type: "tool.call.start",
-				toolCallId: ev.toolCallId,
-				toolName: ev.toolName,
-				args: void 0
-			} };
-		case "tool-call-input-delta": {
-			const acc = state.calls.get(ev.toolCallId);
-			if (acc !== void 0) acc.argsBuffer += ev.argsDelta;
-			return { emit: {
-				type: "tool.call.delta",
-				toolCallId: ev.toolCallId,
-				argsDelta: ev.argsDelta
-			} };
-		}
-		case "tool-call-end": {
-			const acc = state.calls.get(ev.toolCallId);
-			if (acc === void 0) {
-				process.stderr.write(`[graphorin/agent] dropped tool-call-end '${ev.toolCallId}' with no matching tool-call-start.\n`);
-				return {};
-			}
-			state.finalCalls.push({
-				toolCallId: ev.toolCallId,
-				toolName: acc.toolName,
-				args: ev.finalArgs
-			});
-			return { emit: {
-				type: "tool.call.end",
-				toolCallId: ev.toolCallId,
-				finalArgs: ev.finalArgs
-			} };
-		}
-		case "file": return { emit: {
-			type: "file.generated",
-			mimeType: ev.mimeType,
-			data: ev.data
-		} };
-		case "source": return { emit: {
-			type: "source.cited",
-			uri: ev.uri,
-			...ev.title !== void 0 ? { title: ev.title } : {}
-		} };
-		case "finish": return {
-			usage: ev.usage,
-			finished: true
-		};
-		case "error": return { providerError: ev.error };
-		default: return {};
-	}
-}
-/**
-* Resolve the effective {@link ReasoningRetention} for a step. The
-* agent-level setting wins over the provider-level default; when
-* neither is supplied, the provider's `reasoningContract`
-* capability drives the default per RB-42 / suggested DEC-158.
-*/
-function effectiveReasoningRetention(agentOverride, provider) {
-	if (agentOverride !== void 0) return agentOverride;
-	switch (provider.capabilities.reasoningContract) {
-		case "round-trip-required": return "pass-through-claude";
-		case "optional": return "pass-through-all";
-		case "hidden": return "strip";
-		default: return "strip";
-	}
-}
-/**
-* Build the assistant message that the runtime appends to the
-* message buffer after a successful provider call. When the
-* effective {@link ReasoningRetention} is not `'strip'`, the
-* assembled `reasoning` content parts ride along on `content` so
-* the next provider call honours the wire-correct round-trip
-* contract per RB-42.
-*/
-function buildAssistantMessage(text, reasoningParts, toolCalls, agentId, retention) {
-	if (retention !== "strip" && reasoningParts.length > 0) {
-		const parts = [...reasoningParts];
-		if (text.length > 0) parts.push({
-			type: "text",
-			text
-		});
-		return {
-			role: "assistant",
-			content: parts,
-			...toolCalls.length > 0 ? { toolCalls } : {},
-			agentId
-		};
-	}
-	return {
-		role: "assistant",
-		content: text,
-		...toolCalls.length > 0 ? { toolCalls } : {},
-		agentId
-	};
-}
-/**
-* Strip every {@link ReasoningContent} part from each message in
-* the supplied list. Used at the swap point when `prepareStep`
-* downgrades the provider's `reasoningContract` mid-run.
-*/
-function stripReasoningFromMessages(messages) {
-	let stripped = 0;
-	for (let i = 0; i < messages.length; i++) {
-		const msg = messages[i];
-		if (msg === void 0) continue;
-		if (msg.role === "system" || msg.role === "tool") continue;
-		if (typeof msg.content === "string") continue;
-		const filtered = msg.content.filter((p) => p.type !== "reasoning");
-		if (filtered.length === msg.content.length) continue;
-		stripped += msg.content.length - filtered.length;
-		if (msg.role === "assistant") messages[i] = {
-			...msg,
-			content: filtered
-		};
-		else messages[i] = {
-			...msg,
-			content: filtered
-		};
-	}
-	return { stripped };
-}
-/**
-* Count the leading contiguous run of `system` messages in the initial
-* buffer - the trusted, KV-cache-stable instruction prefix. Captured
-* once at run start (WI-09 / P1-1): auto-compaction summarises only the
-* messages after this prefix, so the prefix stays byte-identical across
-* every step (the provider's cache breakpoint is real) and a long run
-* never re-pays for the system prompt.
-*
-* The length is fixed for the run rather than re-derived per compaction
-* on purpose: each compaction inserts its summary as a `system` message
-* right after the prefix, so re-scanning the leading run would absorb
-* that summary into the prefix and shield it from the next compaction -
-* summaries would stack unbounded. Pinning the original length keeps
-* each prior summary inside the compactable body, where the next pass
-* folds it into a fresh summary-of-summary.
-*/
-/**
-* Marker prefix stamped on every compaction summary (see the memory
-* package's summary template). context-engine-05: the prefix scan must
-* stop at it - after a compact-then-suspend cycle the summary is a
-* SYSTEM message sitting right after the true prefix, and counting it
-* in would pin it (and every later summary) outside the compactable
-* window forever, growing the uncompactable prefix by one summary per
-* cycle.
-*/
-const COMPACTION_SUMMARY_MARKER = "<graphorin_compaction_summary";
-function countLeadingSystemMessages(messages) {
-	let i = 0;
-	while (i < messages.length) {
-		const msg = messages[i];
-		if (msg?.role !== "system") break;
-		if (typeof msg.content === "string" && msg.content.startsWith(COMPACTION_SUMMARY_MARKER)) break;
-		i += 1;
-	}
-	return i;
-}
-/**
-* Immutable usage sum. Optional token fields (reasoning + prompt-cache
-* legs, core-provider-02) appear in the result only when at least one
-* side carries them, so pre-cache serialized shapes stay byte-identical.
-*/
-/**
-* D6: assemble the per-step request messages. Trailing, request-only
-* additions ride the LAST prompt-cache anchor and never touch the shared
-* `messages` buffer or the persisted RunState: the structured-output
-* instruction (AG-3) and the attention-recitation plan block are both
-* appended here, in that order, so the stable prompt prefix is unchanged
-* and only the small trailing tail is re-sent each step.
-*/
-function buildStepMessages(messages, structuredInstruction, todos) {
-	const out = [...messages];
-	if (structuredInstruction !== void 0) out.push({
-		role: "system",
-		content: structuredInstruction
-	});
-	const recitation = renderPlanRecitation(todos);
-	if (recitation !== null) out.push({
-		role: "system",
-		content: recitation
-	});
-	return out;
-}
-function addUsage(a, b) {
-	const optional = (x, y) => x === void 0 && y === void 0 ? void 0 : (x ?? 0) + (y ?? 0);
-	const reasoningTokens = optional(a.reasoningTokens, b.reasoningTokens);
-	const cachedReadTokens = optional(a.cachedReadTokens, b.cachedReadTokens);
-	const cacheWriteTokens = optional(a.cacheWriteTokens, b.cacheWriteTokens);
-	return {
-		promptTokens: a.promptTokens + b.promptTokens,
-		completionTokens: a.completionTokens + b.completionTokens,
-		totalTokens: a.totalTokens + b.totalTokens,
-		...reasoningTokens !== void 0 ? { reasoningTokens } : {},
-		...cachedReadTokens !== void 0 ? { cachedReadTokens } : {},
-		...cacheWriteTokens !== void 0 ? { cacheWriteTokens } : {}
-	};
-}
-/**
-* C3: render a ToolError for the model. The first line keeps the
-* long-standing `Error: <message>` shape; a bracketed second line carries
-* the typed kind + the recovery envelope, which is what actually changes
-* model behaviour after a failure (retry vs. fix args vs. give up).
-*/
-function renderToolErrorMessage(error) {
-	const parts = [`kind: ${error.kind}`];
-	if (error.recoverable !== void 0) parts.push(error.recoverable ? "recoverable: yes" : "recoverable: no");
-	if (error.recoveryHint !== void 0) parts.push(`suggested action: ${error.recoveryHint}`);
-	if (error.hint !== void 0) parts.push(error.hint);
-	return `Error: ${error.message}\n[${parts.join("; ")}]`;
-}
-/** In-place variant of {@link addUsage} for mutable accumulators. */
-function accumulateUsage(target, delta) {
-	target.promptTokens += delta.promptTokens;
-	target.completionTokens += delta.completionTokens;
-	target.totalTokens += delta.totalTokens;
-	if (delta.reasoningTokens !== void 0) target.reasoningTokens = (target.reasoningTokens ?? 0) + delta.reasoningTokens;
-	if (delta.cachedReadTokens !== void 0) target.cachedReadTokens = (target.cachedReadTokens ?? 0) + delta.cachedReadTokens;
-	if (delta.cacheWriteTokens !== void 0) target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + delta.cacheWriteTokens;
-}
-/**
 * Build a fresh {@link Agent} from the supplied configuration.
 *
 * @stable
@@ -641,10 +50,12 @@ function createAgent(config) {
 		const subAgent = isWrappedHandoff ? entry.target : entry;
 		const userFilter = isWrappedHandoff ? entry.inputFilter : void 0;
 		const filter = isDescribedFilter(userFilter) ? userFilter : void 0;
+		const forwardEvents = isWrappedHandoff ? entry.forwardEvents : void 0;
 		const toolName = `${HANDOFF_TOOL_PREFIX}${subAgent.config.name}`;
 		handoffMap.set(toolName, {
 			agent: subAgent,
-			filter
+			filter,
+			forwardEvents
 		});
 	}
 	let pendingSteer = [];
@@ -657,91 +68,18 @@ function createAgent(config) {
 	let runInFlight = false;
 	const externalEventQueue = [];
 	const pendingManualCompacts = [];
-	const noopCompactionResult = (skippedReason) => ({
-		beforeTokens: 0,
-		afterTokens: 0,
-		summaryTokens: 0,
-		durationMs: 0,
-		hooksFiredCount: 0,
-		summary: "",
-		applied: false,
-		skippedReason
-	});
 	const memory = config.memory;
 	const progressIO = createProgressIO({ ...config.sensitivity !== void 0 ? { defaultSensitivity: config.sensitivity } : {} });
-	const toolRegistry = buildToolRegistry({
-		...config.tools !== void 0 ? { tools: config.tools } : {},
-		...config.skills !== void 0 ? { skills: config.skills } : {}
-	}).registry;
-	registerToolSearch(toolRegistry, config.toolPromotion === "run-boundary" ? "next-run" : "next-step");
-	if (config.plan === true && toolRegistry.get(PLAN_TOOL_NAME) === void 0) toolRegistry.register(createPlanTool((todos) => {
-		if (activeRunState !== void 0) activeRunState.todos = todos;
-	}), {
-		kind: "built-in",
-		subsystem: "planning"
-	});
-	const spillWriter = createDefaultSpillWriter();
-	const fileResultReader = createFileResultReader({ artifactRoot: spillWriter.artifactRoot });
-	const externalResultReaders = config.resultReaders ?? [];
-	const resultReader = externalResultReaders.length === 0 ? fileResultReader : composeResultReaders([fileResultReader, ...externalResultReaders]);
-	registerReadResult(toolRegistry, resultReader, { force: externalResultReaders.length > 0 });
-	let activeExecutorBridge;
-	const toolApprovalGate = { request: async () => ({ granted: true }) };
-	const toolSecretResolver = buildSecretResolver();
-	const toolTokenCounter = buildToolTokenCounter();
-	const memoryGuardWiring = buildMemoryGuard(memory, memory === void 0 ? {} : { regionReader: createMemoryRegionReader(["working"], async (region) => {
-		if (region !== "working") return "";
-		const scope = {
-			userId: activeRunState?.userId ?? agentId,
-			...activeRunState?.sessionId !== void 0 ? { sessionId: activeRunState.sessionId } : {},
-			agentId
-		};
-		const working = memory.working;
-		if (working?.compile === void 0) return "";
-		try {
-			return await working.compile(scope, agentId);
-		} catch {
-			return "";
-		}
-	}) });
-	const toolMemoryGuardFactory = memoryGuardWiring.memoryGuardFactory;
-	if (memory === void 0) {
-		const guarded = (config.tools ?? []).filter((t) => t.memoryGuardTier !== void 0);
-		if (guarded.length > 0) console.warn(`[graphorin/agent] ${guarded.length} tool(s) declare memoryGuardTier but no memory is wired - the DEC-153 snapshot/verify guard is skipped (SDF-1). Wire \`memory\` to activate it.`);
-	}
-	const toolDataFlowGuard = config.dataFlowPolicy !== void 0 && config.dataFlowPolicy.mode !== "off" ? buildDataFlowGuard(config.dataFlowPolicy) : void 0;
-	const { guard: toolArgumentPolicyGuard, capabilityFloor: ruleOfTwoCapabilityFloor } = buildToolArgumentPolicy(config.toolPolicy, config.ruleOfTwo);
-	const toolStreamingSink = (event) => activeExecutorBridge?.sink(event);
-	const makeToolExecutor = (registry, opts) => createToolExecutor({
-		registry,
-		approvalGate: toolApprovalGate,
-		secretResolver: toolSecretResolver,
-		tokenCounter: toolTokenCounter,
-		memoryGuardFactory: toolMemoryGuardFactory,
-		...memoryGuardWiring.memoryRegionReader !== void 0 ? { memoryRegionReader: memoryGuardWiring.memoryRegionReader } : {},
-		spill: spillWriter,
-		...toolDataFlowGuard !== void 0 ? { dataFlowGuard: toolDataFlowGuard } : {},
-		...toolArgumentPolicyGuard !== void 0 ? { argumentPolicy: toolArgumentPolicyGuard } : {},
-		...opts?.quiet === true ? {} : { streamingSink: toolStreamingSink },
-		...config.maxParallelTools !== void 0 ? { maxParallelTools: config.maxParallelTools } : {},
-		...config.toolRetry !== void 0 ? { retry: config.toolRetry } : {}
+	const executorBridgeSlot = { current: void 0 };
+	const { toolRegistry, spillWriter, resultReader, makeToolExecutor, toolExecutor, toolDataFlowGuard, ruleOfTwoCapabilityFloor, isCodeMode, codeModeAdvertised } = wireToolExecution({
+		config,
+		memory,
+		agentId,
+		handoffToolNames: handoffMap.keys(),
+		getActiveRunState: () => activeRunState,
+		getActiveRunCapability: () => activeRunCapability,
+		executorBridgeSlot
 	});
-	const toolExecutor = makeToolExecutor(toolRegistry);
-	const isCodeMode = config.toolInvocation === "code-mode";
-	let codeModeAdvertised = [];
-	if (isCodeMode) {
-		const reserved = new Set([
-			CODE_EXECUTE_NAME,
-			CODE_SEARCH_NAME,
-			TOOL_SEARCH_NAME,
-			READ_RESULT_NAME,
-			...handoffMap.keys()
-		]);
-		const metas = registerCodeMode(toolRegistry, makeToolExecutor(toolRegistry, { quiet: true }), reserved, () => activeRunCapability);
-		registerReadResult(toolRegistry, resultReader);
-		const readResult = toolRegistry.get(READ_RESULT_NAME);
-		codeModeAdvertised = [...metas, ...readResult !== void 0 ? [readResult] : []];
-	}
 	const causalityMonitor = config.causalityMonitor ? new CausalityMonitor(config.causalityMonitor) : void 0;
 	/**
 	* AG-11: one in-flight run per Agent instance. `steer` / `followUp` /
@@ -783,17 +121,14 @@ function createAgent(config) {
 		if (parentSignal !== void 0) if (parentSignal.aborted) localCtl.abort();
 		else parentSignal.addEventListener("abort", onParentAbort);
 		const usageAcc = new InMemoryUsageAccumulator();
-		const state = resumed ? resumed : createInitialRunState({
-			id: newId("run"),
+		const { state, promotedDeferred, runStartPromotions } = initializeRunState({
+			config,
 			agentId,
 			sessionId,
-			...userId !== void 0 ? { userId } : {}
-		});
+			userId,
+			toolDataFlowGuard
+		}, resumed);
 		activeRunState = state;
-		if (resumed && state.taintSummary !== void 0) toolDataFlowGuard?.seedLedger(state.id, state.taintSummary);
-		const promotedDeferred = /* @__PURE__ */ new Set();
-		if (resumed && state.promotedTools !== void 0) for (const name of state.promotedTools) promotedDeferred.add(name);
-		const runStartPromotions = config.toolPromotion === "run-boundary" ? new Set(promotedDeferred) : void 0;
 		async function* finishRun(s, snapshot) {
 			const taintSnap = toolDataFlowGuard?.snapshotLedger(s.id);
 			if (taintSnap !== void 0) s.taintSummary = taintSnap;
@@ -801,49 +136,22 @@ function createAgent(config) {
 			return yield* finishRunBase(s, snapshot);
 		}
 		const messages = resumed ? [...state.messages] : [];
-		if (!resumed) {
-			const instructionsRaw = config.instructions;
-			let instructionsText;
-			if (typeof instructionsRaw === "string") instructionsText = instructionsRaw;
-			else instructionsText = await instructionsRaw({
-				runId: state.id,
-				sessionId,
-				...userId !== void 0 ? { userId } : {},
-				agentId,
-				deps: options.deps ?? config.deps,
-				tracer,
-				signal,
-				usage: usageAcc,
-				stepNumber: 0,
-				messages,
-				state
-			});
-			let systemPrompt = instructionsText;
-			if (config.autoAssembleContext === true && memory !== void 0) {
-				const lastUser = lastUserText(seed);
-				systemPrompt = (await memory.contextEngine.assemble(memory, {
-					scope: {
-						userId: userId ?? agentId,
-						sessionId,
-						agentId
-					},
-					agentId,
-					sessionId,
-					runId: state.id,
-					...instructionsText.length > 0 ? { agentInstructions: instructionsText } : {},
-					...lastUser !== void 0 ? { lastUserMessage: lastUser } : {}
-				})).systemMessage.content;
-			}
-			if (systemPrompt.length > 0) messages.push({
-				role: "system",
-				content: systemPrompt
-			});
-			messages.push(...seed);
-			for (const m of messages) state.messages.push(m);
-		}
+		if (!resumed) await seedInitialMessages({
+			config,
+			options,
+			memory,
+			agentId,
+			sessionId,
+			userId,
+			tracer,
+			signal,
+			usageAcc,
+			state
+		}, messages, seed);
 		const finalSnapshot = { output: "" };
 		const runSpan = tracer.startSpan({
 			type: "agent.run",
+			...options.parentSpan !== void 0 ? { parent: options.parentSpan } : {},
 			attrs: {
 				"gen_ai.operation.name": "invoke_agent",
 				"gen_ai.agent.id": agentId,
@@ -860,94 +168,22 @@ function createAgent(config) {
 			agentId
 		};
 		const inputGuards = config.guardrails?.input;
-		if (!resumed && inputGuards !== void 0 && inputGuards.length > 0) for (let i = 0; i < messages.length; i++) {
-			const msg = messages[i];
-			if (msg === void 0 || msg.role !== "user" || typeof msg.content !== "string") continue;
-			const composed = await composeGuardrails(inputGuards, msg.content, {
-				stage: "input",
-				runId: state.id,
+		if (!resumed && inputGuards !== void 0 && inputGuards.length > 0) {
+			if (yield* screenInputGuardrails({
+				state,
+				messages,
 				sessionId,
 				agentId
-			});
-			if (!composed.ok) {
-				yield {
-					type: "guardrail.tripped",
-					guardrailName: composed.name,
-					phase: "input",
-					reason: composed.message
-				};
-				const message = `input guardrail '${composed.name}' blocked the run: ${composed.message}`;
-				yield {
-					type: "agent.error",
-					error: {
-						message,
-						code: "guardrail-blocked"
-					}
-				};
-				state.status = "failed";
-				state.error = {
-					message,
-					code: "guardrail-blocked"
-				};
-				return yield* finishRun(state, finalSnapshot);
-			}
-			if (composed.value !== msg.content) {
-				const rewritten = {
-					...msg,
-					content: composed.value
-				};
-				const stateIdx = state.messages.indexOf(msg);
-				messages[i] = rewritten;
-				if (stateIdx !== -1) state.messages[stateIdx] = rewritten;
-			}
+			}, inputGuards)) return yield* finishRun(state, finalSnapshot);
 		}
 		const structuredInstruction = config.outputType?.kind === "structured" ? buildStructuredInstruction(config.outputType) : void 0;
 		const resumedApprovedCalls = [];
 		const grantedApprovals = [];
-		const journaledCallIds = /* @__PURE__ */ new Set();
-		for (const step of state.steps) for (const completed of step.toolCalls) journaledCallIds.add(completed.call.toolCallId);
-		if (resumed && options.directive?.approvals !== void 0 && state.pendingApprovals.length > 0) {
-			const decisions = new Map(options.directive.approvals.map((d) => [d.toolCallId, d]));
-			const stillPending = [];
-			for (const approval of state.pendingApprovals) {
-				const decision = decisions.get(approval.toolCallId);
-				if (decision === void 0) {
-					stillPending.push(approval);
-					continue;
-				}
-				if (decision.granted) {
-					yield {
-						type: "tool.approval.granted",
-						toolCallId: approval.toolCallId
-					};
-					if (journaledCallIds.has(approval.toolCallId) && messages.some((m) => m.role === "tool" && m.toolCallId === approval.toolCallId)) continue;
-					resumedApprovedCalls.push({
-						toolCallId: approval.toolCallId,
-						toolName: approval.toolName,
-						args: approval.args
-					});
-					grantedApprovals.push(approval);
-				} else {
-					yield {
-						type: "tool.approval.denied",
-						toolCallId: approval.toolCallId,
-						...decision.reason !== void 0 ? { reason: decision.reason } : {}
-					};
-					messages.push({
-						role: "tool",
-						toolCallId: approval.toolCallId,
-						content: `Error: tool approval denied${decision.reason ? `: ${decision.reason}` : ""}`
-					});
-					state.messages.push({
-						role: "tool",
-						toolCallId: approval.toolCallId,
-						content: `Error: tool approval denied${decision.reason ? `: ${decision.reason}` : ""}`
-					});
-				}
-			}
-			state.pendingApprovals.splice(0, state.pendingApprovals.length, ...stillPending);
-			if (stillPending.length === 0) state.status = "running";
-		}
+		const subRunDecisions = /* @__PURE__ */ new Map();
+		if (resumed && options.directive?.approvals !== void 0 && state.pendingApprovals.length > 0) yield* processResumeDirective({
+			state,
+			messages
+		}, options.directive.approvals, resumedApprovedCalls, grantedApprovals, subRunDecisions);
 		const systemPrefixLength = countLeadingSystemMessages(messages);
 		const runContextBase = {
 			runId: state.id,
@@ -962,378 +198,50 @@ function createAgent(config) {
 			messages,
 			state
 		};
+		const runEnv = {
+			config,
+			options,
+			memory,
+			state,
+			messages,
+			sessionId,
+			agentId,
+			userId,
+			signal,
+			usageAcc,
+			stopWhen,
+			fallbackPolicy,
+			structuredInstruction,
+			systemPrefixLength,
+			runContextBase,
+			handoffMap,
+			handoffNames: Array.from(handoffMap.keys()),
+			isCodeMode,
+			toolRegistry,
+			toolExecutor,
+			makeToolExecutor,
+			resultReader,
+			codeModeAdvertised,
+			causalityMonitor,
+			toolDataFlowGuard,
+			promotedDeferred,
+			runStartPromotions,
+			activeRunCapability,
+			executorBridgeSlot,
+			pendingManualCompacts,
+			getPendingAbort: () => pendingAbort,
+			getCurrentStepSpan: () => currentStepSpan,
+			getActiveTodos: () => activeRunState?.todos,
+			tryEmergencyCompact: () => tryEmergencyCompact(runEnv),
+			dispatchBatch: (calls, executor, runContext, stepNum, dispatchOpts) => dispatchToolBatch(runEnv, calls, executor, runContext, stepNum, dispatchOpts)
+		};
 		if (resumed && state.status === "failed") return yield* finishRun(state, finalSnapshot);
-		if (resumed && resumedApprovedCalls.length > 0) {
-			if (config.checkpointStore !== void 0) {
-				const prevStatus = state.status;
-				state.status = "awaiting_approval";
-				state.pendingApprovals.unshift(...grantedApprovals);
-				const intentState = serializeRunState(state, { stripTracingApiKey: true });
-				state.pendingApprovals.splice(0, grantedApprovals.length);
-				state.status = prevStatus;
-				await config.checkpointStore.put(state.id, "agent", {
-					id: state.id,
-					threadId: state.id,
-					namespace: "agent",
-					state: intentState,
-					channelVersions: {},
-					stepNumber: 0,
-					createdAt: (/* @__PURE__ */ new Date()).toISOString()
-				}, {
-					source: "sync",
-					status: "suspended",
-					nodeName: "agent.resume.intent"
-				});
-			}
-			state.steps.push({
-				stepNumber: 0,
-				startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-				usage: zeroUsage(),
-				toolCalls: [],
-				agentId: state.currentAgentId
-			});
-			yield* dispatchBatch(resumedApprovedCalls, toolExecutor, {
-				...runContextBase,
-				stepNumber: 0,
-				messages
-			}, 0, { disableRepair: true });
-			if (config.checkpointStore !== void 0) await config.checkpointStore.put(state.id, "agent", {
-				id: state.id,
-				threadId: state.id,
-				namespace: "agent",
-				state: serializeRunState(state, { stripTracingApiKey: true }),
-				channelVersions: {},
-				stepNumber: 0,
-				createdAt: (/* @__PURE__ */ new Date()).toISOString()
-			}, {
-				source: "sync",
-				status: state.status === "awaiting_approval" ? "suspended" : "running",
-				nodeName: "agent.resume.dispatched"
-			});
-		}
-		if (resumed && state.status === "awaiting_approval") return yield* finishRun(state, finalSnapshot);
-		/**
-		* Dispatch a batch of (non-handoff) tool calls through the
-		* {@link ToolExecutor} and surface the results as `AgentEvent`s.
-		*
-		* The agent owns the `tool.execute.start` / `.end` / `.error`
-		* lifecycle (derived deterministically from the returned
-		* {@link CompletedToolCall} outcomes) so every outcome kind -
-		* success, unknown-tool, invalid-input, sanitization-blocked,
-		* execution error - yields a consistent event and tool message,
-		* preserving the pre-WI-03 stream shape (R10). The executor's
-		* genuinely-live streaming events (`tool.execute.progress` /
-		* `.partial`, emitted only by streaming-hint tools) are bridged
-		* through Adapter E while the batch runs and are purely additive.
-		*
-		* Parallelism (WI-04): the executor runs independent calls in this
-		* batch concurrently, bounded by `maxParallelTools`. `tool.execute.start`
-		* is emitted up-front in call order and `.end` / `.error` after the
-		* batch settles, also in call order - so result mapping and tool-message
-		* history are deterministic regardless of which call finishes first,
-		* while `.progress` / `.partial` events for concurrent calls interleave
-		* (keyed by `toolCallId`). Tools declaring `executionMode: 'sequential'`
-		* are serialised by the executor and never overlap.
-		*/
-		async function* dispatchBatch(calls, executor, runContext, stepNum, dispatchOpts = {}) {
-			if (calls.length === 0) return;
-			for (const call of calls) yield {
-				type: "tool.execute.start",
-				toolCallId: call.toolCallId
-			};
-			const bridge = createExecutorEventBridge();
-			activeExecutorBridge = bridge;
-			const resultsPromise = executor.executeBatch({
-				calls,
-				runContext,
-				stepNumber: stepNum,
-				...dispatchOpts.disableRepair !== void 0 ? { disableRepair: dispatchOpts.disableRepair } : {},
-				...activeRunCapability !== void 0 ? { capability: activeRunCapability } : {}
-			});
-			const closeOnSettle = resultsPromise.then(() => bridge.close(), () => bridge.close());
-			for await (const event of bridge.drain()) if (event.type === "tool.execute.progress" || event.type === "tool.execute.partial") yield event;
-			await closeOnSettle;
-			activeExecutorBridge = void 0;
-			const completed = await resultsPromise;
-			const byCallId = new Map(completed.map((c) => [c.outcome.toolCallId, c]));
-			const stepEntry = state.steps[state.steps.length - 1];
-			for (const call of calls) {
-				const result = byCallId.get(call.toolCallId);
-				if (result === void 0) continue;
-				if (stepEntry !== void 0) stepEntry.toolCalls.push(result);
-				const outcome = result.outcome;
-				if ("kind" in outcome) {
-					yield {
-						type: "tool.execute.error",
-						toolCallId: call.toolCallId,
-						error: outcome
-					};
-					const text = renderToolErrorMessage(outcome);
-					messages.push({
-						role: "tool",
-						toolCallId: call.toolCallId,
-						content: text
-					});
-					state.messages.push({
-						role: "tool",
-						toolCallId: call.toolCallId,
-						content: text
-					});
-					causalityMonitor?.recordCall(`tool.error:${call.toolName}`);
-				} else {
-					const output = outcome.output;
-					yield {
-						type: "tool.execute.end",
-						toolCallId: call.toolCallId,
-						result: output,
-						durationMs: outcome.durationMs
-					};
-					const handle = outcome.resultHandle;
-					const rendered = handle !== void 0 ? `${handle.preview}\n\n[Full result${handle.bytes !== void 0 ? ` (${handle.bytes} bytes)` : ""} stored behind a handle. Call read_result with handle ${JSON.stringify(handle.uri)} to retrieve it - optionally narrow with offset/length (bytes) or startLine/endLine.]` : typeof output === "string" ? output : JSON.stringify(output);
-					const text = rendered === void 0 || rendered.trim().length === 0 ? "(tool ran successfully with no output)" : rendered;
-					messages.push({
-						role: "tool",
-						toolCallId: call.toolCallId,
-						content: text
-					});
-					state.messages.push({
-						role: "tool",
-						toolCallId: call.toolCallId,
-						content: text
-					});
-					causalityMonitor?.recordCall(`tool:${call.toolName}`);
-					if (call.toolName === TOOL_SEARCH_NAME) recordToolSearchPromotions(output, promotedDeferred);
-				}
-			}
-		}
-		/**
-		* Auto-compaction trigger (WI-09 / P1-1). Before assembling each
-		* provider request, ask the memory {@link ContextEngine} whether the
-		* in-flight buffer has crossed its per-provider threshold
-		* (`shouldCompact`); when it has, summarise the older turns
-		* (`compactNow`, `source: 'auto-trigger'`), splice the result back in
-		* - preserving the byte-stable system prefix and the most-recent
-		* turns verbatim - and emit `context.compacted`. The compaction is
-		* configured on the memory facade (`createMemory({ contextEngine })`,
-		* RB-46); there is no parallel agent-level knob.
-		*
-		* No-op when no memory is wired, when compaction is disabled or below
-		* threshold (the engine returns `false`), or for `secret`-tier runs
-		* (secret history is never shipped to the summarizer - a less-trusted
-		* external sink; per-result handle references land in WI-10). Best
-		* effort: a misconfigured engine (e.g. no summarizer) is swallowed and
-		* the run proceeds uncompacted rather than aborting mid-flight.
-		*
-		* Operator-requested compactions (`agent.compact()`, CE-3/AG-13) are
-		* serviced here too, FIRST - the queue carries the `compact()` promise
-		* resolvers, and manual requests bypass the trigger evaluation.
-		*/
-		async function* maybeAutoCompact() {
-			while (pendingManualCompacts.length > 0) {
-				const pending = pendingManualCompacts.shift();
-				if (pending !== void 0) yield* serviceManualCompact(pending);
-			}
-			const mem = memory;
-			if (mem === void 0) return;
-			if (config.sensitivity === "secret") return;
-			const engine = mem.contextEngine;
-			if (!await engine.shouldCompact(messages, { compactableFromIndex: systemPrefixLength }).catch(() => false)) return;
-			const startedAt = Date.now();
-			const envelope = await engine.compactNow({
-				scope: {
-					userId: state.userId ?? agentId,
-					sessionId,
-					agentId
-				},
-				runId: state.id,
-				sessionId,
-				agentId,
-				source: "auto-trigger",
-				messages: messages.slice(systemPrefixLength),
-				prefixMessages: messages.slice(0, systemPrefixLength),
-				memory: mem
-			}).catch(() => void 0);
-			if (envelope === void 0) return;
-			if (envelope.result.droppedMessageIndices.length === 0) return;
-			spliceCompacted(envelope);
-			yield {
-				type: "context.compacted",
-				runId: state.id,
-				sessionId,
-				agentId,
-				beforeTokens: envelope.result.beforeTokens,
-				afterTokens: envelope.result.afterTokens,
-				summaryTokens: envelope.result.summaryTokens,
-				durationMs: Date.now() - startedAt,
-				source: "auto-trigger",
-				hooksFiredCount: envelope.result.hooksFiredCount
-			};
-		}
-		/**
-		* context-engine-06: last-resort tier at hard context overflow. When
-		* a provider rejects the request as over-window, force ONE aggressive
-		* compaction (`preserveRecentTurns: 2`, trigger evaluation bypassed)
-		* and let the caller retry the same provider - the fallback chain's
-		* members usually share the same window, so without this the run just
-		* dies. Returns `true` when the buffer actually shrank (retry is
-		* worthwhile); `false` when memory is not wired, the run is
-		* secret-tier, compaction trimmed nothing, or the engine threw.
-		*/
-		async function* tryEmergencyCompact() {
-			const mem = memory;
-			if (mem === void 0 || config.sensitivity === "secret") return false;
-			const startedAt = Date.now();
-			const envelope = await mem.contextEngine.compactNow({
-				scope: {
-					userId: state.userId ?? agentId,
-					sessionId,
-					agentId
-				},
-				runId: state.id,
-				sessionId,
-				agentId,
-				source: "auto-trigger",
-				messages: messages.slice(systemPrefixLength),
-				prefixMessages: messages.slice(0, systemPrefixLength),
-				memory: mem,
-				preserveRecentTurns: 2
-			}).catch(() => void 0);
-			if (envelope === void 0 || envelope.result.droppedMessageIndices.length === 0) return false;
-			spliceCompacted(envelope);
-			yield {
-				type: "context.compacted",
-				runId: state.id,
-				sessionId,
-				agentId,
-				beforeTokens: envelope.result.beforeTokens,
-				afterTokens: envelope.result.afterTokens,
-				summaryTokens: envelope.result.summaryTokens,
-				durationMs: Date.now() - startedAt,
-				source: "auto-trigger",
-				hooksFiredCount: envelope.result.hooksFiredCount
-			};
-			return true;
-		}
-		/**
-		* Prefix-pinned splice shared by the auto + manual compaction paths
-		* (CE-3): stable system prefix + [summary, ...recent turns], with the
-		* post-compaction hooks' text Context Essentials re-anchored as a
-		* trailing system message so they survive the trim (RB-46). Mutates
-		* BOTH the live loop buffer and `state.messages`.
-		*/
-		function spliceCompacted(envelope) {
-			const rebuilt = [...messages.slice(0, systemPrefixLength), ...envelope.result.trimmedMessages];
-			const essentials = envelope.extraContent.map((part) => typeof part === "object" && part !== null && "text" in part ? String(part.text) : "").filter((text) => text.length > 0).join("\n\n");
-			if (essentials.length > 0) rebuilt.push({
-				role: "system",
-				content: essentials
-			});
-			messages.splice(0, messages.length, ...rebuilt);
-			state.messages.splice(0, state.messages.length, ...rebuilt);
-		}
-		/**
-		* Service one `agent.compact()` request inside the loop (CE-3/AG-13):
-		* same prefix-pinned splice as the auto path, `source: 'manual'` (or
-		* the caller's `'pre-step'`), `preserveRecentTurns` forwarded as a
-		* per-call strategy override. An engine failure rejects the caller's
-		* promise but never aborts the live run; a summarize that trims
-		* nothing resolves `applied: false` without an event.
-		*/
-		async function* serviceManualCompact(pending) {
-			const mem = memory;
-			if (mem === void 0) {
-				pending.resolve(noopCompactionResult("no-memory"));
-				return;
-			}
-			const source = pending.options?.source ?? "manual";
-			const startedAt = Date.now();
-			let envelope;
-			try {
-				envelope = await mem.contextEngine.compactNow({
-					scope: {
-						userId: state.userId ?? agentId,
-						sessionId,
-						agentId
-					},
-					runId: state.id,
-					sessionId,
-					agentId,
-					source,
-					messages: messages.slice(systemPrefixLength),
-					prefixMessages: messages.slice(0, systemPrefixLength),
-					memory: mem,
-					...pending.options?.preserveRecentTurns !== void 0 ? { preserveRecentTurns: pending.options.preserveRecentTurns } : {}
-				});
-			} catch (cause) {
-				pending.reject(cause);
-				return;
-			}
-			const { result } = envelope;
-			const applied = result.droppedMessageIndices.length > 0;
-			if (applied) {
-				spliceCompacted(envelope);
-				yield {
-					type: "context.compacted",
-					runId: state.id,
-					sessionId,
-					agentId,
-					beforeTokens: result.beforeTokens,
-					afterTokens: result.afterTokens,
-					summaryTokens: result.summaryTokens,
-					durationMs: Date.now() - startedAt,
-					source,
-					hooksFiredCount: result.hooksFiredCount
-				};
-			}
-			pending.resolve({
-				beforeTokens: result.beforeTokens,
-				afterTokens: result.afterTokens,
-				summaryTokens: result.summaryTokens,
-				durationMs: Date.now() - startedAt,
-				hooksFiredCount: result.hooksFiredCount,
-				summary: result.summary ?? "",
-				applied,
-				...applied ? {} : { skippedReason: "nothing-to-trim" }
-			});
-		}
-		const handoffNames = Array.from(handoffMap.keys());
-		let stepNumber = 0;
+		if (resumed && resumedApprovedCalls.length > 0) yield* dispatchResumedApprovals(runEnv, resumedApprovedCalls, grantedApprovals);
+		if (resumed && subRunDecisions.size > 0) yield* processSubRunResumes(runEnv, subRunDecisions);
+		if (resumed && (state.status === "awaiting_approval" || state.status === "aborted" && state.pendingApprovals.length > 0)) return yield* finishRun(state, finalSnapshot);
+		let stepNumber = state.steps.reduce((max, s) => Math.max(max, s.stepNumber), 0);
 		let verifierRoundsUsed = 0;
 		let lastStepCalledToolNames = [];
-		async function* emitCancellation() {
-			yield {
-				type: "agent.cancelling",
-				runId: state.id,
-				drain: pendingAbort?.drain ?? false,
-				onPendingApprovals: pendingAbort?.onPendingApprovals ?? "deny"
-			};
-			const policy = pendingAbort?.onPendingApprovals ?? "deny";
-			if (policy === "deny") {
-				const drained = state.pendingApprovals.splice(0, state.pendingApprovals.length);
-				for (const approval of drained) yield {
-					type: "tool.approval.denied",
-					toolCallId: approval.toolCallId,
-					reason: "auto-denied: agent.abort()"
-				};
-			} else if (policy === "fail") {
-				state.status = "failed";
-				state.error = {
-					message: "aborted with pending approvals",
-					code: "run-aborted"
-				};
-				yield {
-					type: "agent.error",
-					error: {
-						message: "aborted with pending approvals",
-						code: "run-aborted"
-					}
-				};
-				return true;
-			}
-			state.status = "aborted";
-			return false;
-		}
 		try {
 			while (!stopWhen.check(state)) {
 				while (externalEventQueue.length > 0) {
@@ -1341,7 +249,7 @@ function createAgent(config) {
 					if (ev !== void 0) yield ev;
 				}
 				if (signal.aborted) {
-					if (yield* emitCancellation()) return yield* finishRun(state, finalSnapshot);
+					if (yield* emitCancellation(runEnv)) return yield* finishRun(state, finalSnapshot);
 					break;
 				}
 				stepNumber += 1;
@@ -1369,7 +277,7 @@ function createAgent(config) {
 						"graphorin.step.number": stepNumber
 					}
 				});
-				yield* maybeAutoCompact();
+				yield* maybeAutoCompact(runEnv);
 				const stepCtx = {
 					...runContextBase,
 					stepNumber,
@@ -1377,181 +285,14 @@ function createAgent(config) {
 					...currentStepSpan !== void 0 ? { span: currentStepSpan } : {}
 				};
 				const overrides = config.prepareStep ? await config.prepareStep(stepCtx) : {};
-				const useOverrideRegistry = overrides.tools !== void 0 && !isCodeMode;
-				const stepRegistry = useOverrideRegistry ? buildToolRegistry({ tools: overrides.tools }).registry : toolRegistry;
-				if (useOverrideRegistry) {
-					registerToolSearch(stepRegistry, config.toolPromotion === "run-boundary" ? "next-run" : "next-step");
-					registerReadResult(stepRegistry, resultReader);
-				}
-				const stepExecutor = useOverrideRegistry ? makeToolExecutor(stepRegistry) : toolExecutor;
-				const handoffTools = handoffNames.map((n) => {
-					const h = handoffMap.get(n);
-					if (h === void 0) throw new ToolNotFoundError(n);
-					return buildHandoffTool(h.agent);
-				});
-				const readOnlyRun = activeRunCapability === "read-only";
-				const keepReadOnly = (t) => {
-					const cls = t.__sideEffectClass ?? t.sideEffectClass;
-					return cls === "pure" || cls === "read-only";
-				};
-				let stepTools;
-				if (isCodeMode) stepTools = readOnlyRun ? [...codeModeAdvertised.filter(keepReadOnly)] : [...codeModeAdvertised, ...handoffTools];
-				else {
-					const eagerTools = stepRegistry.listEager();
-					const advertisedPromotions = runStartPromotions ?? promotedDeferred;
-					const promotedTools = advertisedPromotions.size === 0 ? [] : orderPromotedTools(advertisedPromotions, stepRegistry.listDeferred());
-					stepTools = readOnlyRun ? [...eagerTools.filter(keepReadOnly), ...promotedTools.filter(keepReadOnly)] : [
-						...eagerTools,
-						...handoffTools,
-						...promotedTools
-					];
-				}
-				const calledLastStep = new Set(lastStepCalledToolNames);
-				const toolPreferences = stepTools.filter((t) => calledLastStep.has(t.name)).map((t) => {
-					return t.preferredModel;
-				});
-				const primary = resolvePreferredModel({
-					...overrides.provider !== void 0 ? { prepareStepProvider: overrides.provider } : {},
-					toolPreferredModels: toolPreferences,
-					...config.preferredModel !== void 0 ? { agentPreferredModel: config.preferredModel } : {},
-					agentDefaultProvider: config.provider,
-					...config.modelTierMap !== void 0 ? { modelTierMap: config.modelTierMap } : {}
-				});
-				const fallbackChain = primary.source === "prepare-step" ? [primary.resolvedProvider] : [primary.resolvedProvider, ...(config.fallbackModels ?? []).map(specToProvider)];
-				const reasoningPolicy = effectiveReasoningRetention(config.reasoningRetention, primary.resolvedProvider);
-				if (reasoningPolicy === "strip") {
-					const { stripped } = stripReasoningFromMessages(messages);
-					if (stripped > 0) stripReasoningFromMessages(state.messages);
-				}
-				const toolDefs = stepTools.map((t) => toolToDefinition(t));
-				const baseRequest = {
-					messages: buildStepMessages(messages, structuredInstruction, activeRunState?.todos),
-					...config.outputType !== void 0 ? { outputType: {
-						kind: config.outputType.kind,
-						...config.outputType.description !== void 0 ? { description: config.outputType.description } : {},
-						...config.outputType.jsonSchema !== void 0 ? { jsonSchema: config.outputType.jsonSchema } : {}
-					} } : {},
-					tools: toolDefs,
-					...overrides.toolChoice !== void 0 ? { toolChoice: overrides.toolChoice } : config.toolChoice !== void 0 ? { toolChoice: config.toolChoice } : {},
-					metadata: {
-						sessionId,
-						agentId,
-						...userId !== void 0 ? { userId } : {},
-						runId: state.id,
-						stepNumber
-					},
-					signal,
-					...overrides.temperature !== void 0 ? { temperature: overrides.temperature } : {},
-					...overrides.maxTokens !== void 0 ? { maxTokens: overrides.maxTokens } : {},
-					...config.cachePolicy !== void 0 ? { cachePolicy: config.cachePolicy } : {},
-					...currentStepSpan !== void 0 ? { parentSpan: currentStepSpan } : {},
-					reasoningRetention: reasoningPolicy
-				};
-				const stepUsage = zeroUsage();
-				let attempt = 0;
-				let textBuffer = "";
-				let providerForStep = primary.resolvedProvider;
-				let lastModelId = primary.resolvedModelId;
-				let modelSucceeded = false;
-				let lastError;
-				let finalCalls = [];
-				let stepReasoningParts = [];
-				let requestForStep = baseRequest;
-				let emergencyCompactTried = false;
-				for (let chainIdx = 0; chainIdx < fallbackChain.length; chainIdx++) {
-					const candidate = fallbackChain[chainIdx];
-					if (candidate === void 0) continue;
-					providerForStep = candidate;
-					const providerModelId = providerForStep.modelId;
-					if (chainIdx > 0) {
-						attempt += 1;
-						const reason = lastError ? isAgentFallbackEligible(lastError, fallbackPolicy).reason ?? "transient" : "transient";
-						yield {
-							type: "agent.model.fellback",
-							runId: state.id,
-							sessionId,
-							agentId,
-							from: lastModelId,
-							to: providerModelId,
-							reason,
-							stepNumber,
-							attempt
-						};
-						lastModelId = providerModelId;
-					}
-					const evState = {
-						textBuffer: "",
-						reasoningBuffer: "",
-						reasoningParts: [],
-						calls: /* @__PURE__ */ new Map(),
-						finalCalls: []
-					};
-					let providerError;
-					let providerCallCompleted = false;
-					let providerStepUsage = zeroUsage();
-					try {
-						const stream$1 = providerForStep.stream(requestForStep);
-						for await (const ev of stream$1) {
-							if (signal.aborted && pendingAbort?.drain !== true) throw new AgentRuntimeError("run-aborted", "aborted");
-							const out = handleProviderEvent(ev, evState);
-							if (out.emit !== void 0) yield out.emit;
-							if (out.providerError !== void 0) providerError = out.providerError;
-							if (out.usage !== void 0) providerStepUsage = addUsage(providerStepUsage, out.usage);
-							if (out.finished === true) providerCallCompleted = true;
-						}
-					} catch (cause) {
-						if (signal.aborted || cause instanceof AgentRuntimeError && cause.code === "run-aborted") break;
-						const message = cause instanceof Error ? cause.message : String(cause);
-						providerError = {
-							kind: classifyThrownProviderErrorKind(cause),
-							message,
-							cause
-						};
-					}
-					if (providerError !== void 0) {
-						lastError = providerError;
-						if (providerError.kind === "context-length" && !emergencyCompactTried) {
-							emergencyCompactTried = true;
-							if (yield* tryEmergencyCompact()) {
-								requestForStep = {
-									...baseRequest,
-									messages: buildStepMessages(messages, structuredInstruction, activeRunState?.todos)
-								};
-								chainIdx -= 1;
-								continue;
-							}
-						}
-						if (!isAgentFallbackEligible(providerError, fallbackPolicy).eligible || chainIdx === fallbackChain.length - 1) {
-							yield {
-								type: "agent.error",
-								error: {
-									message: providerError.message,
-									code: providerError.kind
-								}
-							};
-							state.status = "failed";
-							state.error = {
-								message: providerError.message,
-								code: providerError.kind
-							};
-							return yield* finishRun(state, finalSnapshot);
-						}
-						continue;
-					}
-					if (providerCallCompleted) {
-						modelSucceeded = true;
-						textBuffer = evState.textBuffer;
-						finalCalls = evState.finalCalls;
-						if (evState.reasoningBuffer.length > 0) stepReasoningParts = [{
-							type: "reasoning",
-							text: evState.reasoningBuffer
-						}];
-						accumulateUsage(stepUsage, providerStepUsage);
-						break;
-					}
-				}
+				const { stepRegistry, stepExecutor, stepTools, primary, fallbackChain } = resolveStepToolContext(runEnv, overrides, lastStepCalledToolNames);
+				const reasoningPolicy = applyReasoningRetention(config.reasoningRetention, primary.resolvedProvider, messages, state.messages);
+				const chain = yield* runProviderFallbackChain(runEnv, fallbackChain, buildBaseRequest(runEnv, overrides, stepTools.map((t) => toolToDefinition(t)), reasoningPolicy, stepNumber, currentStepSpan), primary, stepNumber);
+				if (chain.failed) return yield* finishRun(state, finalSnapshot);
+				const { modelSucceeded, textBuffer, finalCalls, stepReasoningParts } = chain;
+				const { stepUsage, lastModelId } = chain;
 				if (signal.aborted && !modelSucceeded) {
-					yield* emitCancellation();
+					yield* emitCancellation(runEnv);
 					return yield* finishRun(state, finalSnapshot);
 				}
 				if (!modelSucceeded) {
@@ -1572,28 +313,7 @@ function createAgent(config) {
 				usageAcc.add(lastModelId, stepUsage);
 				addModelUsage(state, lastModelId, stepUsage);
 				accumulateUsage(state.usage, stepUsage);
-				const leakCheck = causalityMonitor !== void 0 && textBuffer.length > 0 ? causalityMonitor.checkMessage(textBuffer) : void 0;
-				const leakBlocked = leakCheck?.leakDetected === true && leakCheck.decision === "block";
-				const assistant = buildAssistantMessage(leakBlocked ? LATERAL_LEAK_BLOCKED_NOTICE : textBuffer, stepReasoningParts, finalCalls, agentId, reasoningPolicy);
-				messages.push(assistant);
-				state.messages.push(assistant);
-				if (toolDataFlowGuard !== void 0 && textBuffer.length > 0 && !leakBlocked) toolDataFlowGuard.recordAssistant(state.id, textBuffer);
-				if (leakCheck?.leakDetected === true) {
-					const sha = sha256Hex(textBuffer);
-					yield {
-						type: "agent.lateral-leak.detected",
-						runId: state.id,
-						sessionId,
-						agentId,
-						vector: leakCheck.vector,
-						severity: leakCheck.severity,
-						causalityChain: leakCheck.causalityChain,
-						messageContentSha256: sha,
-						...leakCheck.matchedPattern !== void 0 ? { matchedPattern: leakCheck.matchedPattern } : {},
-						decision: leakCheck.decision,
-						detectedAtIso: (/* @__PURE__ */ new Date()).toISOString()
-					};
-				}
+				const leakBlocked = yield* commitAssistantMessage(runEnv, textBuffer, stepReasoningParts, finalCalls, reasoningPolicy);
 				const handoffCalls = finalCalls.filter((c) => handoffMap.has(c.toolName));
 				if (handoffCalls.length > 1) throw new MultipleHandoffsInStepError(handoffCalls.map((c) => c.toolName));
 				const stepRecord = {
@@ -1619,202 +339,30 @@ function createAgent(config) {
 					};
 				}
 				if (finalCalls.length > 0) {
-					const execRunContext = {
+					const walked = yield* processStepToolCalls(runEnv, finalCalls, stepRegistry, stepExecutor, {
 						...runContextBase,
 						stepNumber,
 						messages,
 						...currentStepSpan !== void 0 ? { span: currentStepSpan } : {}
-					};
-					let batch = [];
-					let stepApprovalsRequested = 0;
-					for (const call of finalCalls) {
-						const handoff = handoffMap.get(call.toolName);
-						if (handoff !== void 0) {
-							if (batch.length > 0) {
-								yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
-								batch = [];
-							}
-							yield {
-								type: "tool.execute.start",
-								toolCallId: call.toolCallId
-							};
-							const filter = handoff.filter ?? filters.defaultHandoffFilter();
-							const filtered = filter(messages);
-							const targetId = handoff.agent.id;
-							const handoffRec = {
-								fromAgentId: agentId,
-								toAgentId: targetId,
+					}, stepNumber);
+					if (walked.suspended) {
+						if (walked.abortPending === true) {
+							yield* emitCancellation(runEnv);
+							if (config.checkpointStore !== void 0) await config.checkpointStore.put(state.id, "agent", {
+								id: state.id,
+								threadId: state.id,
+								namespace: "agent",
+								state: serializeRunState(state, { stripTracingApiKey: true }),
+								channelVersions: {},
 								stepNumber,
-								at: (/* @__PURE__ */ new Date()).toISOString(),
-								inputFilter: filter.descriptor,
-								secretsInheritance: "inherit-allowlist",
-								inheritedSecrets: []
-							};
-							state.handoffs.push(handoffRec);
-							yield {
-								type: "handoff",
-								fromAgentId: agentId,
-								toAgentId: targetId
-							};
-							state.currentAgentId = targetId;
-							const subAgent = handoff.agent;
-							const subStart = Date.now();
-							const subOutputs = [];
-							let subResult;
-							const subStream = subAgent.stream(filtered, {
-								signal,
-								...options.deps !== void 0 || config.deps !== void 0 ? { deps: options.deps ?? config.deps } : {},
-								sessionId
+								createdAt: (/* @__PURE__ */ new Date()).toISOString()
+							}, {
+								source: "sync",
+								status: state.status === "failed" ? "failed" : "aborted",
+								nodeName: "agent.abort",
+								sessionId: state.sessionId
 							});
-							for await (const subEv of subStream) if (subEv.type === "text.complete") subOutputs.push(subEv.text);
-							else if (subEv.type === "agent.end") subResult = subEv.result;
-							const subDurationMs = Date.now() - subStart;
-							const stepEntry = state.steps[state.steps.length - 1];
-							if (subResult !== void 0 && subResult.status !== "completed") {
-								const toolError = {
-									toolCallId: call.toolCallId,
-									toolName: call.toolName,
-									kind: subResult.status === "aborted" ? "aborted" : "execution_failed",
-									message: `handoff to '${targetId}' ${subResult.status}${subResult.error !== void 0 ? `: ${subResult.error.message}` : ""}`
-								};
-								if (stepEntry !== void 0) stepEntry.toolCalls.push({
-									call,
-									outcome: toolError,
-									stepNumber
-								});
-								yield {
-									type: "tool.execute.error",
-									toolCallId: call.toolCallId,
-									error: toolError
-								};
-								const text = renderToolErrorMessage(toolError);
-								messages.push({
-									role: "tool",
-									toolCallId: call.toolCallId,
-									content: text
-								});
-								state.messages.push({
-									role: "tool",
-									toolCallId: call.toolCallId,
-									content: text
-								});
-								continue;
-							}
-							const result = subOutputs.join("");
-							const completed = {
-								call,
-								outcome: {
-									toolCallId: call.toolCallId,
-									toolName: call.toolName,
-									output: result,
-									durationMs: subDurationMs
-								},
-								stepNumber
-							};
-							if (stepEntry !== void 0) stepEntry.toolCalls.push(completed);
-							yield {
-								type: "tool.execute.end",
-								toolCallId: call.toolCallId,
-								result,
-								durationMs: subDurationMs
-							};
-							messages.push({
-								role: "tool",
-								toolCallId: call.toolCallId,
-								content: result
-							});
-							state.messages.push({
-								role: "tool",
-								toolCallId: call.toolCallId,
-								content: result
-							});
-							continue;
-						}
-						const resolvedTool = stepRegistry.get(call.toolName);
-						let gateInput = call.args;
-						if (resolvedTool !== void 0 && isApprovalGated(resolvedTool)) {
-							const parsed = safeParseGatedArgs(resolvedTool, call.args);
-							if (parsed !== void 0 && !parsed.success) {
-								const toolError = {
-									toolCallId: call.toolCallId,
-									toolName: call.toolName,
-									kind: "invalid_input",
-									message: `Invalid arguments for approval-gated tool '${call.toolName}': ${parsed.message}`
-								};
-								const stepEntry = state.steps[state.steps.length - 1];
-								if (stepEntry !== void 0) stepEntry.toolCalls.push({
-									call,
-									outcome: toolError,
-									stepNumber
-								});
-								yield {
-									type: "tool.execute.start",
-									toolCallId: call.toolCallId
-								};
-								yield {
-									type: "tool.execute.error",
-									toolCallId: call.toolCallId,
-									error: toolError
-								};
-								const text = renderToolErrorMessage(toolError);
-								messages.push({
-									role: "tool",
-									toolCallId: call.toolCallId,
-									content: text
-								});
-								state.messages.push({
-									role: "tool",
-									toolCallId: call.toolCallId,
-									content: text
-								});
-								continue;
-							}
-							if (parsed !== void 0) gateInput = parsed.data;
 						}
-						if (await invokeNeedsApproval(resolvedTool, gateInput, execRunContext, signal)) {
-							if (batch.length > 0) {
-								yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
-								batch = [];
-							}
-							yield {
-								type: "tool.execute.start",
-								toolCallId: call.toolCallId
-							};
-							const approval = {
-								toolCallId: call.toolCallId,
-								toolName: call.toolName,
-								args: call.args,
-								requestedAt: (/* @__PURE__ */ new Date()).toISOString()
-							};
-							state.pendingApprovals.push(approval);
-							stepApprovalsRequested += 1;
-							yield {
-								type: "tool.approval.requested",
-								toolCallId: call.toolCallId
-							};
-							continue;
-						}
-						batch.push(call);
-					}
-					if (batch.length > 0) yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
-					if (stepApprovalsRequested > 0) {
-						state.status = "awaiting_approval";
-						const taintSnap = toolDataFlowGuard?.snapshotLedger(state.id);
-						if (taintSnap !== void 0) state.taintSummary = taintSnap;
-						if (promotedDeferred.size > 0) state.promotedTools = [...promotedDeferred];
-						if (config.checkpointStore !== void 0) await config.checkpointStore.put(state.id, "agent", {
-							id: state.id,
-							threadId: state.id,
-							namespace: "agent",
-							state: serializeRunState(state, { stripTracingApiKey: true }),
-							channelVersions: {},
-							stepNumber,
-							createdAt: (/* @__PURE__ */ new Date()).toISOString()
-						}, {
-							source: "sync",
-							status: "suspended",
-							nodeName: "agent.run"
-						});
 						return yield* finishRun(state, finalSnapshot);
 					}
 				}
@@ -1831,37 +379,9 @@ function createAgent(config) {
 				};
 				if (finalCalls.length === 0) {
 					if (config.verifiers !== void 0 && config.verifiers.length > 0) {
-						const feedbacks = [];
-						for (const verifier of config.verifiers) {
-							let result;
-							try {
-								result = await verifier.verify({
-									output: String(finalSnapshot.output ?? ""),
-									state,
-									stepNumber
-								});
-							} catch {
-								result = { ok: true };
-							}
-							yield {
-								type: "verifier.result",
-								verifierId: verifier.id,
-								ok: result.ok,
-								...result.ok ? {} : { feedback: result.feedback },
-								stepNumber
-							};
-							if (!result.ok) feedbacks.push(`[verifier:${verifier.id}] ${result.feedback}`);
-						}
-						if (feedbacks.length > 0 && verifierRoundsUsed < (config.maxVerifierRounds ?? 1)) {
-							verifierRoundsUsed += 1;
-							const feedbackMessage = {
-								role: "user",
-								content: `Your response failed ${feedbacks.length} verification check(s). Address the feedback and answer again:\n${feedbacks.join("\n")}`
-							};
-							messages.push(feedbackMessage);
-							state.messages.push(feedbackMessage);
-							continue;
-						}
+						const gate = yield* runVerifierGate(runEnv, finalSnapshot, stepNumber, verifierRoundsUsed);
+						verifierRoundsUsed = gate.verifierRoundsUsed;
+						if (gate.continueRun) continue;
 					}
 					state.status = "completed";
 					break;
@@ -1895,135 +415,17 @@ function createAgent(config) {
 			runSpan.end();
 			if (parentSignal !== void 0) parentSignal.removeEventListener("abort", onParentAbort);
 		}
-		if (state.status === "running") {
-			const message = `run stopped by stop condition: ${stopWhen.description}`;
-			state.status = "failed";
-			state.error = {
-				message,
-				code: "stop-condition"
-			};
-			yield {
-				type: "agent.error",
-				error: {
-					message,
-					code: "stop-condition"
-				}
-			};
-		}
-		if (state.status === "completed" && config.outputType?.kind === "structured") {
-			const raw = String(finalSnapshot.output ?? "");
-			try {
-				const parsed = JSON.parse(stripJsonFence(raw));
-				finalSnapshot.output = config.outputType.schema !== void 0 ? config.outputType.schema.parse(parsed) : parsed;
-			} catch (cause) {
-				const message = `structured output validation failed: ${cause instanceof Error ? cause.message : String(cause)}`;
-				yield {
-					type: "agent.error",
-					error: {
-						message,
-						code: "output-validation-failed"
-					}
-				};
-				state.status = "failed";
-				state.error = {
-					message,
-					code: "output-validation-failed"
-				};
-			}
-		}
-		const outputGuards = config.guardrails?.output;
-		if (state.status === "completed" && outputGuards !== void 0 && outputGuards.length > 0) {
-			const composed = await composeGuardrails(outputGuards, finalSnapshot.output, {
-				stage: "output",
-				runId: state.id,
-				sessionId,
-				agentId
-			});
-			if (!composed.ok) {
-				yield {
-					type: "guardrail.tripped",
-					guardrailName: composed.name,
-					phase: "output",
-					reason: composed.message
-				};
-				const message = `output guardrail '${composed.name}' blocked the run: ${composed.message}`;
-				yield {
-					type: "agent.error",
-					error: {
-						message,
-						code: "guardrail-blocked"
-					}
-				};
-				state.status = "failed";
-				state.error = {
-					message,
-					code: "guardrail-blocked"
-				};
-			} else if (composed.value !== finalSnapshot.output) finalSnapshot.output = composed.value;
-		}
+		yield* finalizeRunOutput(runEnv, finalSnapshot);
 		activeRunState = void 0;
 		return yield* finishRun(state, finalSnapshot);
 	}
-	/**
-	* Terminal wrapper around {@link finalize}: every exit path of the run
-	* loop - completed, failed, aborted, suspended - ends the stream with
-	* an `agent.end` event carrying the final {@link AgentResult} (AG-20).
-	*/
-	async function* finishRunBase(state, snapshot) {
-		while (pendingManualCompacts.length > 0) pendingManualCompacts.shift()?.resolve(noopCompactionResult("no-active-run"));
-		const result = finalize(state, snapshot);
-		if (result.status === "completed" || result.status === "failed") await spillWriter.clear?.(result.state.id).catch(() => {});
-		yield {
-			type: "agent.end",
-			runId: result.state.id,
-			result
-		};
-		return result;
-	}
-	function finalize(state, snapshot) {
-		state.finishedAt = state.finishedAt ?? (/* @__PURE__ */ new Date()).toISOString();
-		return {
-			output: snapshot.output,
-			usage: state.usage,
-			status: state.status,
-			...state.error !== void 0 ? { error: state.error } : {},
-			state
-		};
-	}
-	const stream = (input, options) => {
-		const opts = options ?? {};
-		return { [Symbol.asyncIterator]: () => {
-			const gen = runLoop(input, opts);
-			return {
-				async next() {
-					const r = await gen.next();
-					if (r.done === true) return {
-						done: true,
-						value: void 0
-					};
-					return {
-						done: false,
-						value: r.value
-					};
-				},
-				async return() {
-					await gen.return(void 0);
-					return {
-						done: true,
-						value: void 0
-					};
-				}
-			};
-		} };
-	};
-	const run = async (input, options) => {
-		const gen = runLoop(input, options ?? {});
-		let next = await gen.next();
-		while (next.done !== true) next = await gen.next();
-		const result = next.value;
-		if (result === void 0) throw new Error("unreachable: agent run loop ended without a result");
-		return result;
-	};
+	const finishRunBase = createRunFinisher({
+		pendingManualCompacts,
+		spillWriter,
+		checkpointStore: config.checkpointStore,
+		checkpointPolicy: config.checkpointPolicy
+	});
+	const { stream, run } = createRunMethods(runLoop);
 	const steer = (message) => {
 		const { seed } = asMessages(message);
 		pendingSteer.push(...seed);
@@ -2044,136 +446,23 @@ function createAgent(config) {
 		pendingAbort = options ?? {};
 		abortController?.abort();
 	};
-	const foldRunOutcome = (result, maxChars) => {
-		const steps = result.state.steps;
-		const toolNames = [...new Set(steps.flatMap((step) => step.toolCalls.map((c) => c.call.toolName)))];
-		const header = `[sub-agent '${config.name}' outcome] status=${result.status}; steps=${steps.length}; toolCalls=${steps.reduce((n, st) => n + st.toolCalls.length, 0)}` + (toolNames.length > 0 ? `; tools=${toolNames.join(", ")}` : "");
-		const text = typeof result.output === "string" ? result.output : JSON.stringify(result.output);
-		return `${header}\n${text.length > maxChars ? `${text.slice(0, maxChars)}\n[... ${text.length - maxChars} chars truncated by contextFold]` : text}`;
-	};
-	const taintFromChildState = (state) => {
-		const summary = state.taintSummary;
-		if (summary === void 0 || !summary.untrustedSeen && !summary.sensitiveSeen) return;
-		return {
-			...summary.untrustedSeen ? { untrusted: true } : {},
-			...summary.sensitiveSeen ? { sensitive: true } : {},
-			sourceKind: "sub-agent"
-		};
-	};
-	const toTool = (options = {}) => {
-		const exposeTurns = options.exposeTurns ?? "final";
-		const foldMaxChars = options.contextFold === void 0 || options.contextFold === false ? null : typeof options.contextFold === "object" ? options.contextFold.maxChars ?? 2e3 : 2e3;
-		const propagateTaint = options.propagateTaint !== false;
-		return {
-			name: options.name ?? `subagent_${config.name}`,
-			description: options.description ?? `Invoke sub-agent '${config.name}'.`,
-			inputSchema: {
-				parse: (v) => v,
-				safeParse: (v) => ({
-					success: true,
-					data: v
-				}),
-				toJSON: () => ({
-					type: "object",
-					properties: { input: { type: "string" } },
-					required: ["input"]
-				})
-			},
-			sideEffectClass: "side-effecting",
-			async execute(input, ctx) {
-				const callOpts = {
-					...ctx?.signal !== void 0 ? { signal: ctx.signal } : {},
-					...ctx?.runContext.deps !== void 0 ? { deps: ctx.runContext.deps } : {},
-					...ctx?.runContext.sessionId !== void 0 ? { sessionId: ctx.runContext.sessionId } : {},
-					...options.capability !== void 0 ? { capability: options.capability } : {}
-				};
-				const seed = options.inputFilter !== void 0 && ctx !== void 0 ? [...options.inputFilter(ctx.runContext.messages), {
-					role: "user",
-					content: input.input
-				}] : input.input;
-				if (exposeTurns === "all") {
-					const turns = [];
-					let endResult;
-					for await (const ev of stream(seed, callOpts)) if (ev.type === "text.complete") turns.push(ev.text);
-					else if (ev.type === "agent.end") endResult = ev.result;
-					if (endResult !== void 0 && endResult.status !== "completed") throw new Error(`sub-agent '${config.name}' ${endResult.status}${endResult.error !== void 0 ? `: ${endResult.error.message}` : ""}`);
-					const allOutput = foldMaxChars !== null && endResult !== void 0 ? foldRunOutcome(endResult, foldMaxChars) : turns.join("\n\n");
-					const allTaint = propagateTaint && endResult !== void 0 ? taintFromChildState(endResult.state) : void 0;
-					return allTaint !== void 0 ? {
-						output: allOutput,
-						taint: allTaint
-					} : allOutput;
-				}
-				const result = await run(seed, callOpts);
-				if (result.status !== "completed") throw new Error(`sub-agent '${config.name}' ${result.status}${result.error !== void 0 ? `: ${result.error.message}` : ""}`);
-				const taint = propagateTaint ? taintFromChildState(result.state) : void 0;
-				const output = exposeTurns === "none" ? "" : foldMaxChars !== null ? foldRunOutcome(result, foldMaxChars) : result.output;
-				return taint !== void 0 ? {
-					output,
-					taint
-				} : output;
-			}
-		};
-	};
-	const compact = async (options) => {
-		if (memory === void 0) return noopCompactionResult("no-memory");
-		if (config.sensitivity === "secret") return noopCompactionResult("sensitivity-gated");
-		if (activeRunState === void 0) return noopCompactionResult("no-active-run");
-		return await new Promise((resolve, reject) => {
-			pendingManualCompacts.push({
-				options,
-				resolve,
-				reject
-			});
-		});
-	};
-	const fanOut = async (options) => {
-		const runId = activeRunState?.id ?? `run_${newId()}`;
-		const sessionId = activeRunState?.sessionId ?? `session_${newId()}`;
-		return runFanOut({
-			children: options.children,
-			...options.maxConcurrentChildren !== void 0 ? { maxConcurrentChildren: options.maxConcurrentChildren } : {},
-			...options.perBudget !== void 0 ? { perBudget: options.perBudget } : {},
-			...options.mergeStrategy !== void 0 ? { mergeStrategy: options.mergeStrategy } : {},
-			...options.signal !== void 0 ? { signal: options.signal } : {},
-			emit: (event) => {
-				externalEventQueue.push(event);
-			},
-			...config.mergeGuard !== void 0 ? { mergeGuard: config.mergeGuard } : {},
-			runId,
-			sessionId,
-			agentId
-		});
-	};
-	const progressFallbackRunId = `run_${newId()}`;
-	const progress = {
-		write: async (content, opts) => {
-			const runId = activeRunState?.id ?? progressFallbackRunId;
-			const ref = await progressIO.write(runId, content, opts);
-			externalEventQueue.push({
-				type: "agent.progress.written",
-				runId,
-				sessionId: activeRunState?.sessionId ?? "",
-				agentId,
-				ref
-			});
-			return ref;
-		},
-		read: async (opts) => {
-			const queriedRunId = opts?.runId ?? activeRunState?.id ?? progressFallbackRunId;
-			const refs = await progressIO.read(queriedRunId, opts);
-			externalEventQueue.push({
-				type: "agent.progress.read",
-				runId: activeRunState?.id ?? queriedRunId,
-				sessionId: activeRunState?.sessionId ?? "",
-				agentId,
-				refs,
-				queriedRunId,
-				queriedRole: opts?.role
-			});
-			return refs;
-		}
+	const toTool = createToTool({
+		config,
+		run,
+		stream
+	});
+	const surfaceDeps = {
+		config,
+		memory,
+		agentId,
+		getActiveRunState: () => activeRunState,
+		externalEventQueue,
+		pendingManualCompacts,
+		progressIO
 	};
+	const compact = createCompactMethod(surfaceDeps);
+	const fanOut = createFanOutMethod(surfaceDeps);
+	const progress = createProgressSurface(surfaceDeps);
 	config.sensitivity;
 	return {
 		id: agentId,
@@ -2190,72 +479,6 @@ function createAgent(config) {
 		registry: toolRegistry
 	};
 }
-/**
-* Pre-execution approval screen (Adapter G / durable HITL). Evaluates a
-* (registry-resolved) tool's `needsApproval` against the realized args.
-* Returns `true` when the run must suspend before the tool executes.
-*
-* Actual execution flows through the `@graphorin/tools` executor, whose
-* `ApprovalGate` auto-grants because only no-approval / pre-approved
-* calls ever reach it; this probe is what keeps the suspend in the
-* agent so the durable-HITL contract (persist `RunState`, resume via
-* directive) is preserved.
-*/
-async function invokeNeedsApproval(tool, args, baseCtx, signal) {
-	const predicate = tool?.needsApproval;
-	if (predicate === void 0 || predicate === false) return false;
-	if (predicate === true) return true;
-	const probeCtx = {
-		toolCallId: "probe",
-		runContext: baseCtx,
-		signal,
-		tracer: baseCtx.tracer,
-		logger: NOOP_LOGGER,
-		secrets: probeSecretsAccessor(),
-		reportProgress: () => {},
-		streamContent: () => {}
-	};
-	return Boolean(await predicate(args, probeCtx));
-}
-/**
-* Rejecting secrets accessor used only by the {@link invokeNeedsApproval}
-* probe. Real tool execution resolves secrets through the executor's
-* ACL-scoped accessor; an approval predicate has no legitimate need to
-* read secret material, so every `require(...)` rejects.
-*/
-function probeSecretsAccessor() {
-	const rejector = (_key, _options) => Promise.reject(/* @__PURE__ */ new Error("secrets.require is unavailable inside a needsApproval predicate"));
-	return { require: rejector };
-}
-/**
-* tools-02: validate an approval-gated call's args at the pre-screen so
-* the gate decision - and what a human is asked to approve - is the input
-* that will actually execute. Structural + defensive: `undefined` when
-* the tool exposes no callable `safeParse` (nothing to validate here; the
-* executor still validates at dispatch); a throwing schema counts as a
-* validation failure rather than crashing the loop.
-*/
-function safeParseGatedArgs(tool, args) {
-	const schema = tool.inputSchema;
-	const safeParse = schema?.safeParse;
-	if (typeof safeParse !== "function") return void 0;
-	try {
-		const parsed = safeParse.call(schema, args);
-		if (parsed.success === true) return {
-			success: true,
-			data: parsed.data
-		};
-		return {
-			success: false,
-			message: parsed.error?.message ?? "schema validation failed"
-		};
-	} catch (cause) {
-		return {
-			success: false,
-			message: cause instanceof Error ? cause.message : String(cause)
-		};
-	}
-}
 
 //#endregion
 export { createAgent };