@graphorin/agent 0.5.0

package/dist/factory.js

@@ -0,0 +1,1853 @@
+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 { 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 { 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";
+
+//#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) {
+	if (registry.listDeferred().length === 0) return;
+	if (registry.get(TOOL_SEARCH_NAME) !== void 0) return;
+	registry.register(createToolSearchTool({ registry }), {
+		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";
+/**
+* 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) {
+	if (registry.get(CODE_EXECUTE_NAME) !== void 0) return [];
+	const isApprovalGated = (t) => t.needsApproval === true || typeof t.needsApproval === "function";
+	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 { outcome } = await quietExecutor.executeOne({
+			call: {
+				toolCallId: newId("codecall"),
+				toolName: call.name,
+				args: call.args
+			},
+			runContext: ctx.runContext,
+			stepNumber: ctx.runContext.stepNumber
+		});
+		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.
+*/
+function classifyThrownProviderErrorKind(cause) {
+	if (typeof cause === "object" && cause !== null && "kind" in cause) switch (cause.kind) {
+		case "rate-limit-exceeded": return "rate-limit";
+	}
+	return "unknown";
+}
+/** Resolve a Zod-like schema to a JSON-Schema record (via `toJSON`), else pass an object through. */
+function projectSchema(raw) {
+	if (raw === null || raw === void 0) return void 0;
+	const toJson = raw.toJSON;
+	if (typeof toJson === "function") return toJson.call(raw);
+	if (typeof raw === "object") return raw;
+}
+function toolToDefinition(tool) {
+	const ts = tool;
+	const inputSchema = projectSchema(ts.inputSchema) ?? {};
+	const outputSchema = projectSchema(ts.outputSchema);
+	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.
+*/
+function countLeadingSystemMessages(messages) {
+	let i = 0;
+	while (i < messages.length && messages[i]?.role === "system") i += 1;
+	return i;
+}
+/**
+* Build a fresh {@link Agent} from the supplied configuration.
+*
+* @stable
+*/
+function createAgent(config) {
+	if (typeof config.name !== "string" || config.name.length === 0) throw new InvalidAgentConfigError("missing 'name'");
+	if (config.provider === void 0 || config.provider === null) throw new InvalidAgentConfigError("missing 'provider'");
+	if (config.outputType?.kind === "text" && config.outputType.schema !== void 0) throw new InvalidAgentConfigError("outputType.kind 'text' with a schema — did you mean kind: 'structured'?");
+	validatePreferredModel(config.preferredModel);
+	if (config.modelTierMap !== void 0) for (const [tier, spec] of Object.entries(config.modelTierMap)) {
+		if (!isModelHintLike(tier)) throw new InvalidPreferredModelError({ tier });
+		if (spec === void 0) continue;
+		if (!isModelSpecLike(spec)) throw new InvalidPreferredModelError(spec);
+	}
+	if (config.fallbackModels !== void 0) {
+		for (const spec of config.fallbackModels) if (!isModelSpecLike(spec)) throw new InvalidPreferredModelError(spec);
+	}
+	const agentId = newId("agent");
+	const tracer = config.tracer ?? NOOP_TRACER;
+	const stopWhen = config.stopWhen ?? isStepCount(50);
+	const fallbackPolicy = config.fallbackPolicy ?? {};
+	const handoffMap = /* @__PURE__ */ new Map();
+	for (const entry of config.handoffs ?? []) {
+		const isWrappedHandoff = typeof entry === "object" && entry !== null && "target" in entry;
+		const subAgent = isWrappedHandoff ? entry.target : entry;
+		const userFilter = isWrappedHandoff ? entry.inputFilter : void 0;
+		const filter = isDescribedFilter(userFilter) ? userFilter : void 0;
+		const toolName = `${HANDOFF_TOOL_PREFIX}${subAgent.config.name}`;
+		handoffMap.set(toolName, {
+			agent: subAgent,
+			filter
+		});
+	}
+	let pendingSteer = [];
+	const pendingFollowUp = [];
+	let abortController;
+	let pendingAbort;
+	let activeRunState;
+	/** AG-11: guards the one-in-flight-run-per-instance invariant. */
+	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);
+	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 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 } : {},
+		...opts?.quiet === true ? {} : { streamingSink: toolStreamingSink },
+		...config.maxParallelTools !== void 0 ? { maxParallelTools: config.maxParallelTools } : {}
+	});
+	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);
+		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` /
+	* `abort` / `compact` address "the run" with no run handle, so
+	* overlapping runs on one instance cannot be expressed safely — they
+	* would share the abort controller, steer queue, active-run ref and
+	* executor bridge. A second concurrent `run()` / `stream()` rejects
+	* with {@link ConcurrentRunError}; run-scoped state is reset on entry
+	* (a steer/abort queued after the previous run ended belongs to NO
+	* run) and cleared in a `finally` that also covers abandoned streams
+	* (consumer `break`) and thrown runs.
+	*/
+	async function* runLoop(input, options) {
+		if (runInFlight) throw new ConcurrentRunError();
+		runInFlight = true;
+		pendingSteer = [];
+		pendingAbort = void 0;
+		causalityMonitor?.reset();
+		try {
+			return yield* runLoopInner(input, options);
+		} finally {
+			runInFlight = false;
+			activeRunState = void 0;
+			while (pendingManualCompacts.length > 0) pendingManualCompacts.shift()?.resolve(noopCompactionResult("no-active-run"));
+		}
+	}
+	async function* runLoopInner(input, options) {
+		const { seed: rawSeed, resumed } = asMessages(input);
+		const seed = resumed === void 0 && pendingFollowUp.length > 0 ? [...pendingFollowUp.splice(0, pendingFollowUp.length), ...rawSeed] : rawSeed;
+		const sessionId = options.sessionId ?? config.sessionId ?? `session_${newId()}`;
+		const userId = options.userId ?? config.userId;
+		const localCtl = new AbortController();
+		abortController = localCtl;
+		const signal = localCtl.signal;
+		const parentSignal = options.signal;
+		const onParentAbort = () => localCtl.abort();
+		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"),
+			agentId,
+			sessionId,
+			...userId !== void 0 ? { userId } : {}
+		});
+		activeRunState = state;
+		if (resumed && state.taintSummary !== void 0) toolDataFlowGuard?.seedLedger(state.id, state.taintSummary);
+		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);
+		}
+		const finalSnapshot = { output: "" };
+		yield {
+			type: "agent.start",
+			runId: state.id,
+			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,
+				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;
+			}
+		}
+		const structuredInstruction = config.outputType?.kind === "structured" ? buildStructuredInstruction(config.outputType) : void 0;
+		const resumedApprovedCalls = [];
+		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
+					});
+				} 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 systemPrefixLength = countLeadingSystemMessages(messages);
+		const runContextBase = {
+			runId: state.id,
+			sessionId,
+			...userId !== void 0 ? { userId } : {},
+			agentId,
+			deps: options.deps ?? config.deps,
+			tracer,
+			signal,
+			usage: usageAcc,
+			stepNumber: 0,
+			messages,
+			state
+		};
+		if (resumed && (state.status === "awaiting_approval" || state.status === "failed")) return yield* finishRun(state, finalSnapshot);
+		if (resumed && resumedApprovedCalls.length > 0) {
+			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);
+		}
+		const promotedDeferred = /* @__PURE__ */ new Set();
+		if (resumed && state.promotedTools !== void 0) for (const name of state.promotedTools) promotedDeferred.add(name);
+		/**
+		* 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) {
+			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
+			});
+			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 = `Error: ${outcome.message}`;
+					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 text = 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);
+					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).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),
+				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
+			};
+		}
+		/**
+		* 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),
+					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;
+		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) {
+					const ev = externalEventQueue.shift();
+					if (ev !== void 0) yield ev;
+				}
+				if (signal.aborted) {
+					if (yield* emitCancellation()) return yield* finishRun(state, finalSnapshot);
+					break;
+				}
+				stepNumber += 1;
+				const stepStart = (/* @__PURE__ */ new Date()).toISOString();
+				if (pendingSteer.length > 0) {
+					for (const m of pendingSteer) {
+						messages.push(m);
+						state.messages.push(m);
+					}
+					pendingSteer = [];
+				}
+				yield {
+					type: "step.start",
+					stepNumber
+				};
+				yield* maybeAutoCompact();
+				const stepCtx = {
+					...runContextBase,
+					stepNumber,
+					messages
+				};
+				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);
+					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);
+				});
+				let stepTools;
+				if (isCodeMode) stepTools = [...codeModeAdvertised, ...handoffTools];
+				else {
+					const eagerTools = stepRegistry.listEager();
+					const promotedTools = promotedDeferred.size === 0 ? [] : orderPromotedTools(promotedDeferred, stepRegistry.listDeferred());
+					stepTools = [
+						...eagerTools,
+						...promotedTools,
+						...handoffTools
+					];
+				}
+				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: structuredInstruction === void 0 ? messages : [...messages, {
+						role: "system",
+						content: structuredInstruction
+					}],
+					...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 } : {},
+					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 = [];
+				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(baseRequest);
+						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 = {
+								promptTokens: providerStepUsage.promptTokens + out.usage.promptTokens,
+								completionTokens: providerStepUsage.completionTokens + out.usage.completionTokens,
+								totalTokens: providerStepUsage.totalTokens + out.usage.totalTokens,
+								...out.usage.reasoningTokens !== void 0 || providerStepUsage.reasoningTokens !== void 0 ? { reasoningTokens: (providerStepUsage.reasoningTokens ?? 0) + (out.usage.reasoningTokens ?? 0) } : {}
+							};
+							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 (!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
+						}];
+						stepUsage.promptTokens += providerStepUsage.promptTokens;
+						stepUsage.completionTokens += providerStepUsage.completionTokens;
+						stepUsage.totalTokens += providerStepUsage.totalTokens;
+						if (providerStepUsage.reasoningTokens !== void 0) stepUsage.reasoningTokens = (stepUsage.reasoningTokens ?? 0) + providerStepUsage.reasoningTokens;
+						break;
+					}
+				}
+				if (signal.aborted && !modelSucceeded) {
+					yield* emitCancellation();
+					return yield* finishRun(state, finalSnapshot);
+				}
+				if (!modelSucceeded) {
+					yield {
+						type: "agent.error",
+						error: {
+							message: "all configured providers failed without finishing",
+							code: "no-provider-completed"
+						}
+					};
+					state.status = "failed";
+					state.error = {
+						message: "no provider completed",
+						code: "no-provider-completed"
+					};
+					return yield* finishRun(state, finalSnapshot);
+				}
+				usageAcc.add(lastModelId, stepUsage);
+				addModelUsage(state, lastModelId, stepUsage);
+				state.usage.promptTokens += stepUsage.promptTokens;
+				state.usage.completionTokens += stepUsage.completionTokens;
+				state.usage.totalTokens += stepUsage.totalTokens;
+				if (stepUsage.reasoningTokens !== void 0) state.usage.reasoningTokens = (state.usage.reasoningTokens ?? 0) + stepUsage.reasoningTokens;
+				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 (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 handoffCalls = finalCalls.filter((c) => handoffMap.has(c.toolName));
+				if (handoffCalls.length > 1) throw new MultipleHandoffsInStepError(handoffCalls.map((c) => c.toolName));
+				const stepRecord = {
+					stepNumber,
+					startedAt: stepStart,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					usage: stepUsage,
+					toolCalls: [],
+					agentId: state.currentAgentId
+				};
+				state.steps.push(stepRecord);
+				lastStepCalledToolNames = finalCalls.map((c) => c.toolName);
+				if (textBuffer.length > 0 && !leakBlocked) {
+					finalSnapshot.output = textBuffer;
+					yield {
+						type: "text.complete",
+						text: textBuffer
+					};
+				}
+				if (finalCalls.length > 0) {
+					const execRunContext = {
+						...runContextBase,
+						stepNumber,
+						messages
+					};
+					let batch = [];
+					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,
+								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
+							});
+							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 = `Error: ${toolError.message}`;
+								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;
+						}
+						if (await invokeNeedsApproval(stepRegistry.get(call.toolName), call.args, 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);
+							state.status = "awaiting_approval";
+							const taintSnap = toolDataFlowGuard?.snapshotLedger(state.id);
+							if (taintSnap !== void 0) state.taintSummary = taintSnap;
+							if (promotedDeferred.size > 0) state.promotedTools = [...promotedDeferred];
+							yield {
+								type: "tool.approval.requested",
+								toolCallId: call.toolCallId
+							};
+							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);
+						}
+						batch.push(call);
+					}
+					if (batch.length > 0) yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
+				}
+				yield {
+					type: "step.end",
+					stepNumber,
+					usage: stepUsage
+				};
+				if (finalCalls.length === 0) {
+					state.status = "completed";
+					break;
+				}
+			}
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : String(cause);
+			const code = cause instanceof AgentRuntimeError ? cause.code : "unknown";
+			yield {
+				type: "agent.error",
+				error: {
+					message,
+					code
+				}
+			};
+			state.status = "failed";
+			state.error = {
+				message,
+				code
+			};
+			return yield* finishRun(state, finalSnapshot);
+		} finally {
+			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;
+		}
+		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* finishRun(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 steer = (message) => {
+		const { seed } = asMessages(message);
+		pendingSteer.push(...seed);
+		if (activeRunState !== void 0) externalEventQueue.push({
+			type: "agent.steered",
+			runId: activeRunState.id
+		});
+	};
+	const followUp = (message) => {
+		const { seed } = asMessages(message);
+		pendingFollowUp.push(...seed);
+		if (activeRunState !== void 0) externalEventQueue.push({
+			type: "agent.followup.queued",
+			runId: activeRunState.id
+		});
+	};
+	const abort = (options) => {
+		pendingAbort = options ?? {};
+		abortController?.abort();
+	};
+	const toTool = (options = {}) => {
+		const exposeTurns = options.exposeTurns ?? "final";
+		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 } : {}
+				};
+				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}` : ""}`);
+					return turns.join("\n\n");
+				}
+				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}` : ""}`);
+				if (exposeTurns === "none") return "";
+				return result.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;
+		}
+	};
+	config.sensitivity;
+	return {
+		id: agentId,
+		config,
+		stream,
+		run,
+		steer,
+		followUp,
+		abort,
+		toTool,
+		compact,
+		fanOut,
+		progress,
+		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 };
+}
+
+//#endregion
+export { createAgent };
+//# sourceMappingURL=factory.js.map