@warlock.js/ai 4.4.0 → 4.6.0

package/esm/agent/agent.mjs

@@ -4,26 +4,42 @@ 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 { accumulateCost, computeCost } from "../utils/compute-cost.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 { JUDGE_DEFAULT_REPAIR_ATTEMPTS } from "./judge-config.type.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
@@ -93,6 +109,16 @@ function validateMiddleware(middleware) {
 	}
 }
 /**
+* 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
@@ -130,10 +156,24 @@ function agent(config) {
 		...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
+		tools,
+		skillsLib,
+		signature
 	};
 	const instanceHandlers = /* @__PURE__ */ new Map();
 	function on(event, handler) {
@@ -153,6 +193,7 @@ function agent(config) {
 		name,
 		isAnonymous,
 		description: config.description,
+		signature,
 		async execute(input, options) {
 			return new Execution(resolvedConfig, input, options, void 0, instanceHandlers).run();
 		},
@@ -161,6 +202,19 @@ function agent(config) {
 			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) {
@@ -170,6 +224,41 @@ function agent(config) {
 	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.
 *
@@ -212,12 +301,13 @@ function agent(config) {
 * return stream;
 */
 var Execution = class {
-	constructor(config, input, options, streamController, instanceHandlers) {
+	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 = {
@@ -226,13 +316,27 @@ var Execution = class {
 			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);
+		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
@@ -280,6 +384,8 @@ var Execution = class {
 		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;
 	}
@@ -292,14 +398,28 @@ var Execution = class {
 	* with `error` populated when things went wrong.
 	*/
 	async runCore() {
+		if (this.resumeFrom && this.resumeFrom.status === "completed") return this.rebuildResumedResult(this.resumeFrom);
 		try {
-			await this.buildInitialMessages();
-			this.emit("agent.starting", { input: this.input });
+			if (!this.resumeFrom) {
+				await this.buildInitialMessages();
+				this.emit("agent.starting", { input: this.input });
+			}
 			await this.runTripLoop();
-			if (await this.parseOutput() === "failed" && this.options?.repair) await this.runRepairLoop();
+			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();
 	}
 	/**
@@ -311,13 +431,50 @@ var Execution = class {
 	* to the model. Runs exactly once per execution.
 	*/
 	async buildInitialMessages() {
-		const { messages, responseSchema } = await buildAgentInputMessages({
+		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
@@ -327,7 +484,7 @@ var Execution = class {
 	* error so the caller can distinguish runaway tool loops from a real result.
 	*/
 	async runTripLoop() {
-		for (let tripIndex = 0; tripIndex < this.maxTrips; tripIndex++) {
+		for (let tripIndex = this.trips.length; tripIndex < this.maxTrips; tripIndex++) {
 			if (this.options?.signal?.aborted) {
 				this.error = this.makeCancelledError();
 				return;
@@ -375,14 +532,11 @@ var Execution = class {
 			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);
-		this.usage.input += response.usage.input;
-		this.usage.output += response.usage.output;
-		this.usage.total += response.usage.total;
-		if (response.usage.cachedTokens !== void 0) this.usage.cachedTokens = (this.usage.cachedTokens ?? 0) + response.usage.cachedTokens;
-		this.usage.cost = accumulateCost(this.usage.cost, response.usage.cost);
+		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 = [];
@@ -410,9 +564,10 @@ var Execution = class {
 		};
 		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.config.tools?.find((tool) => tool.name === request.name))?.mode === "silent";
+			return this.effectiveTools.find((tool) => tool.name === request.name)?.mode === "silent";
 		}) ? "stop" : "continue";
 	}
 	/**
@@ -442,7 +597,7 @@ var Execution = class {
 	async getModelResponse(tripIndex) {
 		const callOptions = {
 			...this.config.modelOptions,
-			tools: this.config.tools ?? [],
+			tools: this.effectiveTools,
 			...this.responseSchema ? { responseSchema: this.responseSchema } : {},
 			...this.options?.signal ? { signal: this.options.signal } : {}
 		};
@@ -458,7 +613,7 @@ var Execution = class {
 		const recoveredCalls = [];
 		const guardConfig = this.resolveStreamingToolGuard();
 		const guard = guardConfig ? new JsonStreamGuard({
-			tools: this.config.tools ?? [],
+			tools: this.effectiveTools,
 			maxBufferBytes: guardConfig.maxBufferBytes,
 			onSafeDelta: (delta) => {
 				content += delta;
@@ -527,7 +682,7 @@ var Execution = class {
 	* an error). Never throws — always returns a `ToolCall` record.
 	*/
 	async dispatchToolCall(toolCallRequest, tripIndex) {
-		const registeredTool = this.config.tools?.find((tool) => tool.name === toolCallRequest.name);
+		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,
@@ -592,9 +747,15 @@ var Execution = class {
 			},
 			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, this.options?.toolCtx), this.logger);
+			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();
@@ -643,10 +804,7 @@ var Execution = class {
 			...toolCallRequest.recoveredFrom ? { recoveredFrom: toolCallRequest.recoveredFrom } : {}
 		};
 		this.toolCalls.push(record);
-		this.usage.input += invokeResult.usage.input;
-		this.usage.output += invokeResult.usage.output;
-		this.usage.total += invokeResult.usage.total;
-		this.usage.cost = accumulateCost(this.usage.cost, invokeResult.usage.cost);
+		mergeUsage(this.usage, invokeResult.usage);
 		this.messages.push({
 			role: "tool",
 			toolCallId: toolCallRequest.id,
@@ -675,13 +833,20 @@ var Execution = class {
 	* - `"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 = extractJsonPayload(text);
+		const payload = this.judgeConfig ? extractJsonLenient(text) : extractJsonPayload(text);
 		const sentinel = Symbol("parse-failed");
 		const parsed = safeJsonParse(payload, sentinel);
 		if (parsed === sentinel) {
@@ -698,8 +863,22 @@ var Execution = class {
 		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 `options.repair` is set and `parseOutput()` returned `"failed"`.
+	* when repair attempts remain (`resolveRepairAttempts() > 0`) and
+	* `parseOutput()` returned `"failed"`.
 	*
 	* Each attempt:
 	* 1. Pushes the bad assistant response into `this.messages` (so the
@@ -714,7 +893,7 @@ var Execution = class {
 	* outcome (success or last failure) is what surfaces to the caller.
 	*/
 	async runRepairLoop() {
-		const maxAttempts = this.options?.repair?.maxAttempts ?? 1;
+		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 ?? "";
@@ -764,6 +943,7 @@ var Execution = class {
 			version: this.config.version,
 			type: "agent",
 			status,
+			...this.error ? { error: this.error } : {},
 			startedAt: this.startedAt.toISOString(),
 			endedAt: endedAt.toISOString(),
 			duration: performance.now() - this.start,
@@ -773,7 +953,13 @@ var Execution = class {
 				name: this.config.model.name,
 				provider: this.config.model.provider
 			},
-			trips: this.trips
+			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,
@@ -789,6 +975,89 @@ var Execution = class {
 		};
 	}
 	/**
+	* 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
@@ -832,12 +1101,13 @@ var Execution = class {
 			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);
+		if (factoryHandler) safeCall(factoryHandler, fullPayload, onError);
 		const bucket = this.instanceHandlers?.get(event);
-		if (bucket) for (const handler of bucket) safeCall(handler, fullPayload);
+		if (bucket) for (const handler of bucket) safeCall(handler, fullPayload, onError);
 		const perCallHandler = this.options?.on?.[event];
-		if (perCallHandler) safeCall(perCallHandler, fullPayload);
+		if (perCallHandler) safeCall(perCallHandler, fullPayload, onError);
 		if (this.streamController) {
 			const body = this.toStreamEvent(event, fullPayload);
 			if (body) this.streamController.push({
@@ -848,6 +1118,23 @@ var Execution = class {
 		}
 	}
 	/**
+	* 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
@@ -953,18 +1240,23 @@ function stableStringify(value) {
 }
 /**
 * Invoke a user-supplied event handler without letting exceptions
-* escape the agent. Thrown errors are swallowed — structured logging
-* attaches here in Phase 0.5 so operators still see the failure.
+* 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) {
+function safeCall(handler, payload, onError) {
 	try {
 		handler(payload);
-	} catch {}
+	} 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 validated input.
+* 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