@warlock.js/ai 4.5.0 → 4.6.0

package/esm/agent/agent-config.type.d.mts

@@ -1,5 +1,6 @@
 import { AttachmentPolicy } from "../contracts/attachment-policy.type.mjs";
 import { FlowObserveOption } from "../observe/resolve-observers.mjs";
+import { SnapshotStore } from "../contracts/orchestrator/snapshot-store.contract.mjs";
 import { AgentToolEntry } from "../tool/executable-as-tool.mjs";
 import { ModelCallOptions, ModelContract } from "../contracts/model.contract.mjs";
 import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
@@ -7,6 +8,7 @@ import { Placeholders } from "../contracts/placeholders.type.mjs";
 import { SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
 import { AgentEventMap } from "../contracts/events/event-map.type.mjs";
 import { StreamingToolGuardConfig } from "../contracts/streaming-tool-guard-config.type.mjs";
+import { AgentSnapshot } from "../contracts/agent/agent-snapshot.type.mjs";
 import { CompleteEvent } from "../contracts/events/complete-event.type.mjs";
 import { UsageEvent } from "../contracts/events/usage-event.type.mjs";
 import { SkillsConfig } from "../skills/contracts/skills-config.type.mjs";
@@ -256,6 +258,33 @@ type AgentConfig<TOutput = unknown> = {
    * Observer errors are swallowed — they never break the run.
    */
   observe?: FlowObserveOption;
+  /**
+   * Opt-in durable mid-run crash-resume. When set, the agent checkpoints
+   * its state to a {@link SnapshotStore} after every settled trip, so a
+   * `agent.resume(runId)` after a crash re-hydrates the completed trips +
+   * tool calls + usage and continues the trip loop from the next trip —
+   * never re-issuing a completed trip's model call or re-invoking its
+   * tools.
+   *
+   * Absent ⇒ no persistence, zero behavior change: the trip loop starts
+   * at trip 0, never writes a snapshot, and runs byte-for-byte as today.
+   *
+   * - `store` — the snapshot store to persist to. Optional; falls back to
+   *   `ai.config({ defaultSnapshotStore })` when omitted. When neither is
+   *   set, snapshot writes silently skip and `resume()` throws.
+   * - `deleteOnComplete` — drop the snapshot once the run terminates
+   *   successfully. Default `false` (keep it, so a completed-run resume
+   *   short-circuits to the stored result and the snapshot stays for audit).
+   *
+   * **Idempotency caveat.** A crash mid-trip re-runs that trip's tools on
+   * resume; side-effectful tools (charging a card, sending an email) must
+   * be idempotent — the same caller-responsibility boundary the supervisor
+   * and workflow primitives already document.
+   */
+  durable?: {
+    /** Snapshot store to persist to. Falls back to the global default. */store?: SnapshotStore<AgentSnapshot>; /** Drop the snapshot on successful completion. Default `false`. */
+    deleteOnComplete?: boolean;
+  };
 };
 //#endregion
 export { AgentConfig, AgentEventHandlers };

package/esm/agent/agent-config.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA;;KAAY,kBAAA,GAAqB,OAAA,eACnB,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AA0BxD;;;;;;;;;;;KAAY,WAAA;EA+FD;;;;;;;;;;;;EAlFT,IAAA;EAbsB;;;;;;;EAqBtB,WAAA;EAkCA;;;;;;;;;;;;EArBA,OAAA,WA6DS;EA3DT,KAAA,EAAO,aAAA;EA8FP;;;;EAzFA,YAAA,GAAe,oBAAA;EA2GF;;;;;;;;;;;;;EA7Fb,KAAA,GAAQ,cAAA;EA+JE;;AAAiB;;;;;;EAtJ3B,gBAAA,GAAmB,gBAAA;;;;;;;;;;;;;EAanB,MAAA,GAAS,cAAA,GAAiB,YAAA;EAE1B,YAAA,GAAe,YAAA;;;;;EAKf,QAAA;EAEA,YAAA,GAAe,gBAAA;;;;;;;;;EASf,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmC1B,KAAA,aAAkB,WAAA;;;;;;EAMlB,EAAA,GAAK,kBAAA;;;;;;;;;;;;EAYL,UAAA,GAAa,eAAA;;;;;;;;;;;EAWb,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;;;EAerB,OAAA,IAAW,KAAA,EAAO,UAAA,YAAsB,OAAA;;;;;;;;;;;;;EAaxC,UAAA,IAAc,KAAA,EAAO,aAAA,CAAc,OAAA,aAAoB,OAAA;;;;;;;;;EASvD,eAAA;;;;;;;;;;;;;;;;;;EAkBA,OAAA,GAAU,iBAAA;AAAA"}
+{"version":3,"file":"agent-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAuBA;;KAAY,kBAAA,GAAqB,OAAA,eACnB,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AA0BxD;;;;;;;;;;;KAAY,WAAA;EA+FD;;;;;;;;;;;;EAlFT,IAAA;EAmOuB;;;;;;;EA3NvB,WAAA;EAoBA;;;;;;;;;;;;EAPA,OAAA,WAoDe;EAlDf,KAAA,EAAO,aAAA;EA2DE;;;;EAtDT,YAAA,GAAe,oBAAA;EA+FV;;;;;;;;;;;;;EAjFL,KAAA,GAAQ,cAAA;EA6IR;;;;;;;;EApIA,gBAAA,GAAmB,gBAAA;EAkLD;;;;;;;;;;;;EArKlB,MAAA,GAAS,cAAA,GAAiB,YAAA;EAE1B,YAAA,GAAe,YAAA;;;;;EAKf,QAAA;EAEA,YAAA,GAAe,gBAAA;;;;;;;;;EASf,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmC1B,KAAA,aAAkB,WAAA;;;;;;EAMlB,EAAA,GAAK,kBAAA;;;;;;;;;;;;EAYL,UAAA,GAAa,eAAA;;;;;;;;;;;EAWb,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;;;EAerB,OAAA,IAAW,KAAA,EAAO,UAAA,YAAsB,OAAA;;;;;;;;;;;;;EAaxC,UAAA,IAAc,KAAA,EAAO,aAAA,CAAc,OAAA,aAAoB,OAAA;;;;;;;;;EASvD,eAAA;;;;;;;;;;;;;;;;;;EAkBA,OAAA,GAAU,iBAAA;;;;;;;;;;;;;;;;;;;;;;;;EAwBV,OAAA;0EAEE,KAAA,GAAQ,aAAA,CAAc,aAAA;IAEtB,gBAAA;EAAA;AAAA"}

package/esm/agent/agent.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent.ts"],"mappings":";;;;;;;;AA6OA;;;;;;;;;;;;;;;;AAA6F;;;;;;AAsI7F;;;;;iBAtIgB,KAAA,oBAAyB,MAAA,EAAQ,WAAA,CAAY,OAAA,IAAW,aAAA,CAAc,OAAA;AAAA,kBAAtE,KAAA;EAAA,kBAAK,UAAA;AAAA;;;;;AAsIqD;KAA9D,gBAAA,sBAAsC,IAAA,CAAK,WAAA,CAAY,OAAA;;;;;;;;;;;;;;;;;;;AAiC3C;;;;;;;;;;iBAHf,UAAA,oBACP,MAAA,EAAQ,gBAAA,CAAiB,OAAA,GACzB,KAAA,GAAO,WAAA,aACN,aAAA,CAAc,OAAA"}
+{"version":3,"file":"agent.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/agent.ts"],"mappings":";;;;;;;;AA6PA;;;;;;;;;;;;;;;;AAA6F;;;;;;AAqL7F;;;;;iBArLgB,KAAA,oBAAyB,MAAA,EAAQ,WAAA,CAAY,OAAA,IAAW,aAAA,CAAc,OAAA;AAAA,kBAAtE,KAAA;EAAA,kBAAK,UAAA;AAAA;;;;;AAqLqD;KAA9D,gBAAA,sBAAsC,IAAA,CAAK,WAAA,CAAY,OAAA;;;;;;;;;;;;;;;;;;;AAiC3C;;;;;;;;;;iBAHf,UAAA,oBACP,MAAA,EAAQ,gBAAA,CAAiB,OAAA,GACzB,KAAA,GAAO,WAAA,aACN,aAAA,CAAc,OAAA"}

package/esm/agent/agent.mjs

@@ -25,6 +25,8 @@ 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
@@ -155,11 +157,23 @@ function agent(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
+		skillsLib,
+		signature
 	};
 	const instanceHandlers = /* @__PURE__ */ new Map();
 	function on(event, handler) {
@@ -179,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();
 		},
@@ -187,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) {
@@ -273,12 +301,13 @@ agent.judge = judgeAgent;
 * 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 = {
@@ -287,15 +316,25 @@ 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];
 	}
@@ -359,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.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();
 	}
 	/**
@@ -431,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;
@@ -479,6 +532,7 @@ 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);
@@ -510,6 +564,7 @@ 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.effectiveTools.find((tool) => tool.name === request.name)?.mode === "silent";
@@ -920,6 +975,70 @@ 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