@warlock.js/core 4.8.0 → 4.8.1

package/esm/ai/src/agent/agent.mjs

@@ -1,1276 +0,0 @@
-import { AIError } from "../errors/ai-error.mjs";
-import { AgentExecutionError } from "../errors/agent-execution-error.mjs";
-import { AgentCancelledError } from "../errors/agent-cancelled-error.mjs";
-import { AgentMaxTripsError } from "../errors/agent-max-trips-error.mjs";
-import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
-import "../errors/index.mjs";
-import { computeCost, mergeUsage } from "../utils/compute-cost.mjs";
-import { extractJsonPayload } from "../utils/extract-json-payload.mjs";
-import { extractJsonLenient } from "../utils/extract-json-lenient.mjs";
-import { generateRunId } from "../utils/generate-run-id.mjs";
-import { captureChildReport } from "../utils/run-context.mjs";
-import { safeJsonParse } from "../utils/safe-json-parse.mjs";
-import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
-import "../utils/index.mjs";
-import { runEval } from "../eval/eval-runner.mjs";
-import { runPipeline } from "../middleware/pipeline.mjs";
-import "../middleware/index.mjs";
-import { notifyObservers } from "../observe/resolve-observers.mjs";
-import { skills } from "../skills/skills.mjs";
-import "../skills/index.mjs";
-import { normalizeAgentTools } from "../tool/executable-as-tool.mjs";
-import { buildAgentInputMessages } from "./agent-input-builder.mjs";
-import { logAgentEvent } from "./agent-log-event.mjs";
-import { createAgentStream } from "./agent-stream.mjs";
-import { agentEventToStreamEvent } from "./agent-to-stream-event.mjs";
-import { JsonStreamGuard } from "./json-stream-guard.mjs";
-import { computeAgentSignature } from "./signature.mjs";
-import { deleteAgentSnapshot, loadAgentSnapshotForResume, persistAgentSnapshot } from "./snapshot.mjs";
-import { log } from "@warlock.js/logger";
-
-//#region ../@warlock.js/ai/src/agent/agent.ts
-const LOG_MODULE = "ai.agent";
-/**
-* Duck-type a value as a {@link SkillsContract} (vs a raw `SkillsConfig`).
-* A contract exposes the agent-facing methods; a config is a plain spec.
-* Checking `catalogPrompt` is sufficient to discriminate the two shapes.
-*/
-function isSkillsContract(value) {
-	return typeof value === "object" && value !== null && typeof value.catalogPrompt === "function";
-}
-/**
-* Detect abort-flavored errors surfaced by SDK HTTP layers — the
-* DOM `AbortError`, axios `ERR_CANCELED`, node-fetch's own
-* `AbortError`. Used to classify them as cancellation rather than
-* generic agent-execution failures.
-*/
-function isAbortLike(err) {
-	if (!err || typeof err !== "object") return false;
-	const e = err;
-	return e.name === "AbortError" || e.code === "ERR_CANCELED" || e.code === "ABORT_ERR";
-}
-/**
-* Readable synthetic name for agents constructed without an explicit
-* `name`. Format: `anon_<provider>_<model>[_<tool1>+<tool2>+...]` —
-* deterministic (same config → same name across restarts) and
-* human-readable in logs / workflow snapshots.
-*
-* Keeps drift detection honest for the `ai.agent({ model })`
-* one-liner without punishing it with a hashed id nobody can read.
-*/
-function synthesizeAgentName(config) {
-	const provider = config.model?.provider ?? "unknown";
-	const model = config.model?.name ?? "unknown";
-	const tools = (config.tools ?? []).map((tool) => tool.name).sort().join("+");
-	const base = `anon_${sanitize(provider)}_${sanitize(model)}`;
-	return tools ? `${base}_${sanitize(tools, { keepPlus: true })}` : base;
-}
-function sanitize(value, opts = {}) {
-	const allowed = opts.keepPlus ? /[^a-zA-Z0-9._+-]/g : /[^a-zA-Z0-9._-]/g;
-	return value.replace(allowed, "-");
-}
-/**
-* Authoring-time check on the middleware array. Throws an
-* `AgentExecutionError` with `context: { authoring: true }` the
-* moment an invalid entry is found — the agent factory surface is
-* where config bugs should surface, not ten trips into a run.
-*
-* Validates:
-* - Every entry is a non-null object with a non-empty string `name`.
-* - No two entries share the same `name` (would silently collide on
-*   `ctx.state` keys and produce impossible-to-debug behavior).
-*
-* Does NOT validate that hook maps contain callable functions —
-* that would catch late-binding bugs but also reject legitimate
-* patterns like `before` being conditionally `undefined`. Runtime
-* dispatch handles missing hooks safely.
-*/
-function validateMiddleware(middleware) {
-	if (!middleware || middleware.length === 0) return;
-	const seen = /* @__PURE__ */ new Set();
-	for (let index = 0; index < middleware.length; index++) {
-		const entry = middleware[index];
-		if (!entry || typeof entry !== "object") throw new AgentExecutionError(`middleware[${index}] must be an object; received ${entry === null ? "null" : typeof entry}`, { context: {
-			authoring: true,
-			index
-		} });
-		const name = entry.name;
-		if (typeof name !== "string" || name.length === 0) throw new AgentExecutionError(`middleware[${index}] must have a non-empty string "name"`, { context: {
-			authoring: true,
-			index
-		} });
-		if (seen.has(name)) throw new AgentExecutionError(`duplicate middleware name "${name}" — each middleware needs a unique name so ctx.state keys do not collide`, { context: {
-			authoring: true,
-			index,
-			name
-		} });
-		seen.add(name);
-	}
-}
-/**
-* Normalize the public `judge` flag (`boolean | JudgeConfig | undefined`)
-* into a resolved {@link JudgeConfig} or `undefined` when the preset is
-* off. `true` ⇒ all defaults (`{}`); a partial config fills missing fields
-* from the defaults; `false` / absent ⇒ `undefined` (judge mode off).
-*/
-function resolveJudgeConfig(judge) {
-	if (!judge) return;
-	return { repairAttempts: (judge === true ? {} : judge).repairAttempts ?? 2 };
-}
-/**
-* Creates an executable AI agent from the given configuration.
-*
-* The agent runs a bounded trip loop: each trip calls the model, dispatches
-* any requested tool calls, then loops until the model stops or `maxTrips`
-* is reached. Each `execute()` / `stream()` call spawns a fresh internal
-* `Execution` instance — the factory itself holds no state across calls.
-*
-* `execute()` never throws — any error is attached to the returned result
-* under `result.error`. `stream()` surfaces errors both on the terminal
-* `error` stream event and via the `stream.result` promise.
-*
-* @example
-* const myAgent = agent({
-*   model: openai.model({ name: "gpt-4o" }),
-*   systemPrompt: "You are a helpful assistant.",
-*   tools: [searchTool],
-* });
-*
-* const result = await myAgent.execute("What is the capital of Egypt?");
-*
-* @example
-* const stream = myAgent.stream("Write a haiku about Cairo.");
-*
-* for await (const event of stream) {
-*   if (event.type === "streaming") process.stdout.write(event.delta);
-* }
-*
-* const result = await stream.result;
-*/
-function agent(config) {
-	validateMiddleware(config.middleware);
-	const isAnonymous = !config.name || typeof config.name !== "string";
-	const tools = normalizeAgentTools(config.tools);
-	const name = isAnonymous ? synthesizeAgentName({
-		...config,
-		tools
-	}) : config.name;
-	const skillsLib = config.skills ? isSkillsContract(config.skills) ? config.skills : skills(config.skills) : void 0;
-	const signature = computeAgentSignature({
-		name: isAnonymous ? void 0 : name,
-		version: config.version,
-		model: {
-			name: config.model?.name,
-			provider: config.model?.provider
-		},
-		tools,
-		maxTrips: config.maxTrips,
-		output: config.output
-	});
-	const resolvedConfig = {
-		...config,
-		name,
-		tools,
-		skillsLib,
-		signature
-	};
-	const instanceHandlers = /* @__PURE__ */ new Map();
-	function on(event, handler) {
-		const existing = instanceHandlers.get(event);
-		const bucket = existing ?? /* @__PURE__ */ new Set();
-		if (!existing) instanceHandlers.set(event, bucket);
-		bucket.add(handler);
-		return () => off(event, handler);
-	}
-	function off(event, handler) {
-		const bucket = instanceHandlers.get(event);
-		if (!bucket) return;
-		bucket.delete(handler);
-		if (bucket.size === 0) instanceHandlers.delete(event);
-	}
-	const agentContract = {
-		name,
-		isAnonymous,
-		description: config.description,
-		signature,
-		async execute(input, options) {
-			return new Execution(resolvedConfig, input, options, void 0, instanceHandlers).run();
-		},
-		stream(input, options) {
-			const { controller, stream } = createAgentStream();
-			new Execution(resolvedConfig, input, options, controller, instanceHandlers).run();
-			return stream;
-		},
-		async resume(runId, options) {
-			const snapshot = await loadAgentSnapshotForResume({
-				durable: resolvedConfig.durable,
-				agentName: name,
-				signature,
-				runId,
-				options
-			});
-			return new Execution(resolvedConfig, snapshot.input, {
-				...options,
-				runId
-			}, void 0, instanceHandlers, snapshot).run();
-		},
-		on,
-		off,
-		eval(options) {
-			return runEval(agentContract, options);
-		}
-	};
-	return agentContract;
-}
-/**
-* Build a judge-safe agent — sugar for `agent({ ...config, judge })`.
-*
-* Use this for LLM-as-judge graders and verdict classifiers running on
-* models that may emit corrupted structured output (e.g. the Amazon Nova
-* family). The returned agent parses verdicts leniently (tolerates fenced
-* ` ```json ` blocks + surrounding prose), auto-enables a couple of repair
-* re-asks, and never throws on a parse miss — surfacing `result.error` with
-* `result.data` left undefined so a flaky judge degrades gracefully.
-*
-* See {@link AgentConfig.judge} for the full behavior + the resilience-over-
-* strictness trade-off.
-*
-* @param config - Any agent config (model, system prompt, output schema, …).
-* @param judge - Optional fine-tuning ({@link JudgeConfig}); defaults to `true`.
-*
-* @example
-* const grader = ai.agent.judge({
-*   model: nova.model({ name: "amazon.nova-pro-v1:0" }),
-*   systemPrompt: "Grade the answer. Respond with JSON only.",
-*   output: verdictSchema,
-* });
-*
-* const result = await grader.execute(prompt);
-* if (result.error) {
-*   // graceful default — the judge couldn't produce a clean verdict
-* }
-*/
-function judgeAgent(config, judge = true) {
-	return agent({
-		...config,
-		judge
-	});
-}
-agent.judge = judgeAgent;
-/**
-* Per-call driver that owns the full lifecycle of a single
-* `agent.execute()` or `agent.stream()` invocation.
-*
-* **Role.** An `Execution` is the short-lived state container and phase
-* orchestrator for one agent run. The public `agent()` factory stays purely
-* functional — all mutable bookkeeping (trips, tool calls, usage totals,
-* message history, terminal error, parsed output) lives here so each call
-* gets a fresh, isolated instance.
-*
-* **Responsibility.**
-* - Owns: building the initial message list, driving the bounded trip loop,
-*   dispatching tool calls safely, parsing the final output against the
-*   caller's schema, emitting lifecycle events (to both the user handler
-*   and, in stream mode, the `StreamController`), and producing the
-*   `AgentResult`.
-* - Does NOT own: how the model produces responses (delegated to
-*   `ModelContract.complete` / `ModelContract.stream`), how tools execute
-*   (delegated to `ToolContract.invoke`), the async-queue plumbing for
-*   streaming (delegated to `createAgentStream`), or any cross-call state
-*   (factory-level concerns live in `agent()`).
-*
-* Streaming mode is opt-in via the fourth constructor argument: pass a
-* `StreamController` and every event is mirrored into it while model calls
-* are driven via `model.stream()` instead of `model.complete()`. The public
-* contract of `execute()` says it never throws — `Execution` enforces that
-* by funneling every unexpected error into `this.error` and returning a
-* well-formed result regardless of what went wrong.
-*
-* Not exported — consumers interact only with the `agent()` factory (see
-* §4.2 of code-style.md — "per-call execution state across phases").
-*
-* @example
-* // Non-streaming — inside agent.execute():
-* const result = await new Execution(config, input, options).run();
-*
-* @example
-* // Streaming — inside agent.stream():
-* const { controller, stream } = createAgentStream();
-* void new Execution(config, input, options, controller).run();
-* return stream;
-*/
-var Execution = class {
-	constructor(config, input, options, streamController, instanceHandlers, resumeFrom) {
-		this.config = config;
-		this.input = input;
-		this.options = options;
-		this.streamController = streamController;
-		this.instanceHandlers = instanceHandlers;
-		this.resumeFrom = resumeFrom;
-		this.trips = [];
-		this.toolCalls = [];
-		this.usage = {
-			input: 0,
-			output: 0,
-			total: 0
-		};
-		this.messages = [];
-		this.start = performance.now();
-		this.logger = log;
-		this.warnedHandlerEvents = /* @__PURE__ */ new Set();
-		this.middlewareState = /* @__PURE__ */ new Map();
-		this.maxTrips = config.maxTrips ?? 10;
-		this.middleware = config.middleware ?? [];
-		this.judgeConfig = resolveJudgeConfig(config.judge);
-		this.runId = resumeFrom?.runId ?? options?.runId ?? generateRunId("agent");
-		this.startedAt = resumeFrom ? new Date(resumeFrom.startedAt) : /* @__PURE__ */ new Date();
-		if (resumeFrom) {
-			this.messages.push(...resumeFrom.messages);
-			this.trips.push(...resumeFrom.trips);
-			this.toolCalls.push(...resumeFrom.toolCalls);
-			mergeUsage(this.usage, resumeFrom.usage);
-			this.systemPrompt = resumeFrom.systemPrompt;
-			this.responseSchema = resumeFrom.responseSchema;
-			this.promptName = resumeFrom.promptName;
-			this.promptVersion = resumeFrom.promptVersion;
-		}
-		const skillTools = config.skillsLib ? normalizeAgentTools(config.skillsLib.tools(this.runId)) ?? [] : [];
-		this.effectiveTools = [...config.tools ?? [], ...skillTools];
-	}
-	/**
-	* Base middleware context shared by every level. `state` is the
-	* single mutable bag threaded through `execute`, `trip`, and `tool`
-	* hooks for the lifetime of this execution — fresh per `execute()`
-	* call, never reused across runs.
-	*/
-	buildExecuteContext() {
-		return {
-			agent: {
-				name: this.config.name ?? this.config.model.name,
-				isAnonymous: !this.config.name
-			},
-			model: {
-				name: this.config.model.name,
-				provider: this.config.model.provider
-			},
-			input: this.input,
-			options: this.options,
-			state: this.middlewareState,
-			signal: this.options?.signal
-		};
-	}
-	/**
-	* Entry point for a single agent execution. Wraps the real work
-	* (`runCore`) in the `execute`-level middleware pipeline, then
-	* emits the terminal `agent.completed` / `agent.error` events and
-	* closes the stream (if any) with the post-pipeline result — so
-	* middleware that short-circuits or transforms the final result
-	* still produces a well-formed public outcome.
-	*
-	* Must never throw: any error that escapes the pipeline is
-	* converted into an `AgentResult` with `error` populated before
-	* returning, preserving the `agent.execute()` public contract.
-	*/
-	async run() {
-		const context = this.buildExecuteContext();
-		let result;
-		try {
-			result = await runPipeline(this.middleware, "execute", context, () => this.runCore(), this.logger);
-		} catch (thrown) {
-			this.error = this.toAIError(thrown);
-			result = this.buildResult();
-		}
-		if (result.error) this.emit("agent.error", { error: result.error });
-		this.emit("agent.completed", { result });
-		await this.fireCompleteHook(result);
-		await notifyObservers(this.config.observe, result.report);
-		captureChildReport(result.report);
-		this.streamController?.end(result);
-		return result;
-	}
-	/**
-	* Inner body wrapped by the `execute`-level pipeline. Drives the
-	* full lifecycle — build messages → emit starting → run trip loop
-	* → parse output → build result. Catches any unexpected throw and
-	* funnels it into `this.error` so the returned result is always
-	* well-formed; `execute`-level `after` hooks receive the result,
-	* with `error` populated when things went wrong.
-	*/
-	async runCore() {
-		if (this.resumeFrom && this.resumeFrom.status === "completed") return this.rebuildResumedResult(this.resumeFrom);
-		try {
-			if (!this.resumeFrom) {
-				await this.buildInitialMessages();
-				this.emit("agent.starting", { input: this.input });
-			}
-			await this.runTripLoop();
-			if (await this.parseOutput() === "failed" && this.resolveRepairAttempts() > 0) await this.runRepairLoop();
-		} catch (thrown) {
-			this.error = this.toAIError(thrown);
-		}
-		await this.checkpoint(this.resolveSnapshotStatus());
-		if (!this.error && this.config.durable?.deleteOnComplete) {
-			const outcome = await deleteAgentSnapshot({
-				durable: this.config.durable,
-				runId: this.runId
-			});
-			if (!outcome.ok) this.logger.warn(LOG_MODULE, "snapshot.delete.failed", "durable snapshot delete failed", {
-				runId: this.runId,
-				error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error)
-			});
-		}
-		return this.buildResult();
-	}
-	/**
-	* Resolve the system prompt (string or `SystemPromptContract`), merge
-	* placeholders from config + execute options, inject a structured-output
-	* instruction when the caller wants typed output but the model can't
-	* enforce it natively, prepend any conversation history, and append the
-	* user input. Produces the initial `messages` array the first trip sends
-	* to the model. Runs exactly once per execution.
-	*/
-	async buildInitialMessages() {
-		const { messages, responseSchema, systemPrompt, promptName, promptVersion } = await buildAgentInputMessages({
-			config: this.config,
-			input: this.input,
-			options: this.options
-		});
-		this.messages.push(...messages);
-		this.responseSchema = responseSchema;
-		this.systemPrompt = systemPrompt;
-		this.promptName = promptName;
-		this.promptVersion = promptVersion;
-		await this.injectSkills();
-	}
-	/**
-	* Prepend the skills library's contribution to the system prompt — the
-	* always-injected metadata catalog first, then (only under `inject`) the
-	* preloaded skill bodies, then the developer's resolved system prompt.
-	* Never replaces the developer prompt.
-	*
-	* No-op when no skills library is attached. `catalogPrompt` returns `""`
-	* when nothing is in scope and `preload` returns `[]` when `inject` is
-	* omitted (the default), so the prepend is a no-op in those cases too.
-	*
-	* Awaited inside `buildInitialMessages`, which runs inside `runCore`'s
-	* try/catch — a source/embedder failure funnels into `this.error` like
-	* any other build failure, no new error handling needed.
-	*/
-	async injectSkills() {
-		const lib = this.config.skillsLib;
-		if (!lib) return;
-		const catalogBlock = await lib.catalogPrompt(this.input);
-		const preloaded = await lib.preload(this.input);
-		const blocks = [];
-		if (catalogBlock) blocks.push(catalogBlock);
-		for (const record of preloaded) if (record.body) blocks.push(record.body);
-		if (blocks.length === 0) return;
-		const prefix = blocks.join("\n\n");
-		const merged = this.systemPrompt ? `${prefix}\n\n${this.systemPrompt}` : prefix;
-		this.systemPrompt = merged;
-		const firstMessage = this.messages[0];
-		if (firstMessage?.role === "system") firstMessage.content = merged;
-		else this.messages.unshift({
-			role: "system",
-			content: merged
-		});
-	}
-	/**
-	* Drive sequential trips up to `maxTrips`. Each trip may stop the loop
-	* naturally (model returned a non-tool-call finish), abort it (model
-	* threw), or continue it (model requested tools). When the loop exits
-	* after the cap without a natural stop, records a "Max trips exceeded"
-	* error so the caller can distinguish runaway tool loops from a real result.
-	*/
-	async runTripLoop() {
-		for (let tripIndex = this.trips.length; tripIndex < this.maxTrips; tripIndex++) {
-			if (this.options?.signal?.aborted) {
-				this.error = this.makeCancelledError();
-				return;
-			}
-			const tripInput = tripIndex === 0 ? this.input : "[tool results]";
-			const outcome = await this.runTrip(tripIndex, tripInput);
-			if (outcome === "error" || outcome === "stop") return;
-		}
-		if (this.trips[this.trips.length - 1]?.finishReason === "tool_calls") this.error = new AgentMaxTripsError("Max trips exceeded", { maxTrips: this.maxTrips });
-	}
-	/**
-	* Execute one round-trip to the model. Aggregates usage into the running
-	* total, dispatches any requested tool calls, appends the assistant +
-	* tool-result messages for the next trip, and records an `LLMTrip`.
-	* Returns an outcome that tells `runTripLoop` whether to continue, stop,
-	* or abort.
-	*/
-	async runTrip(tripIndex, tripInput) {
-		this.emit("agent.trip.started", {
-			tripIndex,
-			input: tripInput
-		});
-		const tripStartedAt = /* @__PURE__ */ new Date();
-		const tripStart = performance.now();
-		let response;
-		try {
-			response = await this.runTripThroughPipeline(tripIndex);
-		} catch (thrown) {
-			this.error = this.toAIError(thrown);
-			const failedTrip = {
-				index: tripIndex,
-				input: tripInput,
-				output: "",
-				finishReason: "error",
-				startedAt: tripStartedAt.toISOString(),
-				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-				duration: performance.now() - tripStart,
-				usage: {
-					input: 0,
-					output: 0,
-					total: 0
-				},
-				error: this.error
-			};
-			this.trips.push(failedTrip);
-			this.emit("agent.trip.completed", { trip: failedTrip });
-			this.emit("agent.error", { error: this.error });
-			await this.checkpoint("failed");
-			return "error";
-		}
-		if (response.usage.cost === void 0) response.usage.cost = computeCost(response.usage, this.config.model.pricing);
-		mergeUsage(this.usage, response.usage);
-		await this.fireUsageHook(tripIndex, response.usage);
-		const isToolCallTrip = response.finishReason === "tool_calls" && response.toolCalls !== void 0 && response.toolCalls.length > 0;
-		const tripToolCalls = [];
-		if (isToolCallTrip) {
-			this.messages.push({
-				role: "assistant",
-				content: response.content,
-				toolCalls: response.toolCalls
-			});
-			for (const toolCallRequest of response.toolCalls) {
-				const record = await this.dispatchToolCall(toolCallRequest, tripIndex);
-				tripToolCalls.push(record);
-			}
-		}
-		const trip = {
-			index: tripIndex,
-			input: tripInput,
-			output: response.content,
-			finishReason: response.finishReason,
-			startedAt: tripStartedAt.toISOString(),
-			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			duration: performance.now() - tripStart,
-			usage: response.usage,
-			toolCalls: tripToolCalls.length > 0 ? tripToolCalls : void 0
-		};
-		this.trips.push(trip);
-		this.emit("agent.trip.completed", { trip });
-		await this.checkpoint("running");
-		if (!isToolCallTrip) return "stop";
-		return response.toolCalls.every((request) => {
-			return this.effectiveTools.find((tool) => tool.name === request.name)?.mode === "silent";
-		}) ? "stop" : "continue";
-	}
-	/**
-	* Route `getModelResponse` through the `trip`-level middleware
-	* pipeline. `trip.before` hooks can short-circuit the trip by
-	* returning a synthetic `ModelResponse` (semantic cache hit).
-	* `trip.after` hooks can transform the response before the trip
-	* record is built or any tool calls are dispatched. `trip.onError`
-	* hooks can recover from provider failures (fallback chain).
-	*/
-	async runTripThroughPipeline(tripIndex) {
-		const context = {
-			...this.buildExecuteContext(),
-			tripIndex,
-			messages: this.messages
-		};
-		return await runPipeline(this.middleware, "trip", context, () => this.getModelResponse(tripIndex), this.logger);
-	}
-	/**
-	* Produce the `ModelResponse` for the current trip. In non-streaming
-	* mode, delegates straight to `model.complete()`. In streaming mode,
-	* drains `model.stream()` while emitting `streaming` events per delta
-	* and accumulates the chunks into the same `ModelResponse` shape, so the
-	* rest of the trip pipeline (tool dispatch, trip record, usage
-	* aggregation) stays identical between the two modes.
-	*/
-	async getModelResponse(tripIndex) {
-		const callOptions = {
-			...this.config.modelOptions,
-			tools: this.effectiveTools,
-			...this.responseSchema ? { responseSchema: this.responseSchema } : {},
-			...this.options?.signal ? { signal: this.options.signal } : {}
-		};
-		if (!this.streamController) return this.config.model.complete(this.messages, callOptions);
-		let content = "";
-		let finishReason = "stop";
-		let usage = {
-			input: 0,
-			output: 0,
-			total: 0
-		};
-		const toolCalls = [];
-		const recoveredCalls = [];
-		const guardConfig = this.resolveStreamingToolGuard();
-		const guard = guardConfig ? new JsonStreamGuard({
-			tools: this.effectiveTools,
-			maxBufferBytes: guardConfig.maxBufferBytes,
-			onSafeDelta: (delta) => {
-				content += delta;
-				this.emit("agent.trip.streaming", {
-					delta,
-					tripIndex
-				});
-			},
-			onRecoveredCall: (request) => {
-				recoveredCalls.push(request);
-			}
-		}) : void 0;
-		for await (const chunk of this.config.model.stream(this.messages, callOptions)) {
-			if (this.options?.signal?.aborted) throw this.makeCancelledError();
-			if (chunk.type === "delta") {
-				if (guard) await guard.feed(chunk.content);
-				else {
-					content += chunk.content;
-					this.emit("agent.trip.streaming", {
-						delta: chunk.content,
-						tripIndex
-					});
-				}
-				continue;
-			}
-			if (chunk.type === "tool-call") {
-				toolCalls.push({
-					id: chunk.id,
-					name: chunk.name,
-					input: chunk.input,
-					...chunk.providerMetadata ? { providerMetadata: chunk.providerMetadata } : {}
-				});
-				continue;
-			}
-			finishReason = chunk.finishReason;
-			usage = chunk.usage;
-		}
-		if (guard) await guard.finalize();
-		const dedupedRecovered = recoveredCalls.filter((recovered) => !isDuplicateToolCall(recovered, toolCalls));
-		const mergedToolCalls = [...toolCalls, ...dedupedRecovered];
-		const resolvedFinishReason = dedupedRecovered.length > 0 && finishReason === "stop" ? "tool_calls" : finishReason;
-		return {
-			content,
-			finishReason: resolvedFinishReason,
-			usage,
-			toolCalls: mergedToolCalls.length > 0 ? mergedToolCalls : void 0
-		};
-	}
-	/**
-	* Resolve the effective `streamingToolGuard` for this trip.
-	* Per-call options win over the agent-level config when the key is
-	* explicitly present on options (including the explicit `undefined`
-	* "disable for this call" form). Returns `undefined` when no guard
-	* should run.
-	*/
-	resolveStreamingToolGuard() {
-		if (this.options !== void 0 && Object.prototype.hasOwnProperty.call(this.options, "streamingToolGuard")) return this.options.streamingToolGuard;
-		return this.config.streamingToolGuard;
-	}
-	/**
-	* Dispatch a single tool call requested by the model. Looks up the tool
-	* by name, invokes it via the safe `ToolContract.invoke` entry, pushes a
-	* matching tool-result message into `this.messages` so the next trip can
-	* see it, and emits the right lifecycle event (`tool-called` on success,
-	* `tool-calling-failed` when the tool is unregistered or invoke returned
-	* an error). Never throws — always returns a `ToolCall` record.
-	*/
-	async dispatchToolCall(toolCallRequest, tripIndex) {
-		const registeredTool = this.effectiveTools.find((tool) => tool.name === toolCallRequest.name);
-		if (!registeredTool) {
-			const error = new AgentExecutionError(`Tool not registered: ${toolCallRequest.name}`, { context: {
-				toolName: toolCallRequest.name,
-				tripIndex
-			} });
-			const nowIso = (/* @__PURE__ */ new Date()).toISOString();
-			const record = {
-				runId: generateRunId("tool"),
-				rootRunId: this.runId,
-				name: toolCallRequest.name,
-				type: "tool",
-				status: "failed",
-				startedAt: nowIso,
-				endedAt: nowIso,
-				duration: 0,
-				usage: {
-					input: 0,
-					output: 0,
-					total: 0
-				},
-				children: [],
-				tripIndex,
-				input: toolCallRequest.input,
-				error,
-				...toolCallRequest.recoveredFrom ? { recoveredFrom: toolCallRequest.recoveredFrom } : {}
-			};
-			this.toolCalls.push(record);
-			this.messages.push({
-				role: "tool",
-				toolCallId: toolCallRequest.id,
-				content: JSON.stringify({ error: error.message })
-			});
-			this.emit("agent.tool.failed", {
-				tool: {
-					name: toolCallRequest.name,
-					description: "(unregistered tool — no description available)"
-				},
-				input: toolCallRequest.input,
-				error,
-				tripIndex
-			});
-			return record;
-		}
-		const toolMeta = {
-			name: registeredTool.name,
-			description: registeredTool.description,
-			action: resolveToolAction(registeredTool, toolCallRequest.input)
-		};
-		this.emit("agent.tool.calling", {
-			tool: toolMeta,
-			input: toolCallRequest.input,
-			tripIndex
-		});
-		const toolContext = {
-			...this.buildExecuteContext(),
-			tripIndex,
-			messages: this.messages,
-			tool: {
-				name: registeredTool.name,
-				description: registeredTool.description,
-				mode: registeredTool.mode
-			},
-			request: toolCallRequest
-		};
-		const runSignal = this.options?.signal;
-		const dispatchToolCtx = runSignal ? {
-			artifacts: this.options?.toolCtx?.artifacts ?? {},
-			...this.options?.toolCtx,
-			signal: runSignal
-		} : this.options?.toolCtx;
-		let invokeResult;
-		try {
-			invokeResult = await runPipeline(this.middleware, "tool", toolContext, () => registeredTool.invoke(toolCallRequest.input, dispatchToolCtx), this.logger);
-		} catch (thrown) {
-			const error = this.toAIError(thrown);
-			const nowIso = (/* @__PURE__ */ new Date()).toISOString();
-			const emptyUsage = {
-				input: 0,
-				output: 0,
-				total: 0
-			};
-			const failedRunId = generateRunId("tool");
-			invokeResult = {
-				error,
-				usage: emptyUsage,
-				report: {
-					runId: failedRunId,
-					rootRunId: failedRunId,
-					name: registeredTool.name,
-					version: registeredTool.version,
-					type: "tool",
-					status: "failed",
-					startedAt: nowIso,
-					endedAt: nowIso,
-					duration: 0,
-					usage: emptyUsage,
-					children: []
-				}
-			};
-		}
-		const innerReport = invokeResult.report;
-		const isComposite = innerReport.type !== "tool";
-		const record = {
-			runId: innerReport.runId,
-			rootRunId: this.runId,
-			name: toolCallRequest.name,
-			version: registeredTool.version,
-			type: "tool",
-			status: innerReport.status,
-			startedAt: innerReport.startedAt,
-			endedAt: innerReport.endedAt,
-			duration: innerReport.duration,
-			usage: invokeResult.usage,
-			children: isComposite ? [innerReport] : innerReport.children,
-			tripIndex,
-			input: toolCallRequest.input,
-			output: invokeResult.data,
-			error: invokeResult.error,
-			...toolCallRequest.recoveredFrom ? { recoveredFrom: toolCallRequest.recoveredFrom } : {}
-		};
-		this.toolCalls.push(record);
-		mergeUsage(this.usage, invokeResult.usage);
-		this.messages.push({
-			role: "tool",
-			toolCallId: toolCallRequest.id,
-			content: invokeResult.error ? JSON.stringify({ error: invokeResult.error.message }) : JSON.stringify(invokeResult.data ?? null)
-		});
-		if (invokeResult.error) this.emit("agent.tool.failed", {
-			tool: toolMeta,
-			input: toolCallRequest.input,
-			error: invokeResult.error,
-			tripIndex
-		});
-		else this.emit("agent.tool.called", {
-			...record,
-			tool: toolMeta
-		});
-		return record;
-	}
-	/**
-	* Parse the final trip output against the user-supplied schema (if any).
-	* Failures populate `this.error` but never throw. Returns an outcome the
-	* caller uses to decide whether self-repair is worth attempting:
-	*
-	* - `"skipped"` — no schema, or a prior trip-level error already set
-	*   `this.error` (model crash, max trips). Not repairable; the failure
-	*   isn't a parse problem the model can fix by re-asking.
-	* - `"failed"` — schema present, output text either failed JSON.parse
-	*   or failed `~standard.validate`. Repairable via `runRepairLoop`.
-	* - `"success"` — parsed and validated; `this.data` populated.
-	*
-	* Under the judge-safe preset (`judge: true`) the JSON extraction is
-	* lenient — it tolerates fenced ` ```json ` blocks plus leading /
-	* trailing prose by slicing the first balanced object / array out of the
-	* response. Never throws regardless of preset: a parse / validation miss
-	* sets `this.error` and returns `"failed"`, leaving `this.data`
-	* undefined for the graceful-default path.
-	*/
-	async parseOutput() {
-		const schema = this.options?.output ?? this.config.output;
-		if (!schema || this.error) return "skipped";
-		const text = this.trips[this.trips.length - 1]?.output ?? "";
-		if (!text) return "skipped";
-		const payload = this.judgeConfig ? extractJsonLenient(text) : extractJsonPayload(text);
-		const sentinel = Symbol("parse-failed");
-		const parsed = safeJsonParse(payload, sentinel);
-		if (parsed === sentinel) {
-			this.error = new SchemaValidationError("Failed to parse model output as JSON", { context: { text } });
-			return "failed";
-		}
-		const validation = await schema["~standard"].validate(parsed);
-		if (validation.issues) {
-			const summary = validation.issues.map((issue) => issue.message).join("; ");
-			this.error = new SchemaValidationError(summary, { issues: validation.issues });
-			return "failed";
-		}
-		this.data = validation.value;
-		return "success";
-	}
-	/**
-	* Resolve how many repair re-asks this run should perform after a parse
-	* failure. Per-call `options.repair` wins when explicitly set (preserving
-	* the existing surface). Otherwise the judge-safe preset supplies its
-	* default attempt count — so `judge: true` enables repair without the
-	* caller also having to pass `repair`. Returns `0` when neither applies,
-	* which leaves the historical "no repair unless asked" behavior intact.
-	*/
-	resolveRepairAttempts() {
-		if (this.options?.repair) return this.options.repair.maxAttempts ?? 1;
-		if (this.judgeConfig) return this.judgeConfig.repairAttempts ?? 2;
-		return 0;
-	}
-	/**
-	* Opt-in self-repair loop for `output` schema failures. Triggered only
-	* when repair attempts remain (`resolveRepairAttempts() > 0`) and
-	* `parseOutput()` returned `"failed"`.
-	*
-	* Each attempt:
-	* 1. Pushes the bad assistant response into `this.messages` (so the
-	*    model can see what it just produced).
-	* 2. Pushes a corrective user message naming the validation/parse error.
-	* 3. Runs another trip — counted against the same `maxTrips` cap as
-	*    normal trips so a stuck model can't loop forever.
-	* 4. Re-parses. Stops on success, on a trip-level error, or when
-	*    either `maxAttempts` or `maxTrips` is exhausted.
-	*
-	* Resets `this.error` and `this.data` before each attempt so the final
-	* outcome (success or last failure) is what surfaces to the caller.
-	*/
-	async runRepairLoop() {
-		const maxAttempts = this.resolveRepairAttempts();
-		for (let attempt = 0; attempt < maxAttempts; attempt++) {
-			if (this.trips.length >= this.maxTrips) return;
-			const badResponse = this.trips[this.trips.length - 1]?.output ?? "";
-			const failureReason = this.error?.message ?? "unknown validation failure";
-			this.error = void 0;
-			this.data = void 0;
-			this.messages.push({
-				role: "assistant",
-				content: badResponse
-			});
-			this.messages.push({
-				role: "user",
-				content: [`Your previous response failed validation: ${failureReason}.`, "Respond again with valid JSON only — no prose, no markdown fences, no commentary."].join(" ")
-			});
-			const tripIndex = this.trips.length;
-			this.logger.warn(LOG_MODULE, "repair.attempting", "retrying after validation failure", {
-				attempt: attempt + 1,
-				maxAttempts,
-				reason: failureReason
-			});
-			if (await this.runTrip(tripIndex, "[repair attempt]") === "error") return;
-			if (await this.parseOutput() === "success") return;
-		}
-	}
-	/**
-	* Build the final `AgentResult` snapshot from accumulated state
-	* (trips, tool calls, data/error, usage, timing).
-	*
-	* Pure — no side effects. `run()` owns terminal event emission and
-	* stream closure so the post-pipeline result (possibly transformed
-	* or short-circuited by an `execute`-level middleware) is what
-	* flows out to consumers and listeners.
-	*
-	* Trips, tool calls, status, and timing live under `report` so the
-	* root stays focused on the four things callers reach for most:
-	* `data`, `text`, `usage`, `error`.
-	*/
-	buildResult() {
-		const finalTrip = this.trips[this.trips.length - 1];
-		const endedAt = /* @__PURE__ */ new Date();
-		const agentName = this.config.name ?? this.config.model.name;
-		const status = this.error ? this.error instanceof AgentCancelledError ? "cancelled" : "failed" : "completed";
-		const report = {
-			runId: this.runId,
-			rootRunId: this.runId,
-			name: agentName,
-			version: this.config.version,
-			type: "agent",
-			status,
-			...this.error ? { error: this.error } : {},
-			startedAt: this.startedAt.toISOString(),
-			endedAt: endedAt.toISOString(),
-			duration: performance.now() - this.start,
-			usage: this.usage,
-			children: this.toolCalls,
-			model: {
-				name: this.config.model.name,
-				provider: this.config.model.provider
-			},
-			trips: this.trips,
-			systemPrompt: this.systemPrompt,
-			...this.promptName ? {
-				promptName: this.promptName,
-				promptVersion: this.promptVersion
-			} : {},
-			...this.config.captureMessages ? { messages: this.captureMessages() } : {}
-		};
-		stampReportLineage(report, {
-			rootRunId: this.runId,
-			sessionId: this.options?.sessionId
-		});
-		return {
-			type: "agent",
-			data: this.data,
-			text: finalTrip?.output,
-			report,
-			usage: this.usage,
-			error: this.error
-		};
-	}
-	/**
-	* Map the run's terminal outcome to the persisted snapshot status.
-	* A cancelled error reads as `"cancelled"`, any other error as
-	* `"failed"`, otherwise `"completed"`. Mirrors the report-status
-	* mapping in {@link buildResult}.
-	*/
-	resolveSnapshotStatus() {
-		if (!this.error) return "completed";
-		return this.error instanceof AgentCancelledError ? "cancelled" : "failed";
-	}
-	/**
-	* Build and persist an {@link AgentSnapshot} from the current
-	* accumulators. The per-trip and terminal checkpoints both route
-	* through here. Reuses {@link captureMessages} to normalize the live
-	* `Message[]` into JSON-safe form so the snapshot round-trips through
-	* any store backend.
-	*
-	* No-op (returns immediately) when `durable` is absent — the common
-	* non-durable path stays free. A failed persist is logged and
-	* swallowed (never aborts the run), matching the supervisor / workflow
-	* checkpoint policy.
-	*/
-	async checkpoint(status) {
-		if (!this.config.durable) return;
-		const outcome = await persistAgentSnapshot({
-			durable: this.config.durable,
-			runId: this.runId,
-			agentName: this.config.name ?? this.config.model.name,
-			signature: this.config.signature,
-			version: this.config.version,
-			input: this.input,
-			systemPrompt: this.systemPrompt,
-			responseSchema: this.responseSchema,
-			promptName: this.promptName,
-			promptVersion: this.promptVersion,
-			messages: this.captureMessages(),
-			trips: this.trips,
-			toolCalls: this.toolCalls,
-			usage: this.usage,
-			status,
-			startedAt: this.startedAt.toISOString()
-		});
-		if (!outcome.ok) this.logger.warn(LOG_MODULE, "snapshot.persist.failed", "durable snapshot persist failed", {
-			runId: this.runId,
-			status,
-			error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error)
-		});
-	}
-	/**
-	* Rebuild the final {@link AgentResult} from a COMPLETED snapshot
-	* WITHOUT re-running anything. Used by the completed-run resume
-	* short-circuit: the persisted trips / tool calls / usage are the
-	* authoritative outcome, so a resume of a settled run re-returns that
-	* outcome idempotently. Re-derives `this.data` from the final trip
-	* output against the schema (cheap, no model call) so the rebuilt
-	* result carries the same structured payload the original produced.
-	*
-	* Only reached for a `completed` snapshot — `failed` / `cancelled`
-	* snapshots re-enter the trip loop to retry the remaining work instead.
-	*/
-	async rebuildResumedResult(_snapshot) {
-		await this.parseOutput();
-		return this.buildResult();
-	}
-	/**
-	* Normalize the accumulated runtime `Message[]` into the JSON-safe
-	* {@link CapturedMessage}[] persisted on `AgentReport.messages` (F2).
-	* Flattens `ContentPart[]` content to a string, and forwards
-	* `toolCalls` (assistant turns) / `toolCallId` (tool-result turns)
-	* only when present so the captured shape stays lean. Called only when
-	* `captureMessages` is enabled.
-	*/
-	captureMessages() {
-		return this.messages.map((message) => {
-			const captured = {
-				role: message.role,
-				content: typeof message.content === "string" ? message.content : JSON.stringify(message.content)
-			};
-			if (message.toolCalls !== void 0) captured.toolCalls = message.toolCalls;
-			if (message.toolCallId !== void 0) captured.toolCallId = message.toolCallId;
-			return captured;
-		});
-	}
-	/**
-	* Normalize any thrown value into an `AIError`. `AIError` instances
-	* pass through untouched; provider-adapter SDK errors are caught by
-	* the adapter and already arrive typed, so this branch mainly
-	* handles runtime crashes (TypeError, ReferenceError) inside
-	* model.complete / model.stream and non-Error values (`throw "bad"`).
-	*/
-	toAIError(thrown) {
-		if (thrown instanceof AIError) return thrown;
-		if (isAbortLike(thrown)) return this.makeCancelledError();
-		return new AgentExecutionError(thrown instanceof Error ? thrown.message : String(thrown), { cause: thrown });
-	}
-	/**
-	* Build the typed cancelled error that both the trip-loop guard
-	* and the mid-stream guard emit. Captures the abort reason when
-	* one was supplied to `controller.abort(reason)` so logs and
-	* telemetry can see what cancelled the run.
-	*/
-	makeCancelledError() {
-		const reason = this.options?.signal?.reason;
-		const reasonText = reason === void 0 ? "" : String(reason);
-		return new AgentCancelledError("agent execution cancelled", {
-			cause: reason,
-			cancelledAt: (/* @__PURE__ */ new Date()).toISOString(),
-			reason: reasonText
-		});
-	}
-	/**
-	* Fire a single event through all three subscription tiers in order
-	* — factory → instance → per-call — and mirror it into the
-	* `StreamController` when streaming is active. A throwing user
-	* handler must never crash the agent, so every dispatch is wrapped
-	* in `safeCall`. Stream events are converted from the internal
-	* `AgentEventMap` payload to the public `StreamEvent` shape because
-	* some of them differ (e.g. the tool-called payload vs stream
-	* event).
-	*/
-	emit(event, payload) {
-		const fullPayload = {
-			...payload,
-			runId: this.runId,
-			rootRunId: this.runId
-		};
-		this.logEvent(event, fullPayload);
-		const onError = (error) => this.surfaceHandlerError(event, error);
-		const factoryHandler = this.config.on?.[event];
-		if (factoryHandler) safeCall(factoryHandler, fullPayload, onError);
-		const bucket = this.instanceHandlers?.get(event);
-		if (bucket) for (const handler of bucket) safeCall(handler, fullPayload, onError);
-		const perCallHandler = this.options?.on?.[event];
-		if (perCallHandler) safeCall(perCallHandler, fullPayload, onError);
-		if (this.streamController) {
-			const body = this.toStreamEvent(event, fullPayload);
-			if (body) this.streamController.push({
-				runId: this.runId,
-				rootRunId: this.runId,
-				...body
-			});
-		}
-	}
-	/**
-	* Surface an isolated event-handler failure (C5). A throwing user
-	* handler never crashes the agent — that isolation is preserved — but
-	* total silence is the wrong default: a broken `on` handler would
-	* otherwise disappear from production with no signal. Routed to the
-	* structured logger (matching the `onUsage` / `onComplete` policy) and
-	* warned at most once per event type so a hot event can't spam the log.
-	*/
-	surfaceHandlerError(event, error) {
-		if (this.warnedHandlerEvents.has(event)) return;
-		this.warnedHandlerEvents.add(event);
-		this.logger.warn(LOG_MODULE, "event.handler.error", "an event handler threw and was isolated", {
-			runId: this.runId,
-			event,
-			error: error instanceof Error ? error.message : String(error)
-		});
-	}
-	/**
-	* Emit a structured log line for a lifecycle event. The action
-	* string mirrors the event name with the `agent.` prefix stripped
-	* (`agent.trip.started` → `trip.started`) so log grep filters and
-	* event handlers read the same vocabulary. Level mapping follows
-	* the convention documented on `@warlock.js/logger`'s `Logger`.
-	*/
-	logEvent(event, payload) {
-		const agentName = this.config.name || this.config.model.name;
-		logAgentEvent(this.logger, {
-			module: `${LOG_MODULE}.${agentName}`,
-			maxTrips: this.maxTrips,
-			modelName: this.config.model.name,
-			totalUsage: this.usage,
-			totalDurationMs: performance.now() - this.start,
-			trips: this.trips,
-			toolCalls: this.toolCalls
-		}, event, payload);
-	}
-	toStreamEvent(event, payload) {
-		return agentEventToStreamEvent(event, payload);
-	}
-	/**
-	* Invoke the `onUsage` hook (when configured) with a flat payload
-	* carrying stable identity. Awaits the handler so async ledger
-	* writes complete before the next trip starts; swallows any throw
-	* so consumer bugs cannot crash the agent. Sync handlers wrapped
-	* via `Promise.resolve()` so the await is safe in either case.
-	*/
-	async fireUsageHook(tripIndex, tripUsage) {
-		const handler = this.config.onUsage;
-		if (!handler) return;
-		const event = {
-			runId: this.runId,
-			tripIndex,
-			model: {
-				name: this.config.model.name,
-				provider: this.config.model.provider
-			},
-			usage: { ...tripUsage },
-			timestamp: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		try {
-			await Promise.resolve(handler(event));
-		} catch (err) {
-			this.logger.warn(LOG_MODULE, "onUsage.hook.error", "onUsage handler threw", {
-				runId: this.runId,
-				tripIndex,
-				error: err instanceof Error ? err.message : String(err)
-			});
-		}
-	}
-	/**
-	* Invoke the `onComplete` hook (when configured) once at the end
-	* of every run. Receives the full `AgentResult` plus pre-extracted
-	* `runId` and `durationMs`. Same swallow-and-log error policy as
-	* `fireUsageHook`.
-	*/
-	async fireCompleteHook(result) {
-		const handler = this.config.onComplete;
-		if (!handler) return;
-		const event = {
-			result,
-			runId: this.runId,
-			durationMs: performance.now() - this.start
-		};
-		try {
-			await Promise.resolve(handler(event));
-		} catch (err) {
-			this.logger.warn(LOG_MODULE, "onComplete.hook.error", "onComplete handler threw", {
-				runId: this.runId,
-				error: err instanceof Error ? err.message : String(err)
-			});
-		}
-	}
-};
-/**
-* Decide whether a guard-synthesized tool call duplicates a real one
-* the provider already streamed structurally. Match key is
-* `name + key-sorted JSON of input` so identical calls (regardless of
-* argument key order) collapse, but two legitimate calls to the same
-* tool with different inputs still both dispatch.
-*/
-function isDuplicateToolCall(recovered, realCalls) {
-	const recoveredKey = `${recovered.name}|${stableStringify(recovered.input)}`;
-	for (const real of realCalls) if (`${real.name}|${stableStringify(real.input)}` === recoveredKey) return true;
-	return false;
-}
-/**
-* `JSON.stringify` variant that sorts object keys at every nesting
-* level so structurally-equal inputs serialize to identical strings.
-* Used only for dedupe-key comparison; never surfaces to consumers.
-*/
-function stableStringify(value) {
-	return JSON.stringify(value, (_key, val) => {
-		if (val !== null && typeof val === "object" && !Array.isArray(val)) {
-			const source = val;
-			const sorted = {};
-			for (const key of Object.keys(source).sort()) sorted[key] = source[key];
-			return sorted;
-		}
-		return val;
-	});
-}
-/**
-* Invoke a user-supplied event handler without letting exceptions
-* escape the agent. A throw is isolated (it never crashes the agent)
-* but no longer silent: the optional `onError` surfaces it — the agent
-* routes it to its structured logger, matching the swallow-and-log
-* policy of the `onUsage` / `onComplete` hooks (C5).
-*/
-function safeCall(handler, payload, onError) {
-	try {
-		handler(payload);
-	} catch (error) {
-		onError?.(error);
-	}
-}
-/**
-* Resolve a tool's `action` declaration into a plain string for
-* inclusion in `ToolEventMeta`. Static strings pass through;
-* function-shaped actions are invoked with the model's raw,
-* pre-validation input (before `execute`'s schema validation runs).
-*
-* Defensive: if the user's callback throws, swallow and return
-* `undefined` rather than crashing the agent — UI strings are not
-* worth aborting an LLM dispatch over.
-*/
-function resolveToolAction(tool, input) {
-	if (tool.action === void 0) return void 0;
-	if (typeof tool.action === "string") return tool.action;
-	try {
-		return tool.action(input);
-	} catch {
-		return;
-	}
-}
-
-//#endregion
-export { agent };
-//# sourceMappingURL=agent.mjs.map