@warlock.js/ai 4.5.0 → 4.6.1

package/cjs/{src-C02yzsLs.cjs → src-OZyDYHxm.cjs}

@@ -142,6 +142,33 @@ var AgentCancelledError = class extends AgentExecutionError {
 	}
 };
 
+//#endregion
+//#region ../@warlock.js/ai/src/errors/agent-drift-error.ts
+/**
+* `agent.resume(runId)` loaded a durable snapshot whose structural
+* fingerprint does not match the current agent definition (model +
+* provider + sorted tool names + maxTrips + output presence + version).
+* The resume is refused — no trip runs — and the user decides how to
+* recover: discard the snapshot, migrate manually, or call
+* `resume(runId, { force: true })` to bypass the check.
+*
+* Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+* different primitive. Thrown (not returned on `result.error`) because a
+* drifted resume never produces a valid run.
+*/
+var AgentDriftError = class extends AgentExecutionError {
+	static {
+		this.defaultCategory = "drift";
+	}
+	constructor(message, options) {
+		super(message, options, "AGENT_DRIFT");
+		this.name = "AgentDriftError";
+		this.savedSignature = options.savedSignature;
+		this.currentSignature = options.currentSignature;
+		this.runId = options.runId;
+	}
+};
+
 //#endregion
 //#region ../@warlock.js/ai/src/errors/agent-max-trips-error.ts
 /**
@@ -661,6 +688,35 @@ var PlannerCancelledError = class extends PlannerFailedError {
 	}
 };
 
+//#endregion
+//#region ../@warlock.js/ai/src/errors/planner-drift-error.ts
+/**
+* `planner.resume(runId)` loaded a durable snapshot whose structural
+* fingerprint does not match the current planner definition (name +
+* ordered capability names). The resume is refused — no node runs — and
+* the user decides how to recover: discard the snapshot, migrate
+* manually, or call `resume(runId, { force: true })` to bypass the check.
+*
+* A mid-run re-plan is NOT drift — the plan changed, not the definition;
+* the persisted `replanCount` honors the replan budget across a resume.
+*
+* Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+* different primitive. Thrown (not returned on `result.error`) because a
+* drifted resume never produces a valid run.
+*/
+var PlannerDriftError = class extends PlannerFailedError {
+	static {
+		this.defaultCategory = "drift";
+	}
+	constructor(message, options) {
+		super(message, options, "PLANNER_DRIFT");
+		this.name = "PlannerDriftError";
+		this.savedSignature = options.savedSignature;
+		this.currentSignature = options.currentSignature;
+		this.runId = options.runId;
+	}
+};
+
 //#endregion
 //#region ../@warlock.js/ai/src/errors/planner-plan-invalid-error.ts
 /**
@@ -3276,7 +3332,7 @@ function surfaceObserverError(observer, error, onError) {
 //#endregion
 //#region ../@warlock.js/ai/src/skills/catalog.ts
 let isEmbedderPeerInstalled = null;
-let loadingPromise$2;
+let loadingPromise$3;
 const EMBEDDER_INSTALL_INSTRUCTIONS = `
 Semantic skill pre-injection ({ inject: { select: "semantic" } }) needs an
 embedder. Pass one explicitly (reuse the one you built for ai.memory()):
@@ -3304,16 +3360,16 @@ and pass it via \`inject.embedder\`.
 */
 function probeEmbedderPeer() {
 	if (isEmbedderPeerInstalled !== null) return Promise.resolve();
-	if (loadingPromise$2) return loadingPromise$2;
-	loadingPromise$2 = (async () => {
+	if (loadingPromise$3) return loadingPromise$3;
+	loadingPromise$3 = (async () => {
 		try {
-			await Promise.resolve().then(() => require("./src-DFibP2FQ.cjs"));
+			await Promise.resolve().then(() => require("./src-Bmajk4Qg.cjs"));
 			isEmbedderPeerInstalled = true;
 		} catch {
 			isEmbedderPeerInstalled = false;
 		}
 	})();
-	return loadingPromise$2;
+	return loadingPromise$3;
 }
 /**
 * Resolve the embedder for semantic selection. The explicit
@@ -5770,6 +5826,155 @@ function readObject(envelope, key) {
 	return value;
 }
 
+//#endregion
+//#region ../@warlock.js/ai/src/agent/signature.ts
+/**
+* Deterministic structural fingerprint of an agent definition.
+* Persisted on every durable snapshot so `agent.resume()` can detect
+* drift between the saved run and the current definition. Covers the
+* fields whose change would make a mid-run resume unsafe — i.e. would
+* make the persisted `messages` / `toolCalls` array inconsistent with
+* what the resumed trip loop would produce:
+*
+* - Model name + provider — a different model invalidates the prior
+*   conversation's continuation.
+* - The sorted tool names — adding / removing / renaming a tool changes
+*   which dispatches the persisted `toolCalls` could have come from.
+* - `maxTrips` — the loop bound is a semantic shape change.
+* - Whether a default `output` schema is configured — flips the
+*   structured-output instruction baked into the system turn.
+* - `version` — dev-curated; a bump is an explicit "this changed" signal.
+*
+* Does NOT cover: system-prompt text, middleware, per-event handlers,
+* placeholders, modelOptions — runtime knobs that don't change the
+* shape of a resumable run. Mirrors `supervisor/signature.ts`'s coarse
+* structural philosophy and reuses its FNV-1a `hash`.
+*
+* `tools` here is read off the resolved config (post-normalization), so
+* raw executables dropped into `tools: []` are already adapted to
+* `ToolContract`s carrying a stable `name`.
+*/
+function computeAgentSignature(config) {
+	const toolNames = (config.tools ?? []).map((tool) => tool.name).sort((a, b) => a.localeCompare(b));
+	const fingerprint = {
+		n: config.name ?? null,
+		p: config.model?.provider ?? null,
+		m: config.model?.name ?? null,
+		t: toolNames,
+		x: config.maxTrips ?? null,
+		o: config.output ? 1 : 0,
+		v: config.version ?? null
+	};
+	return hash$3(JSON.stringify(fingerprint));
+}
+/**
+* FNV-1a 32-bit — the same hash `supervisor/signature.ts` and
+* `workflow/signature.ts` use. Deterministic, no crypto dependency,
+* cheap; signatures are 8-char hex.
+*/
+function hash$3(input) {
+	let h = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		h ^= input.charCodeAt(i);
+		h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/agent/snapshot.ts
+/**
+* Resolve the effective {@link SnapshotStore}: the agent's own
+* `durable.store` wins; absent that, fall back to the global default
+* set via `ai.config({ defaultSnapshotStore })`.
+*
+* The global default is typed for the supervisor snapshot shape, but
+* every store impl keys purely by `runId` and round-trips whatever
+* envelope it is handed — so it serves an `AgentSnapshot` just as well.
+* The cast re-tags the shape at this single boundary (Option B); the
+* agent only ever hands it an `AgentSnapshot`.
+*/
+function resolveSnapshotStore$4(durable) {
+	return durable?.store ?? resolveDefaultSnapshotStore();
+}
+/**
+* Write the current run state to the resolved snapshot store. No-op
+* (returns `{ ok: true }`) when neither `durable.store` nor the global
+* `defaultSnapshotStore` is configured — the common non-durable path.
+* Failures are returned as `{ ok: false }` rather than thrown so the
+* engine can surface them via logs without aborting the run — a failed
+* checkpoint loses resume-ability from that point but never breaks an
+* otherwise-healthy run.
+*/
+async function persistAgentSnapshot(params) {
+	const store = resolveSnapshotStore$4(params.durable);
+	if (!store) return { ok: true };
+	const snapshot = {
+		runId: params.runId,
+		agentName: params.agentName,
+		signature: params.signature,
+		version: params.version,
+		input: params.input,
+		systemPrompt: params.systemPrompt,
+		responseSchema: params.responseSchema,
+		promptName: params.promptName,
+		promptVersion: params.promptVersion,
+		messages: params.messages,
+		trips: params.trips,
+		toolCalls: params.toolCalls,
+		usage: params.usage,
+		status: params.status,
+		startedAt: params.startedAt,
+		savedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		await store.save(snapshot);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* Delete a persisted snapshot — used after a successful run when
+* `durable.deleteOnComplete` is set. Never throws: a failed delete is
+* surfaced as `{ ok: false }` and the engine logs it. No-op (ok) when no
+* store is configured.
+*/
+async function deleteAgentSnapshot(params) {
+	const store = resolveSnapshotStore$4(params.durable);
+	if (!store) return { ok: true };
+	try {
+		await store.delete(params.runId);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* Load a persisted snapshot for `resume()` and run the drift check.
+* Throws `AgentExecutionError` when no store is configured or when the
+* run is missing; throws `AgentDriftError` when the stored signature
+* doesn't match the current definition (unless `force` is set).
+*/
+async function loadAgentSnapshotForResume(params) {
+	const store = resolveSnapshotStore$4(params.durable);
+	if (!store) throw new AgentExecutionError(`agent "${params.agentName}" has no durable store configured — set \`durable: { store }\` on the config or call \`ai.config({ defaultSnapshotStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
+	const snapshot = await store.load(params.runId) ?? null;
+	if (!snapshot) throw new AgentExecutionError(`agent "${params.agentName}": no snapshot for runId "${params.runId}"`, { context: { runId: params.runId } });
+	if (!params.options?.force && snapshot.signature !== params.signature) throw new AgentDriftError(`agent "${params.agentName}" signature drift on resume`, {
+		savedSignature: snapshot.signature,
+		currentSignature: params.signature,
+		runId: params.runId
+	});
+	return snapshot;
+}
+
 //#endregion
 //#region ../@warlock.js/ai/src/agent/agent.ts
 const LOG_MODULE$1 = "ai.agent";
@@ -5899,11 +6104,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) {
@@ -5923,6 +6140,7 @@ function agent(config) {
 		name,
 		isAnonymous,
 		description: config.description,
+		signature,
 		async execute(input, options) {
 			return new Execution(resolvedConfig, input, options, void 0, instanceHandlers).run();
 		},
@@ -5931,6 +6149,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) {
@@ -6017,12 +6248,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 = {
@@ -6031,15 +6263,25 @@ var Execution = class {
 			total: 0
 		};
 		this.messages = [];
-		this.startedAt = /* @__PURE__ */ new Date();
 		this.start = performance.now();
-		this.runId = generateRunId$2("agent");
 		this.logger = _warlock_js_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$2("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];
 	}
@@ -6103,14 +6345,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$1, "snapshot.delete.failed", "durable snapshot delete failed", {
+				runId: this.runId,
+				error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error)
+			});
+		}
 		return this.buildResult();
 	}
 	/**
@@ -6175,7 +6431,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;
@@ -6223,6 +6479,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);
@@ -6254,6 +6511,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";
@@ -6664,6 +6922,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$1, "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
@@ -8180,14 +8502,14 @@ function memory$2() {
 * Default backing table — matches the §8.6 reference DDL verbatim so a
 * stock migration provisions the store with no extra config.
 */
-const DEFAULT_TABLE$2 = "warlock_orchestrator_sessions";
+const DEFAULT_TABLE$3 = "warlock_orchestrator_sessions";
 /**
 * Allowed characters in a Postgres identifier (table name). The table
 * name is interpolated into DDL/DML, so anything outside this
 * conservative ASCII subset is rejected — interpolating an arbitrary
 * string would be a SQL-injection footgun (mirrors `PgCacheDriver`).
 */
-const SAFE_IDENTIFIER$2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SAFE_IDENTIFIER$3 = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
 * Coerce a Postgres `INTEGER` column back to a number. `pg` hands back
 * `INTEGER` as a JS number already, but some pool wrappers surface it
@@ -8271,8 +8593,8 @@ function rowToRecord$1(row) {
 var PgCheckpointStore = class {
 	constructor(options) {
 		if (!options || typeof options.client?.query !== "function") throw new TypeError("ai.checkpoint.pg requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.");
-		const table = options.table ?? DEFAULT_TABLE$2;
-		if (!SAFE_IDENTIFIER$2.test(table)) throw new TypeError(`ai.checkpoint.pg: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+		const table = options.table ?? DEFAULT_TABLE$3;
+		if (!SAFE_IDENTIFIER$3.test(table)) throw new TypeError(`ai.checkpoint.pg: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
 		this.client = options.client;
 		this.table = table;
 		this.ttl = options.ttl;
@@ -9514,27 +9836,27 @@ function memory$1() {
 * Default backing table — provisions the store with no extra config when
 * the dev runs {@link InterruptStore.schema} through their migration tool.
 */
-const DEFAULT_TABLE$1 = "warlock_ai_human_interrupts";
+const DEFAULT_TABLE$2 = "warlock_ai_human_interrupts";
 /**
 * Allowed characters in a Postgres identifier (table name). The table name
 * is interpolated into DDL/DML, so anything outside this conservative
 * ASCII subset is rejected — interpolating an arbitrary string would be a
 * SQL-injection footgun (mirrors `@warlock.js/ai`'s pg stores).
 */
-const SAFE_IDENTIFIER$1 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SAFE_IDENTIFIER$2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
 * Module specifier for the optional `pg` driver. Held in a `string`
 * variable so the dynamic `import()` is not statically resolved at
 * compile time — `pg` is an optional peer that need not be installed for
 * this package to type-check or for a memory-only consumer to run.
 */
-const PG_MODULE = "pg";
+const PG_MODULE$1 = "pg";
 /**
 * Curated install string surfaced (at use time) when a `connectionString`
 * is configured but the optional `pg` driver is absent. Never thrown at
 * import — a memory-only consumer must be able to load this module.
 */
-const PG_INSTALL_INSTRUCTIONS = `
+const PG_INSTALL_INSTRUCTIONS$1 = `
 The @warlock.js/ai Postgres interrupt store requires the pg package.
 Install it with:
 
@@ -9550,12 +9872,12 @@ Or with your preferred package manager:
 * bare `catch` rethrows the curated install string — a missing optional
 * peer surfaces as actionable guidance, never a raw resolution error.
 */
-async function buildPgClient(connectionString) {
+async function buildPgClient$1(connectionString) {
 	let sdk;
 	try {
-		sdk = await import(PG_MODULE);
+		sdk = await import(PG_MODULE$1);
 	} catch {
-		throw new Error(PG_INSTALL_INSTRUCTIONS);
+		throw new Error(PG_INSTALL_INSTRUCTIONS$1);
 	}
 	return new sdk.Pool({ connectionString });
 }
@@ -9603,8 +9925,8 @@ function rowToRecord(row) {
 */
 var PgInterruptStore = class {
 	constructor(options) {
-		const table = options.table ?? DEFAULT_TABLE$1;
-		if (!SAFE_IDENTIFIER$1.test(table)) throw new TypeError(`ai.human.interrupt.pg: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+		const table = options.table ?? DEFAULT_TABLE$2;
+		if (!SAFE_IDENTIFIER$2.test(table)) throw new TypeError(`ai.human.interrupt.pg: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
 		this.table = table;
 		if (options.client) {
 			if (typeof options.client.query !== "function") throw new TypeError("ai.human.interrupt.pg requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.");
@@ -9612,7 +9934,7 @@ var PgInterruptStore = class {
 			return;
 		}
 		if (options.connectionString) {
-			this.clientPromise = buildPgClient(options.connectionString);
+			this.clientPromise = buildPgClient$1(options.connectionString);
 			return;
 		}
 		throw new TypeError("ai.human.interrupt.pg requires either a 'client' or a 'connectionString' option.");
@@ -9954,271 +10276,735 @@ const human = {
 };
 
 //#endregion
-//#region ../@warlock.js/ai/src/guard/detectors/injection.ts
-const DETECTOR_NAME$3 = "injection";
+//#region ../@warlock.js/ai/src/image/image-cost.ts
+/**
+* Price one image-generation `Usage` against an
+* {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD
+* breakdown so image spend folds into the exact same `Usage.cost`
+* rollup the text path uses (`accumulateCost` / `mergeUsage`). There is
+* no separate image-cost field anywhere downstream — only this one
+* function, which knows the two metering models:
+*
+* - **Per-image** (DALL·E, Imagen): `perImageBySize[size]` (when the
+*   request `size` matches a tier) else flat `perImage`, times the
+*   number of images returned, attributed to `cost.output` (the image
+*   IS the output). Token channels stay 0.
+* - **Token** (gpt-image-1): delegates to the standard
+*   {@link computeCost} against the prompt/image token `Usage`.
+*
+* Per-image wins when both shapes are configured (a provider is one or
+* the other). Returns `undefined` when no usable pricing is present —
+* the framework treats that as "cost unknown", never a false zero.
+*
+* @example
+* computeImageCost({ input: 0, output: 0, total: 0 }, 2, "1024x1024", { perImage: 0.04 });
+* // → { input: 0, output: 0.08 }
+*/
+function computeImageCost(usage, imageCount, size, pricing) {
+	if (!pricing) return;
+	if (pricing.perImage !== void 0 || pricing.perImageBySize !== void 0) {
+		const perImage = resolvePerImageRate(size, pricing);
+		if (perImage === void 0) return;
+		return {
+			input: 0,
+			output: perImage * imageCount
+		};
+	}
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
 /**
-* Built-in jailbreak / prompt-injection marker phrases. Each entry is a
-* case-insensitive substring (matched lowercased) paired with the rule
-* label surfaced on the {@link GuardrailMatch} (`injection.<label>`).
+* Resolve the USD-per-image rate: a `perImageBySize` tier matching the
+* requested `size` wins, otherwise the flat `perImage`. Returns
+* `undefined` only when neither is set (the caller already gated on
+* per-image metering being configured at all).
+*/
+function resolvePerImageRate(size, pricing) {
+	if (size !== void 0 && pricing.perImageBySize?.[size] !== void 0) return pricing.perImageBySize[size];
+	return pricing.perImage;
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/image/image.ts
+/**
+* Generate one or more images from a text prompt — the image-output
+* counterpart to `ai.agent`, and the first verb of the output-modality
+* track (Theme I). Wraps an {@link ImageModelContract} (from
+* `openai.image(...)` / `google.image(...)`) in the framework's uniform
+* result contract:
+*
+* - **Never throws.** Provider failures (auth, rate-limit,
+*   content-filter, invalid request) surface as a typed `AIError` on
+*   `result.error`; `result.data` is then `undefined`.
+* - **Cost-truth.** When the model carries pricing, `result.usage.cost`
+*   is filled in — per-token for gpt-image-1, per-image for
+*   DALL·E / Imagen — folding into the same `Usage.cost` rollup as text.
+* - **Observable.** The completed {@link ImageReport} routes to any
+*   registered `Observer` (panoptic, OTel, …) via the shared `observe`
+*   seam, exactly like an agent run.
 *
-* The set targets the canonical override / role-reset / exfiltration
-* patterns rather than trying to be exhaustive — a curated, low-false-
-* positive seed that callers extend with their own `markers`. Phrases are
-* deliberately specific (`"ignore previous instructions"`, not the bare
-* word `"ignore"`) so ordinary prose does not trip the rule.
+* @example
+* const openai = new OpenAISDK({ apiKey });
+* const { data, error, usage } = await ai.image({
+*   model: openai.image({ name: "gpt-image-1" }),
+*   prompt: "an isometric office desk, soft studio lighting",
+*   size: "1024x1024",
+* });
+*
+* if (error) console.warn(error.code);
+* else for (const img of data.images) save(img); // { type: "base64" | "url", ... }
 */
-const BUILT_IN_MARKERS = [
-	{
-		phrase: "ignore previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "ignore all previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "ignore the above instructions",
-		label: "override"
-	},
-	{
-		phrase: "disregard previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "disregard all previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "forget previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "forget all previous instructions",
-		label: "override"
-	},
-	{
-		phrase: "ignore your instructions",
-		label: "override"
-	},
-	{
-		phrase: "override your instructions",
-		label: "override"
-	},
-	{
-		phrase: "do not follow your instructions",
-		label: "override"
-	},
-	{
-		phrase: "you are now",
-		label: "role-reset"
-	},
-	{
-		phrase: "act as",
-		label: "role-reset"
-	},
-	{
-		phrase: "pretend to be",
-		label: "role-reset"
-	},
-	{
-		phrase: "developer mode",
-		label: "jailbreak"
-	},
-	{
-		phrase: "jailbreak",
-		label: "jailbreak"
-	},
-	{
-		phrase: "dan mode",
-		label: "jailbreak"
-	},
-	{
-		phrase: "do anything now",
-		label: "jailbreak"
-	},
-	{
-		phrase: "bypass your",
-		label: "jailbreak"
-	},
-	{
-		phrase: "ignore your guidelines",
-		label: "jailbreak"
-	},
-	{
-		phrase: "ignore your safety",
-		label: "jailbreak"
-	},
-	{
-		phrase: "ignore the rules",
-		label: "jailbreak"
-	},
-	{
-		phrase: "without any restrictions",
-		label: "jailbreak"
-	},
-	{
-		phrase: "reveal your system prompt",
-		label: "exfiltration"
-	},
-	{
-		phrase: "print your system prompt",
-		label: "exfiltration"
-	},
-	{
-		phrase: "show your system prompt",
-		label: "exfiltration"
-	},
-	{
-		phrase: "repeat your instructions",
-		label: "exfiltration"
-	},
-	{
-		phrase: "what are your instructions",
-		label: "exfiltration"
-	},
-	{
-		phrase: "reveal your prompt",
-		label: "exfiltration"
+async function image(params) {
+	const { model, prompt } = params;
+	const runId = generateRunId$2("image");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let imageCount = 0;
+	try {
+		const response = await model.generate(prompt, {
+			count: params.count,
+			size: params.size,
+			quality: params.quality,
+			aspectRatio: params.aspectRatio,
+			negativePrompt: params.negativePrompt,
+			format: params.format,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		if (usage.cost === void 0) {
+			const cost = computeImageCost(usage, response.images.length, params.size, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
+		}
+		data = { images: response.images };
+		imageCount = response.images.length;
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage$2(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
 	}
-];
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "image",
+		type: "image",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		imageCount,
+		reportSchemaVersion: 1
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	await notifyObservers(params.observe, report);
+	return {
+		type: "image",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage$2(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/speech/speech.ts
 /**
-* The zero-dependency built-in injection detector — the internal class
-* behind the {@link injection} factory. Scans for jailbreak / prompt-
-* injection marker phrases (built-in set + caller `markers`) and returns a
-* `block` or `flag` verdict (per `onMatch`) listing every match, or `allow`
-* when the text is clean.
+* Synthesize speech from text — the text-to-speech verb of the
+* output-modality track (Theme I), sibling to `ai.image()`. Wraps a
+* {@link SpeechModelContract} (from `openai.speech(...)`) in the
+* framework's uniform result contract:
 *
-* Detection only: a detector never throws or mutates the pipeline — the
-* `guard()` factory translates the verdict into the trip's throw / record
-* mechanics.
+* - **Never throws.** Provider failures surface as a typed `AIError` on
+*   `result.error`; `result.data` is then `undefined`.
+* - **Cost-truth.** `result.usage.cost` is filled per-character
+*   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same
+*   `Usage.cost` rollup as text.
+* - **Observable.** The completed {@link SpeechReport} routes to any
+*   registered `Observer` (panoptic, OTel, …) via the `observe` seam.
+*
+* @example
+* const openai = new OpenAISDK({ apiKey });
+* const { data, error } = await ai.speech({
+*   model: openai.speech({ name: "tts-1", voice: "alloy" }),
+*   text: "Your order has shipped.",
+*   format: "mp3",
+* });
+* if (!error) await fs.writeFile("ship.mp3", Buffer.from(data.audio.base64, "base64"));
 */
-var InjectionDetector = class {
-	constructor(options = {}) {
-		this.name = DETECTOR_NAME$3;
-		this.block = options.onMatch === "block";
-		this.markers = compileMarkers(options.markers ?? []);
-	}
-	/**
-	* Inspect `text` for any built-in or caller marker. Returns `allow` when
-	* none hit, otherwise the configured `block` / `flag` verdict carrying a
-	* {@link GuardrailMatch} per hit (with a `[start, end]` span for literal
-	* substrings; regex hits report a span only when the match is locatable).
-	*/
-	check(text) {
-		const matches = this.scan(text);
-		if (matches.length === 0) return { type: "allow" };
-		const reason = `Detected ${matches.length} prompt-injection marker(s).`;
-		if (this.block) return {
-			type: "block",
-			reason,
-			matches
-		};
-		return {
-			type: "flag",
-			reason,
-			matches
-		};
-	}
-	/** Collect every marker hit in `text`, in marker registration order. */
-	scan(text) {
-		const lowered = text.toLowerCase();
-		const matches = [];
-		for (const marker of this.markers) {
-			if (marker.phrase !== void 0) {
-				const start = lowered.indexOf(marker.phrase);
-				if (start !== -1) matches.push({
-					rule: `${DETECTOR_NAME$3}.${marker.label}`,
-					label: marker.label,
-					span: [start, start + marker.phrase.length - 1]
-				});
-				continue;
-			}
-			const pattern = marker.pattern;
-			if (pattern === void 0) continue;
-			const result = pattern.exec(text);
-			if (result !== null) {
-				const start = result.index;
-				matches.push({
-					rule: `${DETECTOR_NAME$3}.${marker.label}`,
-					label: marker.label,
-					span: [start, start + result[0].length - 1]
-				});
-			}
+async function speech(params) {
+	const { model, text } = params;
+	const runId = generateRunId$2("speech");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let characters = 0;
+	try {
+		const response = await model.generate(text, {
+			voice: params.voice,
+			format: params.format,
+			speed: params.speed,
+			instructions: params.instructions,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		characters = response.characters;
+		if (usage.cost === void 0) {
+			const cost = computeSpeechCost(usage, characters, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
 		}
-		return matches;
+		data = { audio: response.audio };
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage$1(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
 	}
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "speech",
+		type: "speech",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		characters,
+		reportSchemaVersion: 1
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	await notifyObservers(params.observe, report);
+	return {
+		type: "speech",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/**
+* Price a TTS run: `perMillionCharacters × characters` (per-character
+* metering, attributed to `cost.input`) wins when configured, otherwise
+* the standard token math. Returns `undefined` when no usable pricing
+* is present.
+*/
+function computeSpeechCost(usage, characters, pricing) {
+	if (!pricing) return;
+	if (pricing.perMillionCharacters !== void 0) return {
+		input: characters * pricing.perMillionCharacters / 1e6,
+		output: 0
+	};
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage$1(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/transcribe/audio-input.ts
+/**
+* File-extension → IANA audio media type map covering the formats the
+* common STT providers accept — including the **WhatsApp voice-note**
+* formats (`.ogg` / `.opus`, Opus-in-Ogg on Android; `.m4a` on iOS).
+*/
+const AUDIO_MEDIA_TYPES = {
+	".mp3": "audio/mpeg",
+	".mpeg": "audio/mpeg",
+	".mpga": "audio/mpeg",
+	".m4a": "audio/mp4",
+	".mp4": "audio/mp4",
+	".wav": "audio/wav",
+	".webm": "audio/webm",
+	".weba": "audio/webm",
+	".ogg": "audio/ogg",
+	".oga": "audio/ogg",
+	".opus": "audio/ogg",
+	".flac": "audio/flac",
+	".aac": "audio/aac"
 };
 /**
-* Compile the built-in phrase set plus any caller `markers` into a single
-* ordered list. A caller `string` becomes a lowercased substring matcher
-* (labelled `custom`); a caller `RegExp` is carried as-is (labelled
-* `custom`). Built-ins keep their threat-category label.
+* Resolve the audio media type from a filename's extension, or
+* `undefined` when the extension is unknown. Case-insensitive.
+*
+* @example
+* audioMediaTypeForFilename("voice-note.opus"); // "audio/ogg"
 */
-function compileMarkers(extra) {
-	const compiled = BUILT_IN_MARKERS.map((entry) => ({
-		label: entry.label,
-		phrase: entry.phrase
-	}));
-	for (const marker of extra) {
-		if (typeof marker === "string") {
-			compiled.push({
-				label: "custom",
-				phrase: marker.toLowerCase()
-			});
-			continue;
-		}
-		compiled.push({
-			label: "custom",
-			pattern: marker
-		});
-	}
-	return compiled;
+function audioMediaTypeForFilename(filename) {
+	return AUDIO_MEDIA_TYPES[(0, node_path.extname)(filename).toLowerCase()];
 }
 /**
-* Build the built-in `injection` detector (surfaced as
-* `ai.guardrail.injection(options?)`). Matches a curated set of jailbreak /
-* prompt-injection marker phrases — override (`"ignore previous
-* instructions"`), role-reset (`"you are now"`), jailbreak (`"developer
-* mode"`, `"do anything now"`), and exfiltration (`"reveal your system
-* prompt"`) — extensible with caller `markers` (case-insensitive substrings
-* or `RegExp`s).
+* Package raw audio bytes as an {@link AudioInput} for `ai.transcribe()`.
+* Pure plumbing — no AI, no I/O. Use when you already hold the bytes
+* (an upload buffer, a downloaded blob).
 *
-* Zero runtime dependency: matching is pure string / regex. On a hit the
-* verdict is `flag` by default (record but allow); pass `onMatch: "block"`
-* to reject instead — commonly used on the `input` phase, where the core
-* `trip.before` seam supports `block` / `flag` only.
+* @example
+* const audio = audioFromBuffer(uploadBuffer, "audio/ogg", "note.ogg");
+* const { data } = await ai.transcribe({ model: openai.transcribe({ name: "whisper-1" }), audio });
+*/
+function audioFromBuffer(data, mediaType, filename) {
+	return {
+		base64: Buffer.from(data).toString("base64"),
+		mediaType,
+		...filename ? { filename } : {}
+	};
+}
+/**
+* Read an audio file from disk and package it as an {@link AudioInput}
+* for `ai.transcribe()` — the one-line bridge from a file on disk
+* (WhatsApp `.ogg`/`.opus`, a meeting `.m4a`, a `.wav`) to the
+* transcription verb. **Pure utility — no AI here**; the actual text
+* extraction is the AI step (`ai.transcribe`).
 *
-* @param options - Extra `markers` and the `onMatch` action (`"flag"` | `"block"`).
-* @returns A {@link SyncGuardrailDetector} for the guard's `input` / `output` / `tool` arrays.
+* The media type is inferred from the file extension (override via
+* `options.mediaType` for extensionless or mislabeled files).
 *
 * @example
-* const guard = ai.guardrail({
-*   input: [ai.guardrail.injection({ onMatch: "block" })],
-*   output: [ai.guardrail.injection()], // flag-only on the model's reply
+* // WhatsApp voice note → text, end to end:
+* const audio = await audioFromFile("./voice-note.ogg");
+* const { data, error } = await ai.transcribe({
+*   model: openai.transcribe({ name: "whisper-1" }),
+*   audio,
+*   language: "en",
 * });
-*
-* @example
-* // Extend the built-in set with a house rule.
-* ai.guardrail.injection({ markers: [/system\s*:\s*override/i, "sudo mode"] });
+* if (!error) console.log(data.text);
 */
-function injection(options) {
-	return new InjectionDetector(options);
+async function audioFromFile(filePath, options) {
+	const buffer = await (0, node_fs_promises.readFile)(filePath);
+	const filename = (0, node_path.basename)(filePath);
+	const mediaType = options?.mediaType ?? audioMediaTypeForFilename(filename) ?? "audio/mpeg";
+	return {
+		base64: buffer.toString("base64"),
+		mediaType,
+		filename
+	};
 }
 
 //#endregion
-//#region ../@warlock.js/ai/src/guard/detectors/pii.ts
-/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */
-const DETECTOR_NAME$2 = "pii";
-/** Placeholder substituted for a matched span when the caller supplies no `mask`. */
-const DEFAULT_MASK = "[REDACTED]";
+//#region ../@warlock.js/ai/src/transcribe/transcribe.ts
 /**
-* The built-in PII category regexes. Each is linear (anchored alternations,
-* no nested quantifiers) so it is safe against catastrophic backtracking on
-* adversarial input. All carry the global flag so a single pass over the
-* text yields every occurrence; `lastIndex` is reset per use so a shared
-* instance never leaks state across calls.
+* Transcribe audio to text — the speech-to-text verb of the
+* output-modality track (Theme I), inverse of `ai.speech()`. Wraps a
+* {@link TranscriptionModelContract} (from `openai.transcribe(...)`) in
+* the uniform result contract:
 *
-* - `ssn`         — US Social Security number, `123-45-6789` / `123 45 6789`.
+* - **Never throws.** Provider failures surface as a typed `AIError` on
+*   `result.error`.
+* - **Cost-truth.** `result.usage.cost` is filled per-minute
+*   (`whisper-1`) or per-token (`gpt-4o-transcribe`).
+* - **Observable.** The completed {@link TranscriptionReport} routes to
+*   any registered `Observer` via the `observe` seam.
+*
+* @example
+* const openai = new OpenAISDK({ apiKey });
+* const { data, error } = await ai.transcribe({
+*   model: openai.transcribe({ name: "whisper-1" }),
+*   audio: { base64, mediaType: "audio/mpeg", filename: "voicemail.mp3" },
+*   language: "en",
+* });
+* if (!error) console.log(data.text);
+*/
+async function transcribe(params) {
+	const { model, audio } = params;
+	const runId = generateRunId$2("transcription");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let durationSeconds;
+	try {
+		const response = await model.transcribe(audio, {
+			language: params.language,
+			prompt: params.prompt,
+			format: params.format,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		durationSeconds = response.durationSeconds;
+		if (usage.cost === void 0) {
+			const cost = computeTranscriptionCost(usage, durationSeconds, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
+		}
+		data = {
+			text: response.text,
+			...response.segments ? { segments: response.segments } : {}
+		};
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
+	}
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "transcription",
+		type: "transcription",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		...durationSeconds !== void 0 ? { durationSeconds } : {},
+		reportSchemaVersion: 1
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	await notifyObservers(params.observe, report);
+	return {
+		type: "transcription",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/**
+* Price an STT run: `perMinute × (durationSeconds / 60)` (per-minute
+* metering, attributed to `cost.input`) wins when configured, otherwise
+* the standard token math. Returns `undefined` when no usable pricing
+* is present (e.g. per-minute pricing but the provider didn't report a
+* duration).
+*/
+function computeTranscriptionCost(usage, durationSeconds, pricing) {
+	if (!pricing) return;
+	if (pricing.perMinute !== void 0) {
+		if (durationSeconds === void 0) return;
+		return {
+			input: durationSeconds / 60 * pricing.perMinute,
+			output: 0
+		};
+	}
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/guard/detectors/injection.ts
+const DETECTOR_NAME$3 = "injection";
+/**
+* Built-in jailbreak / prompt-injection marker phrases. Each entry is a
+* case-insensitive substring (matched lowercased) paired with the rule
+* label surfaced on the {@link GuardrailMatch} (`injection.<label>`).
+*
+* The set targets the canonical override / role-reset / exfiltration
+* patterns rather than trying to be exhaustive — a curated, low-false-
+* positive seed that callers extend with their own `markers`. Phrases are
+* deliberately specific (`"ignore previous instructions"`, not the bare
+* word `"ignore"`) so ordinary prose does not trip the rule.
+*/
+const BUILT_IN_MARKERS = [
+	{
+		phrase: "ignore previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "ignore all previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "ignore the above instructions",
+		label: "override"
+	},
+	{
+		phrase: "disregard previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "disregard all previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "forget previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "forget all previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "ignore your instructions",
+		label: "override"
+	},
+	{
+		phrase: "override your instructions",
+		label: "override"
+	},
+	{
+		phrase: "do not follow your instructions",
+		label: "override"
+	},
+	{
+		phrase: "you are now",
+		label: "role-reset"
+	},
+	{
+		phrase: "act as",
+		label: "role-reset"
+	},
+	{
+		phrase: "pretend to be",
+		label: "role-reset"
+	},
+	{
+		phrase: "developer mode",
+		label: "jailbreak"
+	},
+	{
+		phrase: "jailbreak",
+		label: "jailbreak"
+	},
+	{
+		phrase: "dan mode",
+		label: "jailbreak"
+	},
+	{
+		phrase: "do anything now",
+		label: "jailbreak"
+	},
+	{
+		phrase: "bypass your",
+		label: "jailbreak"
+	},
+	{
+		phrase: "ignore your guidelines",
+		label: "jailbreak"
+	},
+	{
+		phrase: "ignore your safety",
+		label: "jailbreak"
+	},
+	{
+		phrase: "ignore the rules",
+		label: "jailbreak"
+	},
+	{
+		phrase: "without any restrictions",
+		label: "jailbreak"
+	},
+	{
+		phrase: "reveal your system prompt",
+		label: "exfiltration"
+	},
+	{
+		phrase: "print your system prompt",
+		label: "exfiltration"
+	},
+	{
+		phrase: "show your system prompt",
+		label: "exfiltration"
+	},
+	{
+		phrase: "repeat your instructions",
+		label: "exfiltration"
+	},
+	{
+		phrase: "what are your instructions",
+		label: "exfiltration"
+	},
+	{
+		phrase: "reveal your prompt",
+		label: "exfiltration"
+	}
+];
+/**
+* The zero-dependency built-in injection detector — the internal class
+* behind the {@link injection} factory. Scans for jailbreak / prompt-
+* injection marker phrases (built-in set + caller `markers`) and returns a
+* `block` or `flag` verdict (per `onMatch`) listing every match, or `allow`
+* when the text is clean.
+*
+* Detection only: a detector never throws or mutates the pipeline — the
+* `guard()` factory translates the verdict into the trip's throw / record
+* mechanics.
+*/
+var InjectionDetector = class {
+	constructor(options = {}) {
+		this.name = DETECTOR_NAME$3;
+		this.block = options.onMatch === "block";
+		this.markers = compileMarkers(options.markers ?? []);
+	}
+	/**
+	* Inspect `text` for any built-in or caller marker. Returns `allow` when
+	* none hit, otherwise the configured `block` / `flag` verdict carrying a
+	* {@link GuardrailMatch} per hit (with a `[start, end]` span for literal
+	* substrings; regex hits report a span only when the match is locatable).
+	*/
+	check(text) {
+		const matches = this.scan(text);
+		if (matches.length === 0) return { type: "allow" };
+		const reason = `Detected ${matches.length} prompt-injection marker(s).`;
+		if (this.block) return {
+			type: "block",
+			reason,
+			matches
+		};
+		return {
+			type: "flag",
+			reason,
+			matches
+		};
+	}
+	/** Collect every marker hit in `text`, in marker registration order. */
+	scan(text) {
+		const lowered = text.toLowerCase();
+		const matches = [];
+		for (const marker of this.markers) {
+			if (marker.phrase !== void 0) {
+				const start = lowered.indexOf(marker.phrase);
+				if (start !== -1) matches.push({
+					rule: `${DETECTOR_NAME$3}.${marker.label}`,
+					label: marker.label,
+					span: [start, start + marker.phrase.length - 1]
+				});
+				continue;
+			}
+			const pattern = marker.pattern;
+			if (pattern === void 0) continue;
+			const result = pattern.exec(text);
+			if (result !== null) {
+				const start = result.index;
+				matches.push({
+					rule: `${DETECTOR_NAME$3}.${marker.label}`,
+					label: marker.label,
+					span: [start, start + result[0].length - 1]
+				});
+			}
+		}
+		return matches;
+	}
+};
+/**
+* Compile the built-in phrase set plus any caller `markers` into a single
+* ordered list. A caller `string` becomes a lowercased substring matcher
+* (labelled `custom`); a caller `RegExp` is carried as-is (labelled
+* `custom`). Built-ins keep their threat-category label.
+*/
+function compileMarkers(extra) {
+	const compiled = BUILT_IN_MARKERS.map((entry) => ({
+		label: entry.label,
+		phrase: entry.phrase
+	}));
+	for (const marker of extra) {
+		if (typeof marker === "string") {
+			compiled.push({
+				label: "custom",
+				phrase: marker.toLowerCase()
+			});
+			continue;
+		}
+		compiled.push({
+			label: "custom",
+			pattern: marker
+		});
+	}
+	return compiled;
+}
+/**
+* Build the built-in `injection` detector (surfaced as
+* `ai.guardrail.injection(options?)`). Matches a curated set of jailbreak /
+* prompt-injection marker phrases — override (`"ignore previous
+* instructions"`), role-reset (`"you are now"`), jailbreak (`"developer
+* mode"`, `"do anything now"`), and exfiltration (`"reveal your system
+* prompt"`) — extensible with caller `markers` (case-insensitive substrings
+* or `RegExp`s).
+*
+* Zero runtime dependency: matching is pure string / regex. On a hit the
+* verdict is `flag` by default (record but allow); pass `onMatch: "block"`
+* to reject instead — commonly used on the `input` phase, where the core
+* `trip.before` seam supports `block` / `flag` only.
+*
+* @param options - Extra `markers` and the `onMatch` action (`"flag"` | `"block"`).
+* @returns A {@link SyncGuardrailDetector} for the guard's `input` / `output` / `tool` arrays.
+*
+* @example
+* const guard = ai.guardrail({
+*   input: [ai.guardrail.injection({ onMatch: "block" })],
+*   output: [ai.guardrail.injection()], // flag-only on the model's reply
+* });
+*
+* @example
+* // Extend the built-in set with a house rule.
+* ai.guardrail.injection({ markers: [/system\s*:\s*override/i, "sudo mode"] });
+*/
+function injection(options) {
+	return new InjectionDetector(options);
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/guard/detectors/pii.ts
+/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */
+const DETECTOR_NAME$2 = "pii";
+/** Placeholder substituted for a matched span when the caller supplies no `mask`. */
+const DEFAULT_MASK = "[REDACTED]";
+/**
+* The built-in PII category regexes. Each is linear (anchored alternations,
+* no nested quantifiers) so it is safe against catastrophic backtracking on
+* adversarial input. All carry the global flag so a single pass over the
+* text yields every occurrence; `lastIndex` is reset per use so a shared
+* instance never leaks state across calls.
+*
+* - `ssn`         — US Social Security number, `123-45-6789` / `123 45 6789`.
 * - `email`       — a pragmatic address shape, not full RFC 5322.
 * - `phone`       — North-American style, optional `+1`, separators, parens.
 * - `credit-card` — 13–16 digit runs, optional space / hyphen grouping.
@@ -10518,8 +11304,8 @@ Install it with:
 const DETECTOR_NAME = "moderation.openai";
 const DEFAULT_MODEL = "omni-moderation-latest";
 let OpenAiSdk;
-let isModuleExists$1;
-let loadingPromise$1;
+let isModuleExists$2;
+let loadingPromise$2;
 /**
 * Settle the lazy import of `openai` once, concurrency-safe. Only needed
 * when the caller did not pass a ready `client`. A bare `catch` flips the
@@ -10528,17 +11314,17 @@ let loadingPromise$1;
 * ai-panoptic's `loadLangfuse`.
 */
 function loadOpenAi() {
-	if (isModuleExists$1 !== void 0) return Promise.resolve();
-	if (loadingPromise$1) return loadingPromise$1;
-	loadingPromise$1 = (async () => {
+	if (isModuleExists$2 !== void 0) return Promise.resolve();
+	if (loadingPromise$2) return loadingPromise$2;
+	loadingPromise$2 = (async () => {
 		try {
 			OpenAiSdk = await import("openai");
-			isModuleExists$1 = true;
+			isModuleExists$2 = true;
 		} catch {
-			isModuleExists$1 = false;
+			isModuleExists$2 = false;
 		}
 	})();
-	return loadingPromise$1;
+	return loadingPromise$2;
 }
 /**
 * The optional OpenAI-backed moderation detector — the internal class behind
@@ -10584,7 +11370,7 @@ var OpenAiModerationDetector = class {
 	async resolveClient() {
 		if (this.client) return this.client;
 		await loadOpenAi();
-		if (!isModuleExists$1) throw new Error(OPENAI_INSTALL_INSTRUCTIONS);
+		if (!isModuleExists$2) throw new Error(OPENAI_INSTALL_INSTRUCTIONS);
 		this.client = new OpenAiSdk.default({ apiKey: this.apiKey });
 		return this.client;
 	}
@@ -10858,6 +11644,56 @@ const guardrail = Object.assign(guard, {
 	moderation
 });
 
+//#endregion
+//#region ../@warlock.js/ai/src/mock/mock-image-model.ts
+/** A 1×1 transparent PNG — the default mock image payload. */
+const TRANSPARENT_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+/**
+* Deterministic {@link ImageModelContract} double for tests — no HTTP.
+* Scripts responses in sequence (the last repeats once exhausted),
+* records every call, and can be primed with pricing to exercise the
+* cost rollup. Mirrors {@link MockModel} for the image path.
+*
+* @example
+* const model = new MockImageModel("mock-image", [{ usage: { input: 0, output: 0, total: 0 } }], {
+*   perImage: 0.04,
+* });
+* const { data, usage } = await ai.image({ model, prompt: "a cat" });
+*/
+var MockImageModel = class {
+	constructor(name, responses, pricing) {
+		this.name = name;
+		this.responses = responses;
+		this.pricing = pricing;
+		this.provider = "mock";
+		this.calls = [];
+		this.callIndex = 0;
+	}
+	async generate(prompt, options) {
+		this.calls.push({
+			prompt,
+			options
+		});
+		const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};
+		this.callIndex += 1;
+		if (response.delay) await new Promise((resolve) => setTimeout(resolve, response.delay));
+		if (response.error) throw response.error;
+		const count = options?.count ?? 1;
+		return {
+			images: response.images ?? Array.from({ length: count }, () => ({
+				type: "base64",
+				base64: TRANSPARENT_PNG_BASE64,
+				mediaType: "image/png"
+			})),
+			usage: response.usage ?? {
+				input: 0,
+				output: 0,
+				total: 0
+			}
+		};
+	}
+};
+
 //#endregion
 //#region ../@warlock.js/ai/src/mock/mock-model.ts
 /**
@@ -11002,7 +11838,78 @@ var MockModel = class {
 	*/
 	reset() {
 		this.calls = [];
-		this.responseIndex = 0;
+		this.responseIndex = 0;
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/ai/src/mock/mock-speech-model.ts
+/** Deterministic {@link SpeechModelContract} double for tests — no HTTP. */
+var MockSpeechModel = class {
+	constructor(name, responses, pricing) {
+		this.name = name;
+		this.responses = responses;
+		this.pricing = pricing;
+		this.provider = "mock";
+		this.calls = [];
+		this.callIndex = 0;
+	}
+	async generate(text, options) {
+		this.calls.push({
+			text,
+			options
+		});
+		const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};
+		this.callIndex += 1;
+		if (response.delay) await new Promise((resolve) => setTimeout(resolve, response.delay));
+		if (response.error) throw response.error;
+		return {
+			audio: response.audio ?? {
+				type: "base64",
+				base64: "AAAA",
+				mediaType: "audio/mpeg"
+			},
+			usage: response.usage ?? {
+				input: 0,
+				output: 0,
+				total: 0
+			},
+			characters: response.characters ?? text.length
+		};
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/ai/src/mock/mock-transcription-model.ts
+/** Deterministic {@link TranscriptionModelContract} double for tests — no HTTP. */
+var MockTranscriptionModel = class {
+	constructor(name, responses, pricing) {
+		this.name = name;
+		this.responses = responses;
+		this.pricing = pricing;
+		this.provider = "mock";
+		this.calls = [];
+		this.callIndex = 0;
+	}
+	async transcribe(audio, options) {
+		this.calls.push({
+			audio,
+			options
+		});
+		const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};
+		this.callIndex += 1;
+		if (response.delay) await new Promise((resolve) => setTimeout(resolve, response.delay));
+		if (response.error) throw response.error;
+		return {
+			text: response.text ?? "mock transcript",
+			...response.segments ? { segments: response.segments } : {},
+			...response.durationSeconds !== void 0 ? { durationSeconds: response.durationSeconds } : {},
+			usage: response.usage ?? {
+				input: 0,
+				output: 0,
+				total: 0
+			}
+		};
 	}
 };
 
@@ -11024,14 +11931,38 @@ var MockModel = class {
 */
 function MockSDK(config = {}) {
 	const models = [];
+	const imageModels = [];
+	const speechModels = [];
+	const transcriptionModels = [];
 	const responses = config.responses ?? [{ content: "Mock response" }];
+	const imageResponses = config.imageResponses ?? [{}];
+	const speechResponses = config.speechResponses ?? [{}];
+	const transcriptionResponses = config.transcriptionResponses ?? [{}];
 	return {
 		models,
+		imageModels,
+		speechModels,
+		transcriptionModels,
 		model(modelConfig) {
 			const model = new MockModel(modelConfig.name ?? config.defaultModelName ?? "mock-model", responses, config.capabilities);
 			models.push(model);
 			return model;
 		},
+		image(imageConfig) {
+			const model = new MockImageModel(imageConfig.name ?? config.defaultModelName ?? "mock-image-model", imageResponses, imageConfig.pricing ?? config.imagePricing);
+			imageModels.push(model);
+			return model;
+		},
+		speech(speechConfig) {
+			const model = new MockSpeechModel(speechConfig.name ?? config.defaultModelName ?? "mock-speech-model", speechResponses, speechConfig.pricing ?? config.speechPricing);
+			speechModels.push(model);
+			return model;
+		},
+		transcribe(transcribeConfig) {
+			const model = new MockTranscriptionModel(transcribeConfig.name ?? config.defaultModelName ?? "mock-transcription-model", transcriptionResponses, transcribeConfig.pricing ?? config.transcriptionPricing);
+			transcriptionModels.push(model);
+			return model;
+		},
 		async count(text, _model) {
 			return approximateTokenCount(text);
 		}
@@ -12320,8 +13251,8 @@ function isDispatchableUnit(value) {
 	return typeof candidate.name === "string" && typeof candidate.execute === "function";
 }
 function detectType(unit) {
-	if (typeof unit.signature === "string") return "workflow";
-	return "agent";
+	if (typeof unit.stream === "function") return "agent";
+	return "workflow";
 }
 function resolveAgentLikeDescription(intent, entryForm, unit, supervisorName) {
 	const entryOverride = entryForm?.description;
@@ -12678,7 +13609,7 @@ function wrapRouteError(supervisorName, thrown) {
 * `snapshotStore` field wins; absent that, fall back to the global
 * default set via `ai.config({ defaultSnapshotStore })`.
 */
-function resolveSnapshotStore$2(config) {
+function resolveSnapshotStore$3(config) {
 	return config.snapshotStore ?? resolveDefaultSnapshotStore();
 }
 /**
@@ -12690,7 +13621,7 @@ function resolveSnapshotStore$2(config) {
 * a failed checkpoint is fatal.
 */
 async function persistSupervisorSnapshot(params) {
-	const store = resolveSnapshotStore$2(params.config);
+	const store = resolveSnapshotStore$3(params.config);
 	if (!store) return { ok: true };
 	const snapshot = {
 		runId: params.runId,
@@ -12721,7 +13652,7 @@ async function persistSupervisorSnapshot(params) {
 * set).
 */
 async function loadSnapshotForResume$1(params) {
-	const store = resolveSnapshotStore$2(params.config);
+	const store = resolveSnapshotStore$3(params.config);
 	if (!store) throw new SupervisorFailedError(`supervisor "${params.config.name}" has no store configured — set \`snapshotStore\` on the config or call \`ai.config({ defaultSnapshotStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
 	const snapshot = await store.load(params.runId) ?? null;
 	if (!snapshot) throw new SupervisorFailedError(`supervisor "${params.config.name}": no snapshot for runId "${params.runId}"`, { context: { runId: params.runId } });
@@ -15310,7 +16241,7 @@ var OrchestratorExecution = class {
 			config: params.config,
 			signature: params.signature,
 			checkpointStore: resolveCheckpointStore(params.config),
-			snapshotStore: resolveSnapshotStore$1(params.config),
+			snapshotStore: resolveSnapshotStore$2(params.config),
 			emitter: adaptEmitter(params.emitter, generateRunId$2("orchestrator"), this.streamController),
 			memory: resolveOrchestratorMemory(params.config.memory)
 		};
@@ -15369,7 +16300,7 @@ function resolveCheckpointStore(config) {
 * snapshot). The factory already guarantees presence when
 * `iterate: true`, so the engine never asserts here.
 */
-function resolveSnapshotStore$1(config) {
+function resolveSnapshotStore$2(config) {
 	if (config.iterate !== true) return;
 	return config.snapshotStore ?? resolveDefaultSnapshotStore();
 }
@@ -16392,6 +17323,94 @@ function normalizeStep(raw) {
 	return step;
 }
 
+//#endregion
+//#region ../@warlock.js/ai/src/planner/snapshot.ts
+/**
+* Resolve the effective {@link SnapshotStore}: the planner's own
+* `durable.store` wins; absent that, fall back to the global default set
+* via `ai.config({ defaultSnapshotStore })`.
+*
+* The global default is typed for the supervisor snapshot shape, but
+* every store impl keys purely by `runId` and round-trips whatever
+* envelope it is handed — so it serves a `PlannerSnapshot` just as well.
+* The cast re-tags the shape at this single boundary (Option B); the
+* planner only ever hands it a `PlannerSnapshot`.
+*/
+function resolveSnapshotStore$1(durable) {
+	return durable?.store ?? resolveDefaultSnapshotStore();
+}
+/**
+* Write the current run state to the resolved snapshot store. No-op
+* (returns `{ ok: true }`) when neither `durable.store` nor the global
+* `defaultSnapshotStore` is configured — the common non-durable path.
+* Failures are returned as `{ ok: false }` rather than thrown so the
+* engine can surface them via logs without aborting the run.
+*/
+async function persistPlannerSnapshot(params) {
+	const store = resolveSnapshotStore$1(params.durable);
+	if (!store) return { ok: true };
+	const snapshot = {
+		runId: params.runId,
+		plannerName: params.plannerName,
+		signature: params.signature,
+		version: params.version,
+		goal: params.goal,
+		plan: params.plan,
+		executedSteps: params.executedSteps,
+		usage: params.usage,
+		children: params.children,
+		replanCount: params.replanCount,
+		status: params.status,
+		startedAt: params.startedAt,
+		savedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		await store.save(snapshot);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* Delete a persisted snapshot — used after a successful run when
+* `durable.deleteOnComplete` is set. Never throws. No-op (ok) when no
+* store is configured.
+*/
+async function deletePlannerSnapshot(params) {
+	const store = resolveSnapshotStore$1(params.durable);
+	if (!store) return { ok: true };
+	try {
+		await store.delete(params.runId);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* Load a persisted snapshot for `resume()` and run the drift check.
+* Throws `PlannerFailedError` when no store is configured or when the run
+* is missing; throws `PlannerDriftError` when the stored signature
+* doesn't match the current definition (unless `force` is set).
+*/
+async function loadPlannerSnapshotForResume(params) {
+	const store = resolveSnapshotStore$1(params.durable);
+	if (!store) throw new PlannerFailedError(`ai.planner("${params.plannerName}"): no durable store configured — set \`durable: { store }\` on the config or call \`ai.config({ defaultSnapshotStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
+	const snapshot = await store.load(params.runId) ?? null;
+	if (!snapshot) throw new PlannerFailedError(`ai.planner("${params.plannerName}"): no snapshot for runId "${params.runId}"`, { context: { runId: params.runId } });
+	if (!params.options?.force && snapshot.signature !== params.signature) throw new PlannerDriftError(`ai.planner("${params.plannerName}") signature drift on resume`, {
+		savedSignature: snapshot.signature,
+		currentSignature: params.signature,
+		runId: params.runId
+	});
+	return snapshot;
+}
+
 //#endregion
 //#region ../@warlock.js/ai/src/planner/planner-run.ts
 /**
@@ -16426,7 +17445,16 @@ var PlannerRun = class {
 		this.executedSteps = [];
 		this.awaitingApproval = false;
 		this.replanCount = 0;
-		this.runId = args.options?.runId ?? generateRunId$2("planner");
+		this.dagResumeConsumed = false;
+		this.runId = args.resumeFrom?.runId ?? args.options?.runId ?? generateRunId$2("planner");
+		if (args.resumeFrom) {
+			this.plan = args.resumeFrom.plan;
+			this.executedSteps.push(...args.resumeFrom.executedSteps);
+			this.children.push(...args.resumeFrom.children);
+			this.mergeUsage(this.usage, args.resumeFrom.usage);
+			this.replanCount = args.resumeFrom.replanCount;
+			this.startedAt = args.resumeFrom.startedAt;
+		}
 	}
 	/**
 	* Run the planner end-to-end. Never throws on runtime failure —
@@ -16446,17 +17474,30 @@ var PlannerRun = class {
 	* unified tree is emitted exactly once.
 	*/
 	async runPlan() {
+		if (this.args.resumeFrom && this.args.resumeFrom.status === "completed") {
+			this.rebuildResumedTerminal("completed");
+			return this.buildResult();
+		}
 		try {
 			if (this.isAborted()) {
 				this.markCancelled();
+				await this.checkpoint(this.resolveSnapshotStatus());
 				return this.buildResult();
 			}
-			const plan = this.args.options?.approvedPlan ?? await this.generatePlan();
-			if (this.error || !plan) return this.buildResult();
-			this.assertPlanValid(plan);
-			if (this.error) return this.buildResult();
+			const plan = this.args.resumeFrom ? this.plan : this.args.options?.approvedPlan ?? await this.generatePlan();
+			if (this.error || !plan) {
+				await this.checkpoint(this.resolveSnapshotStatus());
+				return this.buildResult();
+			}
+			if (!this.args.resumeFrom) {
+				this.assertPlanValid(plan);
+				if (this.error) {
+					await this.checkpoint(this.resolveSnapshotStatus());
+					return this.buildResult();
+				}
+			}
 			this.plan = plan;
-			if (this.args.options?.mode === "plan-only" && !this.args.options?.approvedPlan) {
+			if (!this.args.resumeFrom && this.args.options?.mode === "plan-only" && !this.args.options?.approvedPlan) {
 				this.awaitingApproval = true;
 				return this.buildResult();
 			}
@@ -16465,6 +17506,14 @@ var PlannerRun = class {
 		} catch (caught) {
 			this.error = this.toAIError(caught);
 		}
+		await this.checkpoint(this.resolveSnapshotStatus());
+		if (!this.error && this.args.config.durable?.deleteOnComplete) {
+			const outcome = await deletePlannerSnapshot({
+				durable: this.args.config.durable,
+				runId: this.runId
+			});
+			if (!outcome.ok) this.logDurableFailure("snapshot.delete.failed", outcome.error);
+		}
 		return this.buildResult();
 	}
 	/**
@@ -16548,6 +17597,7 @@ var PlannerRun = class {
 		const previousOutputs = [];
 		let steps = plan.steps;
 		let index = 0;
+		if (this.args.resumeFrom) index = this.rehydrateSequentialState(steps, previousOutputs);
 		while (index < steps.length) {
 			const step = steps[index];
 			if (index >= this.args.maxSteps) {
@@ -16603,6 +17653,10 @@ var PlannerRun = class {
 		const outputs = /* @__PURE__ */ new Map();
 		const rawOutputs = /* @__PURE__ */ new Map();
 		let executedCount = 0;
+		if (this.args.resumeFrom && !this.dagResumeConsumed) {
+			this.dagResumeConsumed = true;
+			executedCount = this.rehydrateDagState(dag, completed, done, outputs, rawOutputs);
+		}
 		while (done.size < dag.nodes.length) {
 			if (this.isAborted()) {
 				this.markCancelled();
@@ -16696,6 +17750,7 @@ var PlannerRun = class {
 			usage: result.usage,
 			childReport
 		});
+		await this.checkpoint("running");
 		if (failed) {
 			this.error = result.error;
 			return false;
@@ -16965,6 +18020,123 @@ var PlannerRun = class {
 		const mergedCost = accumulateCost(target.cost, child.cost);
 		if (mergedCost !== void 0) target.cost = mergedCost;
 	}
+	/**
+	* Re-derive the sequential cursor + prior-output context from the
+	* persisted ledger on resume. Threads every already-`completed` node's
+	* output into `previousOutputs`, returns the first index NOT completed
+	* as the resume cursor, and prunes stale non-completed ledger entries
+	* (the failed node + any skipped tail) at-or-after that cursor so the
+	* re-run repopulates them without duplicating.
+	*/
+	rehydrateSequentialState(steps, previousOutputs) {
+		let cursor = 0;
+		for (let index = 0; index < steps.length; index++) {
+			const snapshot = this.snapshotFor(index);
+			if (snapshot?.status === "completed") {
+				const step = steps[index];
+				previousOutputs.push(this.stringifyOutput(step.capability, snapshot.output));
+				cursor = index + 1;
+				continue;
+			}
+			break;
+		}
+		this.pruneLedgerFrom(cursor);
+		return cursor;
+	}
+	/**
+	* Re-derive the DAG scheduler's working sets from the persisted ledger
+	* on resume. Completed nodes go into `completed` + `done` with their
+	* string + raw outputs restored (so dependents read the right context);
+	* stale non-completed entries are pruned so the re-run repopulates them.
+	* Returns the count of nodes already dispatched (for the `maxSteps`
+	* truncation budget).
+	*/
+	rehydrateDagState(dag, completed, done, outputs, rawOutputs) {
+		const completedIndices = /* @__PURE__ */ new Set();
+		for (const node of dag.nodes) {
+			const snapshot = this.snapshotFor(node.index);
+			if (snapshot?.status !== "completed") continue;
+			completed.add(node.id);
+			done.add(node.id);
+			completedIndices.add(node.index);
+			rawOutputs.set(node.id, snapshot.output);
+			outputs.set(node.id, this.stringifyOutput(node.step.capability, snapshot.output));
+		}
+		const retained = this.executedSteps.filter((snapshot) => completedIndices.has(snapshot.index));
+		this.executedSteps.length = 0;
+		this.executedSteps.push(...retained);
+		return completedIndices.size;
+	}
+	/**
+	* Drop every ledger entry whose index is at or after `from`. Used by
+	* the sequential resume re-seed to clear the crashed run's failed /
+	* skipped frontier before the re-run repopulates it.
+	*/
+	pruneLedgerFrom(from) {
+		const retained = this.executedSteps.filter((snapshot) => snapshot.index < from);
+		this.executedSteps.length = 0;
+		this.executedSteps.push(...retained);
+	}
+	/**
+	* Map the run's terminal outcome to the persisted snapshot status.
+	* `awaiting-approval` (plan-only) never persists a durable snapshot
+	* (resume is always an execution), so it folds to `running` here —
+	* but the durable + plan-only combination is disallowed at the call
+	* site, so this path is effectively unreachable.
+	*/
+	resolveSnapshotStatus() {
+		if (this.cancelledAt !== void 0) return "cancelled";
+		if (this.error) return "failed";
+		if (this.awaitingApproval) return "running";
+		return "completed";
+	}
+	/**
+	* Build and persist a {@link PlannerSnapshot} from the current
+	* accumulators. The per-node and terminal checkpoints both route
+	* through here. No-op when `durable` is absent. A failed persist is
+	* logged and swallowed (never aborts the run), matching the supervisor
+	* / workflow checkpoint policy.
+	*/
+	async checkpoint(status) {
+		if (!this.args.config.durable || !this.plan) return;
+		const outcome = await persistPlannerSnapshot({
+			durable: this.args.config.durable,
+			runId: this.runId,
+			plannerName: this.args.config.name,
+			signature: this.args.signature,
+			version: this.args.config.version,
+			goal: this.args.goal,
+			plan: this.plan,
+			executedSteps: this.executedSteps,
+			usage: this.usage,
+			children: this.children,
+			replanCount: this.replanCount,
+			status,
+			startedAt: this.startedAt
+		});
+		if (!outcome.ok) this.logDurableFailure("snapshot.persist.failed", outcome.error);
+	}
+	/**
+	* Re-derive the terminal state when a resume short-circuits a snapshot
+	* whose run already COMPLETED. The persisted ledger is the
+	* authoritative outcome — `this.data` is restored from the last
+	* completed node so the rebuilt result carries the final output.
+	*
+	* Only reached for a `completed` snapshot — `failed` / `cancelled`
+	* snapshots re-enter execution to retry the unfinished frontier instead.
+	*/
+	rebuildResumedTerminal(_status) {
+		const lastCompleted = [...this.executedSteps].reverse().find((snapshot) => snapshot.status === "completed");
+		if (lastCompleted) this.data = lastCompleted.output;
+	}
+	/** Structured-log a durable persist/delete failure. */
+	logDurableFailure(action, error) {
+		_warlock_js_logger.log.warn("ai.planner", action, "durable snapshot operation failed", {
+			runId: this.runId,
+			planner: this.args.config.name,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
 	/** Whether the caller's abort signal has fired. */
 	isAborted() {
 		return this.args.options?.signal?.aborted === true;
@@ -17070,10 +18242,33 @@ function planner(config) {
 			options
 		}).run();
 	}
+	async function resume(runId, options) {
+		const snapshot = await loadPlannerSnapshotForResume({
+			durable: config.durable,
+			plannerName: config.name,
+			signature,
+			runId,
+			options
+		});
+		return new PlannerRun({
+			config,
+			capabilities,
+			maxSteps,
+			signature,
+			planningAgent,
+			goal: snapshot.goal,
+			options: {
+				...options,
+				runId
+			},
+			resumeFrom: snapshot
+		}).run();
+	}
 	return {
 		name: config.name,
 		signature,
-		execute
+		execute,
+		resume
 	};
 }
 /**
@@ -18424,18 +19619,136 @@ function anchorPieces(text, pieces) {
 			start: resolvedStart,
 			end
 		});
-		cursor = end;
-	}
-	return anchored;
+		cursor = end;
+	}
+	return anchored;
+}
+/**
+* Greedily pack anchored pieces into chunks up to `size` characters, then
+* carry `overlap` trailing characters from each emitted chunk into the
+* next so context is not lost at a boundary. Spans are taken straight
+* from the anchored pieces, so the overlap text is part of the next
+* chunk's span exactly.
+*/
+function packPieces(text, pieces, size, overlap) {
+	const chunks = [];
+	let bufferStart = -1;
+	let bufferEnd = -1;
+	let index = 0;
+	const flush = () => {
+		if (bufferStart === -1) return;
+		chunks.push({
+			text: text.slice(bufferStart, bufferEnd),
+			index,
+			span: [bufferStart, bufferEnd]
+		});
+		index += 1;
+	};
+	for (const piece of pieces) {
+		if (bufferStart === -1) {
+			bufferStart = piece.start;
+			bufferEnd = piece.end;
+			continue;
+		}
+		if (piece.end - bufferStart <= size) {
+			bufferEnd = piece.end;
+			continue;
+		}
+		flush();
+		bufferStart = overlap > 0 ? Math.max(bufferStart, piece.start - overlap) : piece.start;
+		bufferEnd = piece.end;
+	}
+	flush();
+	return chunks;
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/chunk/markdown.ts
+/** Matches an ATX Markdown heading line (`#` … `######`) at line start. */
+const HEADING_LINE = /^#{1,6}[ \t].*$/gm;
+/**
+* Markdown heading/section-aware splitter.
+*
+* Splits the document on ATX heading boundaries (`#`…`######`) first so a
+* section's heading stays glued to its body, then applies the recursive
+* character splitter WITHIN each section so any section larger than `size`
+* is broken down further. Sections at or under `size` are emitted whole.
+* Spans are exact relative to the original document.
+*/
+function markdownChunk(text, size, overlap, separators = DEFAULT_SEPARATORS) {
+	if (text.length === 0) return [];
+	const sections = splitSections(text);
+	const chunks = [];
+	let index = 0;
+	for (const section of sections) {
+		const body = text.slice(section.start, section.end);
+		if (body.trim().length === 0) continue;
+		if (body.length <= size) {
+			chunks.push({
+				text: body,
+				index,
+				span: [section.start, section.end]
+			});
+			index += 1;
+			continue;
+		}
+		const inner = recursiveChunk(body, size, overlap, separators);
+		for (const piece of inner) {
+			chunks.push({
+				text: piece.text,
+				index,
+				span: [section.start + piece.span[0], section.start + piece.span[1]]
+			});
+			index += 1;
+		}
+	}
+	return chunks;
+}
+/**
+* Carve the document into sections, each beginning at a heading line and
+* running until the next heading (the preamble before the first heading is
+* its own section). Spans cover the whole document with no gaps.
+*/
+function splitSections(text) {
+	const starts = [];
+	let match;
+	HEADING_LINE.lastIndex = 0;
+	while ((match = HEADING_LINE.exec(text)) !== null) starts.push(match.index);
+	if (starts.length === 0) return [{
+		start: 0,
+		end: text.length
+	}];
+	const sections = [];
+	if (starts[0] > 0) sections.push({
+		start: 0,
+		end: starts[0]
+	});
+	starts.forEach((start, position) => {
+		const end = position + 1 < starts.length ? starts[position + 1] : text.length;
+		sections.push({
+			start,
+			end
+		});
+	});
+	return sections;
 }
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/chunk/sentence.ts
+/** Matches a sentence terminator (`.`, `!`, `?`) followed by whitespace. */
+const SENTENCE_BOUNDARY = /([.!?])\s+/g;
 /**
-* Greedily pack anchored pieces into chunks up to `size` characters, then
-* carry `overlap` trailing characters from each emitted chunk into the
-* next so context is not lost at a boundary. Spans are taken straight
-* from the anchored pieces, so the overlap text is part of the next
-* chunk's span exactly.
+* Sentence-aware character splitter.
+*
+* Splits the text on sentence terminators (`. `, `! `, `? `), keeping the
+* terminator attached, then greedily packs whole sentences into chunks up
+* to `size` characters, carrying `overlap` characters forward between
+* adjacent chunks. A single sentence longer than `size` becomes its own
+* (oversize) chunk rather than being cut mid-sentence. Spans are exact.
 */
-function packPieces(text, pieces, size, overlap) {
+function sentenceChunk(text, size, overlap) {
+	if (text.trim().length === 0) return [];
+	const sentences = splitSentences(text);
 	const chunks = [];
 	let bufferStart = -1;
 	let bufferEnd = -1;
@@ -18449,475 +19762,1128 @@ function packPieces(text, pieces, size, overlap) {
 		});
 		index += 1;
 	};
-	for (const piece of pieces) {
+	for (const sentence of sentences) {
 		if (bufferStart === -1) {
-			bufferStart = piece.start;
-			bufferEnd = piece.end;
+			bufferStart = sentence.start;
+			bufferEnd = sentence.end;
 			continue;
 		}
-		if (piece.end - bufferStart <= size) {
-			bufferEnd = piece.end;
+		if (sentence.end - bufferStart <= size) {
+			bufferEnd = sentence.end;
 			continue;
 		}
 		flush();
-		bufferStart = overlap > 0 ? Math.max(bufferStart, piece.start - overlap) : piece.start;
-		bufferEnd = piece.end;
+		bufferStart = overlap > 0 ? Math.max(bufferStart, sentence.start - overlap) : sentence.start;
+		bufferEnd = sentence.end;
 	}
 	flush();
 	return chunks;
 }
+/**
+* Split `text` into sentence spans on terminator + whitespace, keeping the
+* terminator with its sentence and absorbing the trailing whitespace into
+* the boundary so reconstructing the spans loses no characters.
+*/
+function splitSentences(text) {
+	const spans = [];
+	let start = 0;
+	let match;
+	SENTENCE_BOUNDARY.lastIndex = 0;
+	while ((match = SENTENCE_BOUNDARY.exec(text)) !== null) {
+		const end = match.index + match[0].length;
+		spans.push({
+			start,
+			end
+		});
+		start = end;
+	}
+	if (start < text.length) spans.push({
+		start,
+		end: text.length
+	});
+	return spans;
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/chunk/chunk.ts
+/** Default target chunk size in characters. */
+const DEFAULT_CHUNK_SIZE = 1e3;
+/** Default character overlap carried between adjacent chunks. */
+const DEFAULT_CHUNK_OVERLAP = 200;
+/**
+* Split `text` into citation-bearing {@link Chunk}s according to
+* {@link ChunkOptions}, dispatching on `options.type`:
+*
+* - `"recursive"` (default) — separator-aware greedy packing.
+* - `"markdown"` — heading/section-aware, then recursive within sections.
+* - `"sentence"` — packs whole sentences.
+* - `"fixed"` — back-to-back character windows.
+*
+* All strategies are character-based (tokenizer-free) and record the exact
+* `[start, end)` span of every chunk in the original text. Empty or
+* whitespace-only input yields `[]`.
+*
+* @example
+* const chunks = chunk(markdownDoc, { type: "markdown", size: 800, overlap: 120 });
+* for (const c of chunks) console.log(c.index, c.span, c.text);
+*/
+function chunk(text, options = {}) {
+	const type = options.type ?? "recursive";
+	const size = options.size ?? 1e3;
+	const overlap = options.overlap ?? 200;
+	const separators = options.separators ?? DEFAULT_SEPARATORS;
+	if (text.trim().length === 0) return [];
+	switch (type) {
+		case "markdown": return markdownChunk(text, size, overlap, separators);
+		case "sentence": return sentenceChunk(text, size, overlap);
+		case "fixed": return fixedChunk(text, size, overlap);
+		default: return recursiveChunk(text, size, overlap, separators);
+	}
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/as-tool.ts
+/**
+* A minimal, schema-library-agnostic Standard Schema for `{ query: string }`.
+*
+* Built by hand (no `seal` / `zod` import) so `asTool()` stays dependency-
+* free and matches the framework's own `passthroughSchema` style — the
+* `~standard.validate` returns `{ issues }` on a bad shape so the tool
+* runtime surfaces a `SchemaValidationError` exactly like any other tool.
+*/
+function ragToolSchema() {
+	return { "~standard": {
+		version: 1,
+		vendor: "warlock-ai-rag",
+		validate: (value) => {
+			if (!value || typeof value !== "object" || typeof value.query !== "string") return { issues: [{ message: "rag tool input must be { query: string }" }] };
+			return { value: { query: value.query } };
+		}
+	} };
+}
+/**
+* Build a `ToolContract<{ query: string }, RetrieveResult>` that exposes a
+* rag's `retrieve()` to an agent's `tools: []` loop.
+*
+* `retrieve()` is a leaf operation (no inner executable report to nest),
+* so the plain `tool()` factory is the right shape — not `compositeAsTool`.
+* The resulting contract has `invoke`, so `isExecutableTool` returns false
+* and `normalizeAgentTools` passes it through untouched. On a thrown
+* retrieval error the runtime serializes `{ error }` back to the agent for
+* self-correction; the run does not abort.
+*
+* The tool name defaults to `retrieve_<name>` — namespaced by the rag's
+* name because the agent tool surface has no duplicate-name collision
+* guard (first match wins silently).
+*/
+function ragAsTool(name, retrieveFn, options = {}) {
+	return tool({
+		name: options.name ?? `retrieve_${name}`,
+		description: options.description ?? `Search the "${name}" knowledge base and return the most relevant cited passages for a query.`,
+		input: ragToolSchema(),
+		execute: async ({ query }) => retrieveFn(query, options.retrieve)
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/retrieve.ts
+/** Default number of chunks returned after reranking. */
+const DEFAULT_TOP_K = 5;
+/** Default cosine floor applied at the vector-store stage. */
+const DEFAULT_THRESHOLD = .5;
+/**
+* The cite pipeline: embed the query → over-fetch candidates from the
+* store → filter to this rag's namespace → map to {@link RetrievedChunk}s
+* with a {@link Citation} → optionally rerank → slice `topK`.
+*
+* Behavior matches the design's failure modes:
+* - No hits clearing the threshold → `{ query, chunks: [] }`, never throws.
+* - Namespace-prefix filtering keeps two rags sharing one driver isolated.
+* - A reranker that throws is caught; the raw cosine order is used instead.
+* - A dimension mismatch (indexed with model A, queried with model B)
+*   throws a clear error rather than returning garbage hits.
+*/
+async function retrieve(query, deps, options = {}) {
+	const topK = options.topK ?? deps.defaults?.topK ?? 5;
+	const threshold = options.threshold ?? deps.defaults?.threshold ?? .5;
+	const tags = options.tags ?? deps.defaults?.tags;
+	const candidates = options.candidates ?? deps.defaults?.candidates ?? Math.max(topK * 4, topK);
+	const { vector, dimensions } = await deps.embedder.embed(query);
+	if (deps.indexedDimensions !== void 0 && dimensions !== 0 && deps.indexedDimensions !== 0 && dimensions !== deps.indexedDimensions) throw new Error(`rag.retrieve(): query embedder dimensions (${dimensions}) do not match the dimensions captured at index time (${deps.indexedDimensions}); index and query must use the same embedding model`);
+	const hits = await deps.store.query(vector, {
+		topK: candidates,
+		threshold,
+		tags
+	});
+	const prefix = `${deps.namespace}.`;
+	let retrieved = hits.filter((hit) => hit.key.startsWith(prefix)).map((hit) => toRetrievedChunk(hit.value, hit.score));
+	retrieved = await applyReranker(query, retrieved, deps.reranker);
+	return {
+		query,
+		chunks: retrieved.slice(0, topK)
+	};
+}
+/** Build a cited {@link RetrievedChunk} from a stored chunk + its cosine score. */
+function toRetrievedChunk(stored, score) {
+	const citation = {
+		sourceId: stored.sourceId,
+		chunkIndex: stored.chunkIndex,
+		span: stored.span,
+		score,
+		metadata: stored.metadata
+	};
+	return {
+		text: stored.text,
+		score,
+		citation
+	};
+}
+/**
+* Run the optional reranker, degrading to the raw cosine order if it
+* throws — a flaky optional reranker must never fail the whole retrieval.
+*/
+async function applyReranker(query, candidates, reranker) {
+	if (!reranker) return candidates;
+	try {
+		return await reranker.rerank(query, candidates);
+	} catch {
+		return candidates;
+	}
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/store/cache-vector-store.ts
+/**
+* Adapt any `@warlock.js/cache` `CacheDriver` to the {@link VectorStore}
+* narrowing the RAG pipeline depends on. The cache driver IS the vector
+* store — exactly as `SemanticMemory` and `semanticCache` already use it:
+*
+* - `upsert` → `driver.set(key, value, { vector, tags })`
+* - `query`  → `driver.similar<T>(vector, { topK, threshold, tags })`
+* - `removeNamespace` → `driver.removeNamespace(namespace)`
+*
+* Drivers without similarity support throw `CacheUnsupportedError` from
+* `set({ vector })` / `similar()`; the error surfaces unchanged so the
+* caller sees the cache layer's own message (pointing at the `pg` /
+* `redis` drivers for production-scale similarity).
+*
+* @example
+* const store = cacheVectorStore(new MemoryCacheDriver());
+* await store.upsert("ai.rag.docs.guide.0", { text: "…" }, vector);
+* const hits = await store.query(queryVector, { topK: 5, threshold: 0.5 });
+*/
+function cacheVectorStore(driver) {
+	return {
+		async upsert(key, value, vector, tags) {
+			await driver.set(key, value, tags && tags.length > 0 ? {
+				vector,
+				tags
+			} : { vector });
+		},
+		async query(vector, options) {
+			return (await driver.similar(vector, {
+				topK: options.topK,
+				threshold: options.threshold,
+				tags: options.tags
+			})).map((hit) => ({
+				key: hit.key,
+				value: hit.value,
+				score: hit.score
+			}));
+		},
+		async removeNamespace(namespace) {
+			await driver.removeNamespace(namespace);
+		}
+	};
+}
 
 //#endregion
-//#region ../@warlock.js/ai/src/rag/chunk/markdown.ts
-/** Matches an ATX Markdown heading line (`#` … `######`) at line start. */
-const HEADING_LINE = /^#{1,6}[ \t].*$/gm;
+//#region ../@warlock.js/ai/src/rag/rag.ts
+const DEFAULT_NAME = "rag";
+const DEFAULT_NAMESPACE_PREFIX = "ai.rag";
 /**
-* Markdown heading/section-aware splitter.
+* Max chunk texts embedded per `embedder.embedMany()` call. One call is
+* one provider request, so a giant document is sub-batched to stay under
+* the provider's per-request token cap (the design's "chunk larger than
+* provider per-request cap" guard).
+*/
+const DEFAULT_MAX_BATCH = 96;
+/**
+* Create a RAG pipeline: **chunk → embed → vector store → retrieve →
+* rerank → cite**, reusing the app's `ai.embedder` for embedding, a
+* `@warlock.js/cache` `CacheDriver` as the vector store, and the
+* composite-as-tool engine to expose retrieval as a tool.
 *
-* Splits the document on ATX heading boundaries (`#`…`######`) first so a
-* section's heading stays glued to its body, then applies the recursive
-* character splitter WITHIN each section so any section larger than `size`
-* is broken down further. Sections at or under `size` are emitted whole.
-* Spans are exact relative to the original document.
+* Resolution is loud at construction (mirroring `memory()`):
+* - `embedder` is required — a provider with no embedder must be caught
+*   here, not at first index.
+* - `store` falls back to `ai.config({ defaultStore })`; if neither
+*   resolves, construction throws.
+*
+* `retrieve()` is return-only — it never auto-injects into a prompt; the
+* caller formats the cited chunks (or uses `asTool()` for the agent loop).
+* The reranker is OFF by default (cosine-only) unless `config.reranker`
+* is set.
+*
+* @example
+* import { ai } from "@warlock.js/ai";
+* import { MemoryCacheDriver } from "@warlock.js/cache";
+*
+* const kb = ai.rag({
+*   name: "docs",
+*   embedder: openai.embedder({ name: "text-embedding-3-small" }),
+*   store: new MemoryCacheDriver(),
+*   chunk: { type: "markdown", size: 800, overlap: 120 },
+* });
+*
+* await kb.index([{ id: "guide", text: longMarkdown, metadata: { url: "/guide" } }]);
+* const { chunks } = await kb.retrieve("how do I configure caching?", { topK: 4 });
 */
-function markdownChunk(text, size, overlap, separators = DEFAULT_SEPARATORS) {
-	if (text.length === 0) return [];
-	const sections = splitSections(text);
-	const chunks = [];
-	let index = 0;
-	for (const section of sections) {
-		const body = text.slice(section.start, section.end);
-		if (body.trim().length === 0) continue;
-		if (body.length <= size) {
-			chunks.push({
-				text: body,
-				index,
-				span: [section.start, section.end]
-			});
-			index += 1;
-			continue;
-		}
-		const inner = recursiveChunk(body, size, overlap, separators);
-		for (const piece of inner) {
-			chunks.push({
-				text: piece.text,
-				index,
-				span: [section.start + piece.span[0], section.start + piece.span[1]]
-			});
-			index += 1;
+function rag(config) {
+	const name = config.name ?? DEFAULT_NAME;
+	if (!config.embedder) throw new Error(`rag("${name}"): an \`embedder\` is required — pass one from a provider that supports embeddings (e.g. openai.embedder({ name: "text-embedding-3-small" }))`);
+	const driver = config.store ?? resolveDefaultStore();
+	if (!driver) throw new Error(`rag("${name}"): no store — pass \`store\` (a vector-capable @warlock.js/cache CacheDriver) or call \`ai.config({ defaultStore })\` at app boot before constructing the rag`);
+	const store = cacheVectorStore(driver);
+	const namespace = config.namespace ?? `${DEFAULT_NAMESPACE_PREFIX}.${name}`;
+	const embedder = config.embedder;
+	let indexedDimensions;
+	const instance = {
+		name,
+		async index(docs, chunkOverride) {
+			const chunkOptions = chunkOverride ?? config.chunk;
+			const limits = config.limits;
+			if (limits?.maxDocuments !== void 0 && docs.length > limits.maxDocuments) throw new Error(`rag("${name}"): index() received ${docs.length} documents, exceeding the configured maxDocuments of ${limits.maxDocuments}`);
+			if (limits?.maxBytes !== void 0) {
+				const totalBytes = docs.reduce((sum, doc) => sum + Buffer.byteLength(doc.text ?? ""), 0);
+				if (totalBytes > limits.maxBytes) throw new Error(`rag("${name}"): index() received ${totalBytes} bytes of document text, exceeding the configured maxBytes of ${limits.maxBytes}`);
+			}
+			const records = [];
+			for (const doc of docs) {
+				const pieces = chunk(doc.text, chunkOptions);
+				for (const piece of pieces) {
+					const value = {
+						sourceId: doc.id,
+						chunkIndex: piece.index,
+						span: piece.span,
+						text: piece.text,
+						metadata: doc.metadata
+					};
+					records.push({
+						key: keyFor(namespace, doc.id, piece.index),
+						value,
+						text: piece.text,
+						tags: doc.tags
+					});
+				}
+			}
+			if (records.length === 0) return { chunks: 0 };
+			if (limits?.maxChunks !== void 0 && records.length > limits.maxChunks) throw new Error(`rag("${name}"): index() produced ${records.length} chunks, exceeding the configured maxChunks of ${limits.maxChunks}`);
+			for (let offset = 0; offset < records.length; offset += DEFAULT_MAX_BATCH) {
+				const batch = records.slice(offset, offset + DEFAULT_MAX_BATCH);
+				const { vectors, dimensions } = await embedder.embedMany(batch.map((record) => record.text));
+				if (indexedDimensions === void 0 && dimensions !== 0) indexedDimensions = dimensions;
+				await Promise.all(batch.map((record, position) => store.upsert(record.key, record.value, vectors[position], record.tags)));
+			}
+			return { chunks: records.length };
+		},
+		async retrieve(query, options) {
+			return retrieve(query, {
+				embedder,
+				store,
+				namespace,
+				reranker: config.reranker,
+				defaults: config.retrieve,
+				indexedDimensions
+			}, options);
+		},
+		async clear() {
+			await store.removeNamespace(namespace);
+		},
+		asTool(options) {
+			return ragAsTool(name, (query, retrieveOptions) => instance.retrieve(query, retrieveOptions), options);
 		}
-	}
-	return chunks;
+	};
+	return instance;
 }
 /**
-* Carve the document into sections, each beginning at a heading line and
-* running until the next heading (the preamble before the first heading is
-* its own section). Spans cover the whole document with no gaps.
+* Namespaced key for a stored chunk. Uses the `.` separator (matching
+* `SemanticMemory.keyFor`) so namespace-prefix filtering on the returned
+* `hit.key` stays aligned with the cache's `parseKey` normalization.
 */
-function splitSections(text) {
-	const starts = [];
-	let match;
-	HEADING_LINE.lastIndex = 0;
-	while ((match = HEADING_LINE.exec(text)) !== null) starts.push(match.index);
-	if (starts.length === 0) return [{
-		start: 0,
-		end: text.length
-	}];
-	const sections = [];
-	if (starts[0] > 0) sections.push({
-		start: 0,
-		end: starts[0]
-	});
-	starts.forEach((start, position) => {
-		const end = position + 1 < starts.length ? starts[position + 1] : text.length;
-		sections.push({
-			start,
-			end
-		});
-	});
-	return sections;
+function keyFor(namespace, sourceId, chunkIndex) {
+	return `${namespace}.${sourceId}.${chunkIndex}`;
 }
 
 //#endregion
-//#region ../@warlock.js/ai/src/rag/chunk/sentence.ts
-/** Matches a sentence terminator (`.`, `!`, `?`) followed by whitespace. */
-const SENTENCE_BOUNDARY = /([.!?])\s+/g;
+//#region ../@warlock.js/ai/src/rag/store/pg-vector-store.ts
 /**
-* Sentence-aware character splitter.
-*
-* Splits the text on sentence terminators (`. `, `! `, `? `), keeping the
-* terminator attached, then greedily packs whole sentences into chunks up
-* to `size` characters, carrying `overlap` characters forward between
-* adjacent chunks. A single sentence longer than `size` becomes its own
-* (oversize) chunk rather than being cut mid-sentence. Spans are exact.
+* Default backing table — provisions the store with no extra config when
+* the dev runs {@link VectorStore.schema | ensureSchema} through their
+* migration tool.
 */
-function sentenceChunk(text, size, overlap) {
-	if (text.trim().length === 0) return [];
-	const sentences = splitSentences(text);
-	const chunks = [];
-	let bufferStart = -1;
-	let bufferEnd = -1;
-	let index = 0;
-	const flush = () => {
-		if (bufferStart === -1) return;
-		chunks.push({
-			text: text.slice(bufferStart, bufferEnd),
-			index,
-			span: [bufferStart, bufferEnd]
-		});
-		index += 1;
-	};
-	for (const sentence of sentences) {
-		if (bufferStart === -1) {
-			bufferStart = sentence.start;
-			bufferEnd = sentence.end;
-			continue;
-		}
-		if (sentence.end - bufferStart <= size) {
-			bufferEnd = sentence.end;
-			continue;
-		}
-		flush();
-		bufferStart = overlap > 0 ? Math.max(bufferStart, sentence.start - overlap) : sentence.start;
-		bufferEnd = sentence.end;
-	}
-	flush();
-	return chunks;
-}
+const DEFAULT_TABLE$1 = "warlock_ai_rag_vectors";
+/** Default embedding width baked into the DDL (OpenAI `text-embedding-3-small`). */
+const DEFAULT_DIMENSIONS = 1536;
+/** Default `ivfflat` list count when that index strategy is chosen. */
+const DEFAULT_IVFFLAT_LISTS = 100;
 /**
-* Split `text` into sentence spans on terminator + whitespace, keeping the
-* terminator with its sentence and absorbing the trailing whitespace into
-* the boundary so reconstructing the spans loses no characters.
+* Allowed characters in a Postgres identifier (table name). The table name
+* is interpolated into DDL/DML, so anything outside this conservative
+* ASCII subset is rejected — interpolating an arbitrary string would be a
+* SQL-injection footgun (mirrors the snapshot / human-interrupt pg stores
+* and `@warlock.js/cache`'s `PgCacheDriver`).
 */
-function splitSentences(text) {
-	const spans = [];
-	let start = 0;
-	let match;
-	SENTENCE_BOUNDARY.lastIndex = 0;
-	while ((match = SENTENCE_BOUNDARY.exec(text)) !== null) {
-		const end = match.index + match[0].length;
-		spans.push({
-			start,
-			end
-		});
-		start = end;
+const SAFE_IDENTIFIER$1 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Module specifier for the optional `pg` driver. Held in a `string`
+* variable so the dynamic `import()` is not statically resolved at compile
+* time — `pg` is an optional peer that need not be installed for this
+* package to type-check or for a cache-only consumer to run.
+*/
+const PG_MODULE = "pg";
+/**
+* Curated install string surfaced (at use time) when a `connectionString`
+* is configured but the optional `pg` driver is absent. Never thrown at
+* import — a cache-only consumer must be able to load this module.
+*/
+const PG_INSTALL_INSTRUCTIONS = `
+The @warlock.js/ai Postgres vector store requires the pg package and a
+Postgres database with the pgvector extension. Install the driver with:
+
+  npm install pg
+
+Or with your preferred package manager:
+
+  pnpm add pg
+  yarn add pg
+`.trim();
+/**
+* Lazily import `pg` and return a `Pool` built from `connectionString`. A
+* bare `catch` rethrows the curated install string — a missing optional
+* peer surfaces as actionable guidance, never a raw resolution error.
+*/
+async function buildPgClient(connectionString) {
+	let sdk;
+	try {
+		sdk = await import(PG_MODULE);
+	} catch {
+		throw new Error(PG_INSTALL_INSTRUCTIONS);
 	}
-	if (start < text.length) spans.push({
-		start,
-		end: text.length
-	});
-	return spans;
+	return new sdk.Pool({ connectionString });
 }
-
-//#endregion
-//#region ../@warlock.js/ai/src/rag/chunk/chunk.ts
-/** Default target chunk size in characters. */
-const DEFAULT_CHUNK_SIZE = 1e3;
-/** Default character overlap carried between adjacent chunks. */
-const DEFAULT_CHUNK_OVERLAP = 200;
 /**
-* Split `text` into citation-bearing {@link Chunk}s according to
-* {@link ChunkOptions}, dispatching on `options.type`:
-*
-* - `"recursive"` (default) — separator-aware greedy packing.
-* - `"markdown"` — heading/section-aware, then recursive within sections.
-* - `"sentence"` — packs whole sentences.
-* - `"fixed"` — back-to-back character windows.
+* Serialize a JS `number[]` to the pgvector text literal: `[1,2,3]`.
+* pgvector accepts a vector either as this bracketed literal or via a
+* typed parameter; passing the literal string + an explicit `::vector`
+* cast keeps the store driver-agnostic (no dependency on a registered
+* `pg` type parser).
 *
-* All strategies are character-based (tokenizer-free) and record the exact
-* `[start, end)` span of every chunk in the original text. Empty or
-* whitespace-only input yields `[]`.
+* Non-finite components (`NaN` / `±Infinity`) are rejected — pgvector
+* stores only finite floats, and silently coercing them would corrupt the
+* index. The check is cheap relative to the embed call that produced the
+* vector.
 *
 * @example
-* const chunks = chunk(markdownDoc, { type: "markdown", size: 800, overlap: 120 });
-* for (const c of chunks) console.log(c.index, c.span, c.text);
+* vectorLiteral([1, 0.5, -2]); // "[1,0.5,-2]"
 */
-function chunk(text, options = {}) {
-	const type = options.type ?? "recursive";
-	const size = options.size ?? 1e3;
-	const overlap = options.overlap ?? 200;
-	const separators = options.separators ?? DEFAULT_SEPARATORS;
-	if (text.trim().length === 0) return [];
-	switch (type) {
-		case "markdown": return markdownChunk(text, size, overlap, separators);
-		case "sentence": return sentenceChunk(text, size, overlap);
-		case "fixed": return fixedChunk(text, size, overlap);
-		default: return recursiveChunk(text, size, overlap, separators);
+function vectorLiteral(vector) {
+	let literal = "[";
+	for (let index = 0; index < vector.length; index++) {
+		const component = vector[index];
+		if (!Number.isFinite(component)) throw new TypeError(`pgVectorStore: embedding component at index ${index} is not finite (${component}); pgvector stores only finite floats.`);
+		if (index > 0) literal += ",";
+		literal += String(component);
 	}
+	return literal + "]";
 }
-
-//#endregion
-//#region ../@warlock.js/ai/src/rag/as-tool.ts
 /**
-* A minimal, schema-library-agnostic Standard Schema for `{ query: string }`.
+* Coerce a `value` JSONB column back into the stored payload. node-postgres
+* parses `JSONB` into a JS value already, but some pool wrappers hand back
+* the raw string — be defensive across both (mirrors the snapshot store's
+* `parsePayload`).
+*/
+function parseValue(value) {
+	if (typeof value === "string") return JSON.parse(value);
+	return value;
+}
+/**
+* Coerce a pgvector cosine **distance** (`<=>`, in `[0, 2]`, 0 = identical)
+* into the cosine **similarity** score the {@link VectorStore} contract
+* declares (`[0, 1]`, 1 = identical). `pg` returns the computed distance
+* column as a string for `double precision`; parse then map `1 - distance`,
+* clamped to `[0, 1]` so a tiny floating-point overshoot never yields a
+* score just outside the contract's range.
+*/
+function distanceToScore(distance) {
+	const score = 1 - (typeof distance === "string" ? Number(distance) : distance);
+	if (score < 0) return 0;
+	if (score > 1) return 1;
+	return score;
+}
+/**
+* Postgres + pgvector-backed {@link VectorStore} — one durable row per
+* indexed chunk, keyed by the RAG pipeline's dotted `key`
+* (`ai.rag.<name>.<sourceId>.<chunkIndex>`), with the chunk payload in a
+* `value` JSONB column and the embedding in a `vector` column.
 *
-* Built by hand (no `seal` / `zod` import) so `asTool()` stays dependency-
-* free and matches the framework's own `passthroughSchema` style — the
-* `~standard.validate` returns `{ issues }` on a bad shape so the tool
-* runtime surfaces a `SchemaValidationError` exactly like any other tool.
+* Owns: the three RAG vector operations against a pgvector index —
+* `upsert` (INSERT … ON CONFLICT DO UPDATE), `query` (cosine
+* `ORDER BY embedding <=> $vec` with a `threshold` floor + optional `tags`
+* overlap filter, capped at `topK`), and `removeNamespace` (prefix DELETE).
+* Also emits the reference DDL via {@link PgVectorStore.schema} (alias
+* {@link PgVectorStore.ensureSchema}).
+*
+* Does NOT own: the connection lifecycle (a dev-supplied `client` is never
+* closed; a store-built `Pool` from a `connectionString` is also left open
+* for the process to reuse) or schema migration — the dev runs the DDL
+* through their own tool; the framework never auto-migrates.
+*
+* Front it with the {@link pgVectorStore} factory — callers never `new` it.
 */
-function ragToolSchema() {
-	return { "~standard": {
-		version: 1,
-		vendor: "warlock-ai-rag",
-		validate: (value) => {
-			if (!value || typeof value !== "object" || typeof value.query !== "string") return { issues: [{ message: "rag tool input must be { query: string }" }] };
-			return { value: { query: value.query } };
+var PgVectorStore = class {
+	constructor(options) {
+		const table = options.table ?? DEFAULT_TABLE$1;
+		if (!SAFE_IDENTIFIER$1.test(table)) throw new TypeError(`pgVectorStore: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+		this.table = table;
+		this.dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;
+		this.index = options.index ?? "hnsw";
+		this.ivfflatLists = options.ivfflatLists ?? DEFAULT_IVFFLAT_LISTS;
+		if (options.client) {
+			if (typeof options.client.query !== "function") throw new TypeError("pgVectorStore requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.");
+			this.clientPromise = Promise.resolve(options.client);
+			return;
 		}
-	} };
-}
+		if (options.connectionString) {
+			this.clientPromise = buildPgClient(options.connectionString);
+			return;
+		}
+		throw new TypeError("pgVectorStore requires either a 'client' or a 'connectionString' option.");
+	}
+	/**
+	* Resolve the backing client, surfacing the lazy `pg` import's curated
+	* install string on the first call that needs it.
+	*/
+	client() {
+		return this.clientPromise;
+	}
+	/**
+	* Index `value` under `key` with its embedding `vector`. Upserts on the
+	* `key` primary key — re-indexing the same chunk overwrites its payload,
+	* embedding, and tags rather than appending a duplicate row. Optional
+	* `tags` ride a `text[]` column so {@link query} can restrict the
+	* candidate set with an array-overlap filter.
+	*
+	* The embedding is sent as a pgvector text literal (`$3`) cast to
+	* `::vector`, so the store needs no registered `pg` type parser. `tags`
+	* defaults to an empty array (never `NULL`) to keep the overlap filter's
+	* `&&` semantics simple.
+	*/
+	async upsert(key, value, vector, tags) {
+		await (await this.client()).query(`INSERT INTO ${this.table} (key, value, embedding, tags)
+       VALUES ($1, $2::jsonb, $3::vector, $4::text[])
+       ON CONFLICT (key) DO UPDATE
+         SET value = EXCLUDED.value,
+             embedding = EXCLUDED.embedding,
+             tags = EXCLUDED.tags`, [
+			key,
+			JSON.stringify(value),
+			vectorLiteral(vector),
+			tags ?? []
+		]);
+	}
+	/**
+	* Return the cosine-nearest rows to `vector`, mapped to the contract's
+	* `{ key, value, score }` shape. The SQL:
+	*
+	* - computes `embedding <=> $1::vector` (cosine **distance**) once, aliased
+	*   `distance`, and `ORDER BY` it ascending (nearest first);
+	* - applies the `threshold` floor as `distance <= 1 - threshold`
+	*   (similarity `>=` threshold), so the default `0.5` floor maps to a
+	*   `<= 0.5` distance bound — the filter runs in SQL, not in JS, so a
+	*   below-floor row never crosses the wire;
+	* - when `tags` are given, restricts to rows whose `tags` array overlaps
+	*   the requested set via `tags && $tags::text[]` (one-of semantics,
+	*   matching the cache store);
+	* - caps the result at `topK` with `LIMIT`.
+	*
+	* The returned `score` is `1 - distance`, clamped to `[0, 1]`, so callers
+	* see the same cosine-similarity scale the cache store emits.
+	*/
+	async query(vector, options) {
+		const client = await this.client();
+		const params = [vectorLiteral(vector), options.topK];
+		const conditions = [];
+		if (options.threshold !== void 0) {
+			params.push(1 - options.threshold);
+			conditions.push(`(embedding <=> $1::vector) <= $${params.length}`);
+		}
+		if (options.tags !== void 0 && options.tags.length > 0) {
+			params.push(options.tags);
+			conditions.push(`tags && $${params.length}::text[]`);
+		}
+		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		const { rows } = await client.query(`SELECT key, value, (embedding <=> $1::vector) AS distance
+       FROM ${this.table}
+       ${where}
+       ORDER BY embedding <=> $1::vector
+       LIMIT $2`, params);
+		return rows.map((row) => ({
+			key: row.key,
+			value: parseValue(row.value),
+			score: distanceToScore(row.distance)
+		}));
+	}
+	/**
+	* Drop every entry written under `namespace`. The RAG pipeline keys
+	* chunks as `<namespace>.<sourceId>.<chunkIndex>`, so a row belongs to
+	* the namespace when its `key` equals it OR begins with `<namespace>.`
+	* — deleting `ai.rag.docs` must not also catch `ai.rag.docs2`. The `_`
+	* and `%` LIKE wildcards in the namespace are escaped so a namespace
+	* that happens to contain them is matched literally.
+	*/
+	async removeNamespace(namespace) {
+		const client = await this.client();
+		const escaped = namespace.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
+		await client.query(`DELETE FROM ${this.table}
+       WHERE key = $1 OR key LIKE $2 ESCAPE '\\'`, [namespace, `${escaped}.%`]);
+	}
+	/**
+	* Return the reference migration DDL for this store's backing table,
+	* interpolating the configured table name, embedding width, and ANN
+	* index strategy. The dev runs it once through their migration tool —
+	* the framework never auto-migrates.
+	*
+	* The emitted statements:
+	* 1. `CREATE EXTENSION IF NOT EXISTS vector;` — enables pgvector (needs
+	*    a superuser or a role with `CREATE` on the database the first time).
+	* 2. `CREATE TABLE IF NOT EXISTS <table> (key TEXT PRIMARY KEY, value
+	*    JSONB NOT NULL, embedding vector(<dimensions>) NOT NULL, tags
+	*    text[] NOT NULL DEFAULT '{}');`
+	* 3. A GIN index on `tags` so the array-overlap filter stays sargable.
+	* 4. The chosen ANN index over `embedding` using `vector_cosine_ops`:
+	*    - `"hnsw"` → `USING hnsw (embedding vector_cosine_ops)`;
+	*    - `"ivfflat"` → `USING ivfflat (embedding vector_cosine_ops)
+	*      WITH (lists = <ivfflatLists>)`;
+	*    - `"none"` → emitted as a comment (exact scan, no ANN index).
+	*
+	* @example
+	* const store = pgVectorStore({ client: pool, dimensions: 1536 });
+	* await pool.query(store.ensureSchema());
+	*/
+	schema() {
+		const lines = [
+			`CREATE EXTENSION IF NOT EXISTS vector;`,
+			`CREATE TABLE IF NOT EXISTS ${this.table} (`,
+			`  key        TEXT PRIMARY KEY,`,
+			`  value      JSONB NOT NULL,`,
+			`  embedding  vector(${this.dimensions}) NOT NULL,`,
+			`  tags       TEXT[] NOT NULL DEFAULT '{}'`,
+			`);`,
+			`CREATE INDEX IF NOT EXISTS idx_${this.table}_tags`,
+			`  ON ${this.table} USING gin (tags);`
+		];
+		if (this.index === "hnsw") lines.push(`CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`, `  ON ${this.table} USING hnsw (embedding vector_cosine_ops);`);
+		else if (this.index === "ivfflat") lines.push(`CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`, `  ON ${this.table} USING ivfflat (embedding vector_cosine_ops)`, `  WITH (lists = ${this.ivfflatLists});`);
+		else lines.push(`-- No ANN index requested (index: "none"): cosine queries fall back`, `-- to an exact sequential scan, which is correct but linear in rows.`);
+		return lines.join("\n");
+	}
+	/**
+	* Alias for {@link PgVectorStore.schema} — reads more naturally in a
+	* migration script (`await pool.query(store.ensureSchema())`). Returns
+	* the identical DDL string; it does NOT execute anything against the
+	* database (the store never auto-migrates).
+	*/
+	ensureSchema() {
+		return this.schema();
+	}
+};
 /**
-* Build a `ToolContract<{ query: string }, RetrieveResult>` that exposes a
-* rag's `retrieve()` to an agent's `tools: []` loop.
+* Create a Postgres + pgvector-backed {@link VectorStore} for the RAG
+* pipeline. Either pass a live `pg.Pool` / `pg.Client` (`{ client }`) —
+* `@warlock.js/ai` never imports `pg` in that case — or a
+* `{ connectionString }` and let the store lazily `import("pg")` to build
+* its own pool. When `pg` is not installed, a curated install string
+* surfaces on first use, never at import.
 *
-* `retrieve()` is a leaf operation (no inner executable report to nest),
-* so the plain `tool()` factory is the right shape — not `compositeAsTool`.
-* The resulting contract has `invoke`, so `isExecutableTool` returns false
-* and `normalizeAgentTools` passes it through untouched. On a thrown
-* retrieval error the runtime serializes `{ error }` back to the agent for
-* self-correction; the run does not abort.
+* Run {@link PgVectorStoreInstance.ensureSchema} through your migration
+* tool once before use (it enables the `vector` extension, creates the
+* table, and builds the tag + ANN indexes); the store never auto-migrates.
 *
-* The tool name defaults to `retrieve_<name>` — namespaced by the rag's
-* name because the agent tool surface has no duplicate-name collision
-* guard (first match wins silently).
+* Index and query MUST use the same embedding model — the `vector(N)`
+* column width is fixed at table-creation time from `dimensions`.
+*
+* @example
+* import { Pool } from "pg";
+* import { ai } from "@warlock.js/ai";
+*
+* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+* const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });
+*
+* // Once, via your migration tooling:
+* // await pool.query(store.ensureSchema());
+*
+* const kb = ai.rag({
+*   name: "docs",
+*   embedder: openai.embedder({ name: "text-embedding-3-small" }),
+*   store,
+* });
+*
+* @example
+* // Let the store build its own pool from a connection string:
+* const store = ai.rag.pgVectorStore({
+*   connectionString: process.env.DATABASE_URL,
+*   index: "ivfflat",
+*   ivfflatLists: 200,
+* });
 */
-function ragAsTool(name, retrieveFn, options = {}) {
-	return tool({
-		name: options.name ?? `retrieve_${name}`,
-		description: options.description ?? `Search the "${name}" knowledge base and return the most relevant cited passages for a query.`,
-		input: ragToolSchema(),
-		execute: async ({ query }) => retrieveFn(query, options.retrieve)
-	});
+function pgVectorStore(options) {
+	return new PgVectorStore(options);
 }
 
 //#endregion
-//#region ../@warlock.js/ai/src/rag/retrieve.ts
-/** Default number of chunks returned after reranking. */
-const DEFAULT_TOP_K = 5;
-/** Default cosine floor applied at the vector-store stage. */
-const DEFAULT_THRESHOLD = .5;
+//#region ../@warlock.js/ai/src/rag/loaders/load-text.ts
+/** Default `id` when the caller supplies neither `id` nor an item id. */
+const DEFAULT_ID$2 = "document";
 /**
-* The cite pipeline: embed the query → over-fetch candidates from the
-* store → filter to this rag's namespace → map to {@link RetrievedChunk}s
-* with a {@link Citation} → optionally rerank → slice `topK`.
+* Load plain text into {@link RagDocument}(s) — the zero-dependency base
+* loader every other loader ultimately funnels into. Accepts a single
+* string, a single `{ id, text }` record, or an array mixing both; each
+* input becomes one document carrying `metadata.loader = "text"` plus a
+* `metadata.source` (the resolved id).
 *
-* Behavior matches the design's failure modes:
-* - No hits clearing the threshold → `{ query, chunks: [] }`, never throws.
-* - Namespace-prefix filtering keeps two rags sharing one driver isolated.
-* - A reranker that throws is caught; the raw cosine order is used instead.
-* - A dimension mismatch (indexed with model A, queried with model B)
-*   throws a clear error rather than returning garbage hits.
+* Caller `metadata` always wins over the loader-derived keys, and per-item
+* `metadata` / `tags` (when an item is a record) layer on top of the shared
+* option values. Empty / whitespace-only items are dropped — they would
+* chunk to nothing anyway, so the result never carries a no-op document.
+*
+* The output is the exact shape `index()` consumes:
+*
+* @example
+* const kb = ai.rag({ embedder, store });
+* await kb.index(loadText("a long string of notes…"));
+*
+* @example
+* await kb.index(loadText([
+*   { id: "faq-1", text: "…", metadata: { section: "billing" } },
+*   { id: "faq-2", text: "…" },
+* ]));
+*
+* @param input - A string, a `{ id, text }` record, or an array of either.
+* @param options - Shared `id` / `metadata` / `tags` ({@link LoadTextOptions}).
+* @returns A {@link RagLoaderResult} ready to hand to `rag.index()`.
+*/
+function loadText(input, options = {}) {
+	const items = Array.isArray(input) ? input : [input];
+	const baseId = options.id ?? DEFAULT_ID$2;
+	const multiple = items.length > 1;
+	const docs = [];
+	items.forEach((item, index) => {
+		const text = typeof item === "string" ? item : item.text;
+		if (text.trim().length === 0) return;
+		const id = (typeof item === "string" ? void 0 : item.id) ?? (multiple ? `${baseId}#${index}` : baseId);
+		const itemMetadata = typeof item === "string" ? void 0 : item.metadata;
+		const itemTags = typeof item === "string" ? void 0 : item.tags;
+		docs.push({
+			id,
+			text,
+			metadata: {
+				source: id,
+				loader: "text",
+				...options.metadata,
+				...itemMetadata
+			},
+			tags: itemTags ?? options.tags
+		});
+	});
+	return docs;
+}
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/loaders/load-html.ts
+/** Default `id` when the caller supplies none. */
+const DEFAULT_ID$1 = "document";
+/**
+* Elements whose *content* is not human-readable text and must be removed
+* wholesale (open tag → close tag → everything in between) before tags are
+* stripped. `script` / `style` would otherwise leak code into the chunked
+* text; `noscript` / `template` / `head` / `svg` are non-prose noise.
+*/
+const STRIPPED_ELEMENTS = [
+	"script",
+	"style",
+	"noscript",
+	"template",
+	"head",
+	"svg"
+];
+/**
+* Block-level tags that imply a line break in the readable text. Replacing
+* them with `\n` BEFORE the generic tag strip keeps paragraph / list / table
+* structure (so the recursive splitter still sees `\n\n` boundaries) instead
+* of collapsing the whole page onto one line.
+*/
+const BLOCK_TAGS = /<\/?(?:p|div|section|article|header|footer|main|aside|nav|h[1-6]|ul|ol|li|table|tr|td|th|thead|tbody|blockquote|pre|hr|br)\b[^>]*>/gi;
+/** Named HTML entities common in prose. Numeric entities are decoded generically. */
+const NAMED_ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " ",
+	copy: "©",
+	reg: "®",
+	trade: "™",
+	hellip: "…",
+	mdash: "—",
+	ndash: "–",
+	lsquo: "‘",
+	rsquo: "’",
+	ldquo: "“",
+	rdquo: "”",
+	laquo: "«",
+	raquo: "»",
+	middot: "·",
+	bull: "•"
+};
+/**
+* Decode the HTML entities that survive tag stripping: named (`&amp;`),
+* decimal (`&#169;`), and hex (`&#xA9;`). Unknown named entities are left
+* verbatim rather than dropped, so unusual markup never silently loses text.
 */
-async function retrieve(query, deps, options = {}) {
-	const topK = options.topK ?? deps.defaults?.topK ?? 5;
-	const threshold = options.threshold ?? deps.defaults?.threshold ?? .5;
-	const tags = options.tags ?? deps.defaults?.tags;
-	const candidates = options.candidates ?? deps.defaults?.candidates ?? Math.max(topK * 4, topK);
-	const { vector, dimensions } = await deps.embedder.embed(query);
-	if (deps.indexedDimensions !== void 0 && dimensions !== 0 && deps.indexedDimensions !== 0 && dimensions !== deps.indexedDimensions) throw new Error(`rag.retrieve(): query embedder dimensions (${dimensions}) do not match the dimensions captured at index time (${deps.indexedDimensions}); index and query must use the same embedding model`);
-	const hits = await deps.store.query(vector, {
-		topK: candidates,
-		threshold,
-		tags
+function decodeEntities(text) {
+	return text.replace(/&(#x?[0-9a-f]+|[a-z][a-z0-9]*);/gi, (match, body) => {
+		if (body[0] === "#") {
+			const codePoint = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+			if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 1114111) return match;
+			try {
+				return String.fromCodePoint(codePoint);
+			} catch {
+				return match;
+			}
+		}
+		return NAMED_ENTITIES[body.toLowerCase()] ?? match;
 	});
-	const prefix = `${deps.namespace}.`;
-	let retrieved = hits.filter((hit) => hit.key.startsWith(prefix)).map((hit) => toRetrievedChunk(hit.value, hit.score));
-	retrieved = await applyReranker(query, retrieved, deps.reranker);
-	return {
-		query,
-		chunks: retrieved.slice(0, topK)
-	};
 }
-/** Build a cited {@link RetrievedChunk} from a stored chunk + its cosine score. */
-function toRetrievedChunk(stored, score) {
-	const citation = {
-		sourceId: stored.sourceId,
-		chunkIndex: stored.chunkIndex,
-		span: stored.span,
-		score,
-		metadata: stored.metadata
-	};
-	return {
-		text: stored.text,
-		score,
-		citation
-	};
+/**
+* Pull the `<title>` text out of the document, decoded and trimmed, or
+* `undefined` when there is none. Read BEFORE `<head>` is stripped.
+*/
+function extractTitle(html) {
+	const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+	if (!match) return;
+	const title = decodeEntities(match[1]).replace(/\s+/g, " ").trim();
+	return title.length > 0 ? title : void 0;
 }
 /**
-* Run the optional reranker, degrading to the raw cosine order if it
-* throws — a flaky optional reranker must never fail the whole retrieval.
+* Strip HTML markup down to readable plain text — a lightweight,
+* dependency-free pass (no DOM parser): drop comments and non-prose elements
+* (`script` / `style` / `head` / `svg` / …) content-and-all, convert block
+* tags to line breaks to preserve paragraph structure, remove every
+* remaining tag, decode entities, then collapse runs of whitespace while
+* keeping blank-line paragraph separators.
 */
-async function applyReranker(query, candidates, reranker) {
-	if (!reranker) return candidates;
-	try {
-		return await reranker.rerank(query, candidates);
-	} catch {
-		return candidates;
+function htmlToText(html) {
+	let text = html;
+	text = text.replace(/<!--[\s\S]*?-->/g, " ");
+	for (const tag of STRIPPED_ELEMENTS) {
+		const element = new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, "gi");
+		text = text.replace(element, " ");
+		text = text.replace(new RegExp(`<\\/?${tag}\\b[^>]*>`, "gi"), " ");
 	}
+	text = text.replace(BLOCK_TAGS, "\n");
+	text = text.replace(/<[^>]+>/g, "");
+	text = decodeEntities(text);
+	text = text.replace(/[^\S\n]+/g, " ").replace(/[ \t]*\n[ \t]*/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+	return text;
+}
+/**
+* Load an HTML string into a single {@link RagDocument} of readable text.
+* Scripts, styles, and other non-prose elements are dropped content-and-all,
+* block tags become line breaks (so paragraph structure survives for the
+* splitter), remaining tags are stripped, and HTML entities are decoded — a
+* lightweight regex pass, no heavy DOM dependency.
+*
+* The document's `metadata.title` is set from the page's `<title>` (unless
+* the caller overrode it), and `metadata.loader` is `"html"`. The output is
+* the exact shape `index()` consumes.
+*
+* @example
+* const kb = ai.rag({ embedder, store });
+* await kb.index(loadHtml(rawHtmlString, { id: "landing-page" }));
+*
+* @param html - The raw HTML markup.
+* @param options - Shared `id` / `metadata` / `tags` ({@link LoadHtmlOptions}).
+* @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.
+*/
+function loadHtml(html, options = {}) {
+	const id = options.id ?? DEFAULT_ID$1;
+	const title = extractTitle(html);
+	const text = htmlToText(html);
+	if (text.length === 0) return [];
+	return [{
+		id,
+		text,
+		metadata: {
+			source: id,
+			loader: "html",
+			...title !== void 0 ? { title } : {},
+			...options.metadata
+		},
+		tags: options.tags
+	}];
 }
 
 //#endregion
-//#region ../@warlock.js/ai/src/rag/store/cache-vector-store.ts
+//#region ../@warlock.js/ai/src/rag/loaders/load-web.ts
+/** Browser-ish UA so servers that gate on it still return prose. */
+const DEFAULT_USER_AGENT = "warlock-ai-rag-loader/1.0 (+https://github.com/warlock-js)";
 /**
-* Adapt any `@warlock.js/cache` `CacheDriver` to the {@link VectorStore}
-* narrowing the RAG pipeline depends on. The cache driver IS the vector
-* store — exactly as `SemanticMemory` and `semanticCache` already use it:
-*
-* - `upsert` → `driver.set(key, value, { vector, tags })`
-* - `query`  → `driver.similar<T>(vector, { topK, threshold, tags })`
-* - `removeNamespace` → `driver.removeNamespace(namespace)`
+* Whether a `content-type` header names an HTML document (so it is run
+* through the tag-strip pass) versus already-plain text (used verbatim).
+*/
+function isHtmlContentType(contentType) {
+	if (!contentType) return true;
+	const lower = contentType.toLowerCase();
+	return lower.includes("text/html") || lower.includes("application/xhtml");
+}
+/**
+* Fetch a URL through the SSRF-safe outbound policy and load it into a single
+* {@link RagDocument} of readable text. The fetch ALWAYS goes through
+* `guardedFetch` — never a raw `fetch` — so the scheme allowlist, host
+* allowlist, post-DNS private-IP guard, timeout, and response-size cap from
+* {@link LoadWebOptions.policy} (or the strict defaults) always apply.
 *
-* Drivers without similarity support throw `CacheUnsupportedError` from
-* `set({ vector })` / `similar()`; the error surfaces unchanged so the
-* caller sees the cache layer's own message (pointing at the `pg` /
-* `redis` drivers for production-scale similarity).
+* HTML responses are run through the same tag-strip pass as {@link loadHtml}
+* (scripts/styles dropped, entities decoded, paragraph structure kept);
+* non-HTML text responses (`text/plain`, markdown, …) are used verbatim.
+* The document's `metadata.source` is the resolved URL, `metadata.title` is
+* the page `<title>` (HTML only, unless overridden), `metadata.contentType`
+* is the server-reported type, and `metadata.loader` is `"web"`.
+*
+* The output is the exact shape `index()` consumes, so a load feeds straight
+* in:
 *
 * @example
-* const store = cacheVectorStore(new MemoryCacheDriver());
-* await store.upsert("ai.rag.docs.guide.0", { text: "…" }, vector);
-* const hits = await store.query(queryVector, { topK: 5, threshold: 0.5 });
-*/
-function cacheVectorStore(driver) {
-	return {
-		async upsert(key, value, vector, tags) {
-			await driver.set(key, value, tags && tags.length > 0 ? {
-				vector,
-				tags
-			} : { vector });
+* const kb = ai.rag({ embedder, store });
+* await kb.index(await loadWeb("https://example.com/guide"));
+*
+* @example
+* // Tighten the SSRF policy to a single host:
+* await kb.index(await loadWeb(url, {
+*   policy: { hostAllowlist: ["docs.example.com"], maxBytes: 2_000_000 },
+*   tags: ["docs"],
+* }));
+*
+* @param url - The absolute URL to fetch. Validated by the outbound policy.
+* @param options - `policy` (the {@link OutboundPolicy}) plus shared
+*   `id` / `metadata` / `tags` ({@link LoadWebOptions}).
+* @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.
+* @throws {OutboundPolicyError} when the policy blocks the URL, the request
+*   times out, the body exceeds the cap, or the response is not OK.
+*/
+async function loadWeb(url, options = {}) {
+	const policy = resolveOutboundPolicy(options.policy);
+	const response = await guardedFetch(url, policy, {
+		headers: {
+			"user-agent": DEFAULT_USER_AGENT,
+			accept: "text/html,text/*"
 		},
-		async query(vector, options) {
-			return (await driver.similar(vector, {
-				topK: options.topK,
-				threshold: options.threshold,
-				tags: options.tags
-			})).map((hit) => ({
-				key: hit.key,
-				value: hit.value,
-				score: hit.score
-			}));
+		redirect: "follow"
+	});
+	if (!response.ok) throw new OutboundPolicyError(`loadWeb: fetching "${url}" returned ${response.status} ${response.statusText}`, { context: {
+		url,
+		status: response.status
+	} });
+	const contentType = response.headers.get("content-type") ?? void 0;
+	const raw = await readTextCapped(response, policy.maxBytes);
+	const isHtml = isHtmlContentType(contentType);
+	const text = isHtml ? htmlToText(raw) : raw.trim();
+	const title = isHtml ? extractTitle(raw) : void 0;
+	const id = options.id ?? url;
+	if (text.length === 0) return [];
+	return [{
+		id,
+		text,
+		metadata: {
+			source: url,
+			loader: "web",
+			...title !== void 0 ? { title } : {},
+			...contentType !== void 0 ? { contentType } : {},
+			...options.metadata
 		},
-		async removeNamespace(namespace) {
-			await driver.removeNamespace(namespace);
-		}
-	};
+		tags: options.tags
+	}];
 }
 
 //#endregion
-//#region ../@warlock.js/ai/src/rag/rag.ts
-const DEFAULT_NAME = "rag";
-const DEFAULT_NAMESPACE_PREFIX = "ai.rag";
+//#region ../@warlock.js/ai/src/rag/loaders/errors.ts
+/**
+* Loader error surface. The only loader-specific failure is a missing
+* OPTIONAL peer (`pdf-parse`), which — like the moderation detector's
+* missing `openai` peer — is an *infrastructure* fault, not a content
+* problem, so {@link loadPdf} throws a plain `Error` carrying the curated
+* {@link PDF_PARSE_INSTALL_INSTRUCTIONS} rather than an `AIError`. Mirrors
+* the guard's `OPENAI_INSTALL_INSTRUCTIONS` / ai-panoptic's
+* `LANGFUSE_INSTALL_INSTRUCTIONS`.
+*/
 /**
-* Max chunk texts embedded per `embedder.embedMany()` call. One call is
-* one provider request, so a giant document is sub-batched to stay under
-* the provider's per-request token cap (the design's "chunk larger than
-* provider per-request cap" guard).
+* Curated install string thrown by {@link loadPdf} on first call when the
+* `pdf-parse` peer is absent. Surfaced instead of a raw
+* module-resolution stack trace.
 */
-const DEFAULT_MAX_BATCH = 96;
+const PDF_PARSE_INSTALL_INSTRUCTIONS = `
+The @warlock.js/ai PDF loader requires the optional "pdf-parse" peer.
+Install it with:
+
+  npm install pdf-parse
+`.trim();
+
+//#endregion
+//#region ../@warlock.js/ai/src/rag/loaders/load-pdf.ts
+/** Default `id` when the caller supplies none. */
+const DEFAULT_ID = "document";
+let pdfParse;
+let isModuleExists$1;
+let loadingPromise$1;
 /**
-* Create a RAG pipeline: **chunk → embed → vector store → retrieve →
-* rerank → cite**, reusing the app's `ai.embedder` for embedding, a
-* `@warlock.js/cache` `CacheDriver` as the vector store, and the
-* composite-as-tool engine to expose retrieval as a tool.
-*
-* Resolution is loud at construction (mirroring `memory()`):
-* - `embedder` is required — a provider with no embedder must be caught
-*   here, not at first index.
-* - `store` falls back to `ai.config({ defaultStore })`; if neither
-*   resolves, construction throws.
+* Settle the lazy import of `pdf-parse` once, concurrency-safe. A bare
+* `catch` flips the flag to `false`; the curated
+* {@link PDF_PARSE_INSTALL_INSTRUCTIONS} surfaces at first
+* {@link loadPdf} call, never a raw module-resolution stack trace. Mirrors
+* the guard moderation detector's `loadOpenAi`.
+*/
+function loadPdfParse() {
+	if (isModuleExists$1 !== void 0) return Promise.resolve();
+	if (loadingPromise$1) return loadingPromise$1;
+	loadingPromise$1 = (async () => {
+		try {
+			const mod = await import("pdf-parse");
+			pdfParse = mod.default ?? mod;
+			isModuleExists$1 = typeof pdfParse === "function";
+		} catch {
+			isModuleExists$1 = false;
+		}
+	})();
+	return loadingPromise$1;
+}
+/**
+* Coerce a {@link RagDocument}-compatible binary input into a `Buffer` for
+* `pdf-parse`. Accepts a Node `Buffer`, an `ArrayBuffer`, or a typed array
+* (`Uint8Array`) — the shapes a file read / fetch body hands back.
+*/
+function toBuffer(input) {
+	if (Buffer.isBuffer(input)) return input;
+	if (input instanceof ArrayBuffer) return Buffer.from(input);
+	return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+}
+/**
+* Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`
+* peer. The peer is resolved lazily on the FIRST call (not at import) so
+* importing `@warlock.js/ai` never forces it to be installed; when it is
+* absent the curated {@link PDF_PARSE_INSTALL_INSTRUCTIONS} is thrown as a
+* plain `Error` (a missing optional peer is an infrastructure fault, not a
+* content problem).
 *
-* `retrieve()` is return-only — it never auto-injects into a prompt; the
-* caller formats the cited chunks (or uses `asTool()` for the agent loop).
-* The reranker is OFF by default (cosine-only) unless `config.reranker`
-* is set.
+* By default the whole PDF becomes a single document carrying
+* `metadata.pageCount`. With `perPage: true`, each page becomes its own
+* document (`id` suffixed `#p<n>`, `metadata.page` set) so citations stay
+* page-precise. Document `metadata.title` comes from the PDF info
+* dictionary's `Title` (unless overridden), and `metadata.loader` is
+* `"pdf"`. The output is the exact shape `index()` consumes.
 *
 * @example
-* import { ai } from "@warlock.js/ai";
-* import { MemoryCacheDriver } from "@warlock.js/cache";
+* import { readFile } from "node:fs/promises";
+* const kb = ai.rag({ embedder, store });
+* await kb.index(await loadPdf(await readFile("guide.pdf"), { id: "guide" }));
 *
-* const kb = ai.rag({
-*   name: "docs",
-*   embedder: openai.embedder({ name: "text-embedding-3-small" }),
-*   store: new MemoryCacheDriver(),
-*   chunk: { type: "markdown", size: 800, overlap: 120 },
-* });
+* @example
+* // One document per page for page-precise citations:
+* await kb.index(await loadPdf(bytes, { id: "manual", perPage: true }));
+*
+* @param input - The PDF bytes (`Buffer`, `ArrayBuffer`, or `Uint8Array`).
+* @param options - `perPage` plus shared `id` / `metadata` / `tags`
+*   ({@link LoadPdfOptions}).
+* @returns A {@link RagLoaderResult} ready for `rag.index()`.
+* @throws {Error} carrying {@link PDF_PARSE_INSTALL_INSTRUCTIONS} when the
+*   `pdf-parse` peer is not installed.
+*/
+async function loadPdf(input, options = {}) {
+	await loadPdfParse();
+	if (!isModuleExists$1 || !pdfParse) throw new Error(PDF_PARSE_INSTALL_INSTRUCTIONS);
+	const id = options.id ?? DEFAULT_ID;
+	if (options.perPage ?? false) return loadPerPage(input, id, options);
+	const parsed = await pdfParse(toBuffer(input));
+	const text = parsed.text.trim();
+	const title = parsed.info?.Title?.trim();
+	if (text.length === 0) return [];
+	return [{
+		id,
+		text,
+		metadata: {
+			source: id,
+			loader: "pdf",
+			pageCount: parsed.numpages,
+			...title ? { title } : {},
+			...options.metadata
+		},
+		tags: options.tags
+	}];
+}
+/**
+* Per-page variant: render each page separately via `pdf-parse`'s
+* `pagerender` hook, accumulating one document per non-empty page. Each
+* carries `metadata.page` (1-based) and `metadata.pageCount`, and its id is
+* the base id suffixed `#p<n>` so every page-document is distinctly
+* identified for citation.
 *
-* await kb.index([{ id: "guide", text: longMarkdown, metadata: { url: "/guide" } }]);
-* const { chunks } = await kb.retrieve("how do I configure caching?", { topK: 4 });
+* `pdf-parse` calls `pagerender` once per page in document order and
+* `await`s the returned string, so capturing each page's joined text content
+* here gives reliable page boundaries the concatenated `text` lacks.
 */
-function rag(config) {
-	const name = config.name ?? DEFAULT_NAME;
-	if (!config.embedder) throw new Error(`rag("${name}"): an \`embedder\` is required — pass one from a provider that supports embeddings (e.g. openai.embedder({ name: "text-embedding-3-small" }))`);
-	const driver = config.store ?? resolveDefaultStore();
-	if (!driver) throw new Error(`rag("${name}"): no store — pass \`store\` (a vector-capable @warlock.js/cache CacheDriver) or call \`ai.config({ defaultStore })\` at app boot before constructing the rag`);
-	const store = cacheVectorStore(driver);
-	const namespace = config.namespace ?? `${DEFAULT_NAMESPACE_PREFIX}.${name}`;
-	const embedder = config.embedder;
-	let indexedDimensions;
-	const instance = {
-		name,
-		async index(docs, chunkOverride) {
-			const chunkOptions = chunkOverride ?? config.chunk;
-			const limits = config.limits;
-			if (limits?.maxDocuments !== void 0 && docs.length > limits.maxDocuments) throw new Error(`rag("${name}"): index() received ${docs.length} documents, exceeding the configured maxDocuments of ${limits.maxDocuments}`);
-			if (limits?.maxBytes !== void 0) {
-				const totalBytes = docs.reduce((sum, doc) => sum + Buffer.byteLength(doc.text ?? ""), 0);
-				if (totalBytes > limits.maxBytes) throw new Error(`rag("${name}"): index() received ${totalBytes} bytes of document text, exceeding the configured maxBytes of ${limits.maxBytes}`);
-			}
-			const records = [];
-			for (const doc of docs) {
-				const pieces = chunk(doc.text, chunkOptions);
-				for (const piece of pieces) {
-					const value = {
-						sourceId: doc.id,
-						chunkIndex: piece.index,
-						span: piece.span,
-						text: piece.text,
-						metadata: doc.metadata
-					};
-					records.push({
-						key: keyFor(namespace, doc.id, piece.index),
-						value,
-						text: piece.text,
-						tags: doc.tags
-					});
-				}
-			}
-			if (records.length === 0) return { chunks: 0 };
-			if (limits?.maxChunks !== void 0 && records.length > limits.maxChunks) throw new Error(`rag("${name}"): index() produced ${records.length} chunks, exceeding the configured maxChunks of ${limits.maxChunks}`);
-			for (let offset = 0; offset < records.length; offset += DEFAULT_MAX_BATCH) {
-				const batch = records.slice(offset, offset + DEFAULT_MAX_BATCH);
-				const { vectors, dimensions } = await embedder.embedMany(batch.map((record) => record.text));
-				if (indexedDimensions === void 0 && dimensions !== 0) indexedDimensions = dimensions;
-				await Promise.all(batch.map((record, position) => store.upsert(record.key, record.value, vectors[position], record.tags)));
-			}
-			return { chunks: records.length };
-		},
-		async retrieve(query, options) {
-			return retrieve(query, {
-				embedder,
-				store,
-				namespace,
-				reranker: config.reranker,
-				defaults: config.retrieve,
-				indexedDimensions
-			}, options);
-		},
-		async clear() {
-			await store.removeNamespace(namespace);
-		},
-		asTool(options) {
-			return ragAsTool(name, (query, retrieveOptions) => instance.retrieve(query, retrieveOptions), options);
-		}
-	};
-	return instance;
+async function loadPerPage(input, id, options) {
+	const pages = [];
+	const parsed = await pdfParse(toBuffer(input), { pagerender: async (page) => {
+		const rendered = await renderPage(page);
+		pages.push(rendered);
+		return rendered;
+	} });
+	const title = parsed.info?.Title?.trim();
+	const docs = [];
+	pages.forEach((pageText, index) => {
+		const text = pageText.trim();
+		if (text.length === 0) return;
+		const pageNumber = index + 1;
+		docs.push({
+			id: `${id}#p${pageNumber}`,
+			text,
+			metadata: {
+				source: id,
+				loader: "pdf",
+				page: pageNumber,
+				pageCount: parsed.numpages,
+				...title ? { title } : {},
+				...options.metadata
+			},
+			tags: options.tags
+		});
+	});
+	return docs;
 }
 /**
-* Namespaced key for a stored chunk. Uses the `.` separator (matching
-* `SemanticMemory.keyFor`) so namespace-prefix filtering on the returned
-* `hit.key` stays aligned with the cache's `parseKey` normalization.
+* Join a single page's text-layer items in reading order, inserting a space
+* between items so adjacent words do not run together. Mirrors the essence
+* of `pdf-parse`'s default renderer without depending on its internals, so
+* the per-page hook stays stable across `pdf-parse` versions. A page with no
+* text layer (scanned image) renders to an empty string and is dropped.
 */
-function keyFor(namespace, sourceId, chunkIndex) {
-	return `${namespace}.${sourceId}.${chunkIndex}`;
+async function renderPage(page) {
+	if (typeof page?.getTextContent !== "function") return "";
+	return (await page.getTextContent({
+		normalizeWhitespace: true,
+		disableCombineTextItems: false
+	})).items.map((item) => item.str).join(" ").replace(/\s+/g, " ").trim();
 }
 
 //#endregion
@@ -21608,7 +23574,19 @@ const ai = {
 	planner,
 	rag: Object.assign(rag, {
 		keywordReranker,
-		llmReranker
+		llmReranker,
+		chunk,
+		cacheVectorStore,
+		pgVectorStore,
+		vectorLiteral,
+		loadText,
+		loadHtml,
+		loadWeb,
+		loadPdf,
+		bm25Rank,
+		reciprocalRankFusion,
+		hybridRank,
+		multiQuery
 	}),
 	spawnSubAgent,
 	router,
@@ -21616,6 +23594,12 @@ const ai = {
 	batch,
 	streamObject,
 	serve,
+	image,
+	speech,
+	transcribe,
+	audioFromFile,
+	audioFromBuffer,
+	audioMediaTypeForFilename,
 	fallbackModel,
 	eval: evalScorers,
 	dataset,
@@ -21680,6 +23664,12 @@ Object.defineProperty(exports, 'AgentCancelledError', {
     return AgentCancelledError;
   }
 });
+Object.defineProperty(exports, 'AgentDriftError', {
+  enumerable: true,
+  get: function () {
+    return AgentDriftError;
+  }
+});
 Object.defineProperty(exports, 'AgentExecutionError', {
   enumerable: true,
   get: function () {
@@ -21770,6 +23760,12 @@ Object.defineProperty(exports, 'MaxStepsExceededError', {
     return MaxStepsExceededError;
   }
 });
+Object.defineProperty(exports, 'MockImageModel', {
+  enumerable: true,
+  get: function () {
+    return MockImageModel;
+  }
+});
 Object.defineProperty(exports, 'MockModel', {
   enumerable: true,
   get: function () {
@@ -21788,6 +23784,18 @@ Object.defineProperty(exports, 'MockSkillsStore', {
     return MockSkillsStore;
   }
 });
+Object.defineProperty(exports, 'MockSpeechModel', {
+  enumerable: true,
+  get: function () {
+    return MockSpeechModel;
+  }
+});
+Object.defineProperty(exports, 'MockTranscriptionModel', {
+  enumerable: true,
+  get: function () {
+    return MockTranscriptionModel;
+  }
+});
 Object.defineProperty(exports, 'OPENAI_INSTALL_INSTRUCTIONS', {
   enumerable: true,
   get: function () {
@@ -21836,6 +23844,12 @@ Object.defineProperty(exports, 'OutboundPolicyError', {
     return OutboundPolicyError;
   }
 });
+Object.defineProperty(exports, 'PDF_PARSE_INSTALL_INSTRUCTIONS', {
+  enumerable: true,
+  get: function () {
+    return PDF_PARSE_INSTALL_INSTRUCTIONS;
+  }
+});
 Object.defineProperty(exports, 'Persona', {
   enumerable: true,
   get: function () {
@@ -21848,6 +23862,12 @@ Object.defineProperty(exports, 'PlannerCancelledError', {
     return PlannerCancelledError;
   }
 });
+Object.defineProperty(exports, 'PlannerDriftError', {
+  enumerable: true,
+  get: function () {
+    return PlannerDriftError;
+  }
+});
 Object.defineProperty(exports, 'PlannerFailedError', {
   enumerable: true,
   get: function () {
@@ -22052,6 +24072,24 @@ Object.defineProperty(exports, 'assertUrlAllowed', {
     return assertUrlAllowed;
   }
 });
+Object.defineProperty(exports, 'audioFromBuffer', {
+  enumerable: true,
+  get: function () {
+    return audioFromBuffer;
+  }
+});
+Object.defineProperty(exports, 'audioFromFile', {
+  enumerable: true,
+  get: function () {
+    return audioFromFile;
+  }
+});
+Object.defineProperty(exports, 'audioMediaTypeForFilename', {
+  enumerable: true,
+  get: function () {
+    return audioMediaTypeForFilename;
+  }
+});
 Object.defineProperty(exports, 'batch', {
   enumerable: true,
   get: function () {
@@ -22124,6 +24162,12 @@ Object.defineProperty(exports, 'computeCost', {
     return computeCost;
   }
 });
+Object.defineProperty(exports, 'computeImageCost', {
+  enumerable: true,
+  get: function () {
+    return computeImageCost;
+  }
+});
 Object.defineProperty(exports, 'computeOrchestratorSignature', {
   enumerable: true,
   get: function () {
@@ -22352,6 +24396,12 @@ Object.defineProperty(exports, 'hybridRank', {
     return hybridRank;
   }
 });
+Object.defineProperty(exports, 'image', {
+  enumerable: true,
+  get: function () {
+    return image;
+  }
+});
 Object.defineProperty(exports, 'inProcessSessionLock', {
   enumerable: true,
   get: function () {
@@ -22412,6 +24462,18 @@ Object.defineProperty(exports, 'llmReranker', {
     return llmReranker;
   }
 });
+Object.defineProperty(exports, 'loadHtml', {
+  enumerable: true,
+  get: function () {
+    return loadHtml;
+  }
+});
+Object.defineProperty(exports, 'loadPdf', {
+  enumerable: true,
+  get: function () {
+    return loadPdf;
+  }
+});
 Object.defineProperty(exports, 'loadRecord', {
   enumerable: true,
   get: function () {
@@ -22430,6 +24492,18 @@ Object.defineProperty(exports, 'loadSnapshotForResume', {
     return loadSnapshotForResume$1;
   }
 });
+Object.defineProperty(exports, 'loadText', {
+  enumerable: true,
+  get: function () {
+    return loadText;
+  }
+});
+Object.defineProperty(exports, 'loadWeb', {
+  enumerable: true,
+  get: function () {
+    return loadWeb;
+  }
+});
 Object.defineProperty(exports, 'memory', {
   enumerable: true,
   get: function () {
@@ -22574,6 +24648,12 @@ Object.defineProperty(exports, 'pg$2', {
     return pg$2;
   }
 });
+Object.defineProperty(exports, 'pgVectorStore', {
+  enumerable: true,
+  get: function () {
+    return pgVectorStore;
+  }
+});
 Object.defineProperty(exports, 'pii', {
   enumerable: true,
   get: function () {
@@ -22880,6 +24960,12 @@ Object.defineProperty(exports, 'spawnSubAgent', {
     return spawnSubAgent;
   }
 });
+Object.defineProperty(exports, 'speech', {
+  enumerable: true,
+  get: function () {
+    return speech;
+  }
+});
 Object.defineProperty(exports, 'stampReportLineage', {
   enumerable: true,
   get: function () {
@@ -22958,6 +25044,12 @@ Object.defineProperty(exports, 'topic', {
     return topic;
   }
 });
+Object.defineProperty(exports, 'transcribe', {
+  enumerable: true,
+  get: function () {
+    return transcribe;
+  }
+});
 Object.defineProperty(exports, 'urlSource', {
   enumerable: true,
   get: function () {
@@ -22970,6 +25062,12 @@ Object.defineProperty(exports, 'vcr', {
     return vcr;
   }
 });
+Object.defineProperty(exports, 'vectorLiteral', {
+  enumerable: true,
+  get: function () {
+    return vectorLiteral;
+  }
+});
 Object.defineProperty(exports, 'withRunFrame', {
   enumerable: true,
   get: function () {
@@ -22988,4 +25086,4 @@ Object.defineProperty(exports, 'workflow', {
     return workflow;
   }
 });
-//# sourceMappingURL=src-C02yzsLs.cjs.map
+//# sourceMappingURL=src-OZyDYHxm.cjs.map