@warlock.js/core 4.4.0 → 4.5.0

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

@@ -0,0 +1,1157 @@
+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 { 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 resolvedConfig = {
+		...config,
+		name,
+		tools,
+		skillsLib
+	};
+	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,
+		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;
+		},
+		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) {
+		this.config = config;
+		this.input = input;
+		this.options = options;
+		this.streamController = streamController;
+		this.instanceHandlers = instanceHandlers;
+		this.trips = [];
+		this.toolCalls = [];
+		this.usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		this.messages = [];
+		this.startedAt = /* @__PURE__ */ new Date();
+		this.start = performance.now();
+		this.runId = generateRunId("agent");
+		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);
+		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() {
+		try {
+			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);
+		}
+		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 = 0; 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 });
+			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 });
+		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
+		};
+	}
+	/**
+	* 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