@warlock.js/core 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `@warlock.js/core` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 4.6.0
+
+### Added
+
+- release-hygiene tests: version↔changelog invariant + generator-stub import check
+- `router.routeCount()` exposes the number of registered routes as a boot/readiness signal
+- `health.addRoutesRegisteredCheck(getRouteCount)` registers a readiness check that reports not-ready when a booted HTTP app has zero routes
+- seeders now receive a `{ track }` context — `track(model)`, `track(models[])`, and `track(table, id)` register created records (each call returns its argument so it can be chained inline); `recordsCreated` is auto-derived from the track count
+- `seed_records` table (created via the new `SeedRecordsTableMigration`) records every tracked seed reference within the same transaction the seed runs in; only the last run's refs are kept per seeder
+- `warlock seed --drop [name]` undoes a seed: deletes its tracked records in reverse run/insertion order inside a transaction, then resets the matching seeds-log rows so `once: true` seeds re-run; scope to one seeder with `--drop=<name>`
+- `Seeder.dependsOn` is now resolved — seeders are topologically sorted so dependencies run before dependents, layered over the numeric `order` tie-break; throws `UnknownSeederDependencyError` for a missing dependency and `SeederDependencyCycleError` for a cycle
+- seeders receive an injectable clock and a meaningful batch size — `run({ track, now, batchSize })`; `now()` (default `() => new Date()`) drives both seed data and the seeds-log timestamps so historical/back-fill runs are deterministic, and `batchSize` surfaces the seeder's own `batchSize` for `Model.createMany(rows, { batchSize })`
+- repository-level aggregation — `aggregate()`, `sum()`, `avg()`, `min()`, `max()`, and `groupBy()` on `RepositoryManager`, each reusing `filterBy` (and its operator-injection guard), `where`, and scopes before the aggregate, exactly like `count()`
+- `warlock doctor` — a read-only diagnostics command that runs routes / config / connectors / optional-peers / health / release-hygiene checks and prints a pass/warn/fail report (exits non-zero on any failure, never opens a DB/cache/socket connection)
+- `warlock routes` — a read-only command that lists the registered HTTP routes as a verb-colored table (method / path / name / action / middleware-count / source); filter with `--method` / `--path` / `--name`, or emit the normalized rows as JSON with `--json`. Boots app code to register routes but starts no connectors
+
+### Changed
+
+- `Seeder.run` now receives a `SeedContext` (`run(ctx)`) — backward compatible, an existing zero-arg `run()` keeps working unchanged
+
+### Fixed
+
+- route-module load/registration failures are no longer swallowed: a route file that throws on import or registration now surfaces loudly instead of silently 404'ing the whole surface
+- `ModuleLoader.loadModule` rethrows after logging (wrapped in a new `ModuleLoadError` carrying the failing file + cause), so a broken module aborts boot and is caught loudly by the HMR batch-reload handler in dev
+- `ModuleLoader.loadAll` aggregates per-file failures and throws an `AggregateError` at the end, so one broken module no longer hides the others
+- `router.withSourceFile` rethrows the callback error after logging instead of consuming it with a bare `console.log` (the `try/finally` source-file stack cleanup is preserved)
+
 ## 4.5.0
 
 ### Changed

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

@@ -24,6 +24,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
@@ -154,11 +156,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) {
@@ -178,6 +192,7 @@ function agent(config) {
 		name,
 		isAnonymous,
 		description: config.description,
+		signature,
 		async execute(input, options) {
 			return new Execution(resolvedConfig, input, options, void 0, instanceHandlers).run();
 		},
@@ -186,6 +201,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) {
@@ -272,12 +300,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 = {
@@ -286,15 +315,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];
 	}
@@ -358,14 +397,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();
 	}
 	/**
@@ -430,7 +483,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;
@@ -478,6 +531,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);
@@ -509,6 +563,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";
@@ -919,6 +974,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