@warlock.js/core 4.4.0 → 4.6.0

package/esm/ai/src/human/register.mjs

@@ -0,0 +1,37 @@
+import { humanApproval } from "./human-approval.mjs";
+import { resume } from "./resume.mjs";
+import { memory } from "./stores/memory.mjs";
+import { pg } from "./stores/pg.mjs";
+import { redis } from "./stores/redis.mjs";
+import "./stores/index.mjs";
+
+//#region ../@warlock.js/ai/src/human/register.ts
+/**
+* The assembled `ai.human.*` namespace — the human-in-the-loop surface
+* mounted onto the shared `ai` object in `../ai`.
+*
+* - `approval(options)` — the `tool.before` approval-gate middleware.
+* - `resume(id, decision, options)` — out-of-process durable resume.
+* - `interrupt.{memory,pg,redis}()` — the
+*   {@link import("./contracts").InterruptStore} factories (memory ships
+*   real; pg/redis lazily import their optional-peer driver).
+*
+* Declared as a standalone object so `../ai` can spread it onto the `ai`
+* literal and pin the `Ai.human` member to this exact shape with no casts.
+* Lives here (not inlined into `../ai`) to keep the human factories grouped
+* with the rest of the human module and avoid `../ai` reaching into each
+* store/middleware file directly.
+*/
+const human = {
+	approval: humanApproval,
+	resume,
+	interrupt: {
+		memory,
+		pg,
+		redis
+	}
+};
+
+//#endregion
+export { human };
+//# sourceMappingURL=register.mjs.map

package/esm/ai/src/human/register.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.mjs","names":["interruptMemory","interruptPg","interruptRedis"],"sources":["../../../../../../../../../@warlock.js/ai/src/human/register.ts"],"sourcesContent":["import { humanApproval } from \"./human-approval\";\nimport { resume } from \"./resume\";\nimport { interruptMemory, interruptPg, interruptRedis } from \"./stores\";\n\n/**\n * The assembled `ai.human.*` namespace — the human-in-the-loop surface\n * mounted onto the shared `ai` object in `../ai`.\n *\n * - `approval(options)` — the `tool.before` approval-gate middleware.\n * - `resume(id, decision, options)` — out-of-process durable resume.\n * - `interrupt.{memory,pg,redis}()` — the\n *   {@link import(\"./contracts\").InterruptStore} factories (memory ships\n *   real; pg/redis lazily import their optional-peer driver).\n *\n * Declared as a standalone object so `../ai` can spread it onto the `ai`\n * literal and pin the `Ai.human` member to this exact shape with no casts.\n * Lives here (not inlined into `../ai`) to keep the human factories grouped\n * with the rest of the human module and avoid `../ai` reaching into each\n * store/middleware file directly.\n */\nexport const human = {\n  approval: humanApproval,\n  resume,\n  interrupt: {\n    memory: interruptMemory,\n    pg: interruptPg,\n    redis: interruptRedis,\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,QAAQ;CACnB,UAAU;CACV;CACA,WAAW;EACDA;EACJC;EACGC;CACT;AACF"}

package/esm/ai/src/human/resume-seed.mjs

@@ -0,0 +1,53 @@
+//#region ../@warlock.js/ai/src/human/resume-seed.ts
+/**
+* Process-local registry of decisions pre-seeded for a durable re-run.
+*
+* **Why it exists.** v1 durable resume re-runs the *same* agent turn with
+* the human's decision already in hand (it does **not** rehydrate an
+* in-flight supervisor — that is the deferred v2 lift). The agent's
+* `ai.human.approval(...)` middleware is baked in at construction, so the
+* re-run cannot be handed a different handler. Instead, `ai.human.resume(...)`
+* stashes the decision here keyed by the agent name; the approval
+* middleware's handler consults the registry **before** calling the
+* author's handler and, on a hit, replays the seeded decision exactly once
+* — so the gated tool call this time resolves to the human's ruling instead
+* of pausing again.
+*
+* Keyed by agent name (not interrupt id): the re-run produces a *fresh*
+* interrupt id (the id embeds a random segment), so the seed must be
+* matched to the run, not the prior id. The registry holds at most one
+* seeded decision per agent and consumes it on first read, so a second
+* gated call in the same re-run falls through to the author's handler.
+*/
+const seededDecisions = /* @__PURE__ */ new Map();
+/**
+* Stash a decision to be replayed on the next gated tool call of `agentName`.
+* Overwrites any prior seed for the same agent (a re-run carries exactly one
+* pre-seeded decision).
+*/
+function seedDecision(agentName, decision) {
+	seededDecisions.set(agentName, decision);
+}
+/**
+* Take (read **and** remove) the seeded decision for `agentName`, or
+* `undefined` when none is staged. Consuming on read makes the seed
+* one-shot: only the first gated call of a re-run replays it.
+*/
+function takeSeededDecision(agentName) {
+	const decision = seededDecisions.get(agentName);
+	if (decision === void 0) return;
+	seededDecisions.delete(agentName);
+	return decision;
+}
+/**
+* Drop any staged seed for `agentName` without consuming it as a decision.
+* Used to clean up after a re-run that errored before the seeded call fired,
+* so a stale seed never leaks into an unrelated later run of the same agent.
+*/
+function clearSeededDecision(agentName) {
+	seededDecisions.delete(agentName);
+}
+
+//#endregion
+export { clearSeededDecision, seedDecision, takeSeededDecision };
+//# sourceMappingURL=resume-seed.mjs.map

package/esm/ai/src/human/resume-seed.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-seed.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/human/resume-seed.ts"],"sourcesContent":["import type { ApprovalDecision } from \"./contracts\";\n\n/**\n * Process-local registry of decisions pre-seeded for a durable re-run.\n *\n * **Why it exists.** v1 durable resume re-runs the *same* agent turn with\n * the human's decision already in hand (it does **not** rehydrate an\n * in-flight supervisor — that is the deferred v2 lift). The agent's\n * `ai.human.approval(...)` middleware is baked in at construction, so the\n * re-run cannot be handed a different handler. Instead, `ai.human.resume(...)`\n * stashes the decision here keyed by the agent name; the approval\n * middleware's handler consults the registry **before** calling the\n * author's handler and, on a hit, replays the seeded decision exactly once\n * — so the gated tool call this time resolves to the human's ruling instead\n * of pausing again.\n *\n * Keyed by agent name (not interrupt id): the re-run produces a *fresh*\n * interrupt id (the id embeds a random segment), so the seed must be\n * matched to the run, not the prior id. The registry holds at most one\n * seeded decision per agent and consumes it on first read, so a second\n * gated call in the same re-run falls through to the author's handler.\n */\nconst seededDecisions = new Map<string, ApprovalDecision>();\n\n/**\n * Stash a decision to be replayed on the next gated tool call of `agentName`.\n * Overwrites any prior seed for the same agent (a re-run carries exactly one\n * pre-seeded decision).\n */\nexport function seedDecision(agentName: string, decision: ApprovalDecision): void {\n  seededDecisions.set(agentName, decision);\n}\n\n/**\n * Take (read **and** remove) the seeded decision for `agentName`, or\n * `undefined` when none is staged. Consuming on read makes the seed\n * one-shot: only the first gated call of a re-run replays it.\n */\nexport function takeSeededDecision(agentName: string): ApprovalDecision | undefined {\n  const decision = seededDecisions.get(agentName);\n\n  if (decision === undefined) {\n    return undefined;\n  }\n\n  seededDecisions.delete(agentName);\n\n  return decision;\n}\n\n/**\n * Drop any staged seed for `agentName` without consuming it as a decision.\n * Used to clean up after a re-run that errored before the seeded call fired,\n * so a stale seed never leaks into an unrelated later run of the same agent.\n */\nexport function clearSeededDecision(agentName: string): void {\n  seededDecisions.delete(agentName);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsBA,MAAM,kCAAkB,IAAI,IAA8B;;;;;;AAO1D,SAAgB,aAAa,WAAmB,UAAkC;CAChF,gBAAgB,IAAI,WAAW,QAAQ;AACzC;;;;;;AAOA,SAAgB,mBAAmB,WAAiD;CAClF,MAAM,WAAW,gBAAgB,IAAI,SAAS;CAE9C,IAAI,aAAa,QACf;CAGF,gBAAgB,OAAO,SAAS;CAEhC,OAAO;AACT;;;;;;AAOA,SAAgB,oBAAoB,WAAyB;CAC3D,gBAAgB,OAAO,SAAS;AAClC"}

package/esm/ai/src/human/resume.mjs

@@ -0,0 +1,121 @@
+import { clearSeededDecision, seedDecision } from "./resume-seed.mjs";
+
+//#region ../@warlock.js/ai/src/human/resume.ts
+/**
+* Validate that a decision is a well-formed {@link ApprovalDecision}.
+*
+* `ai.human.resume(...)` is a public, out-of-process entry point — a
+* webhook can hand it anything. Guard the closed `type` union (and the
+* per-variant required fields) before applying it, so a malformed payload
+* fails loudly here rather than silently mis-driving the re-run.
+*/
+function assertDecision(decision) {
+	if (decision.type === "approve") return;
+	if (decision.type === "reject") {
+		if (typeof decision.reason !== "string") throw new TypeError("ai.human.resume: a 'reject' decision requires a string 'reason'.");
+		return;
+	}
+	if (decision.type === "edit") {
+		if (!("args" in decision)) throw new TypeError("ai.human.resume: an 'edit' decision requires replacement 'args'.");
+		return;
+	}
+	throw new TypeError(`ai.human.resume: unknown decision type '${decision.type}'. Expected one of: approve, reject, edit.`);
+}
+/**
+* Re-run the agent for a resumed interrupt with the decision pre-seeded.
+*
+* Stages the decision in the process-local seed registry (keyed by agent
+* name), then re-executes the original prompt. The agent's
+* `ai.human.approval(...)` middleware consumes the seed on the gated tool
+* call — so this time it resolves to the human's ruling instead of pausing
+* again. The seed is cleared in a `finally` so a re-run that errors before
+* the gated call never leaks a stale seed into a later run.
+*/
+async function rerun(pending, decision, options) {
+	const { agent } = options;
+	if (!agent) return {
+		type: "applied",
+		interruptId: pending.interruptId,
+		decision
+	};
+	const input = options.input ?? pending.request.context.originalInput ?? "";
+	seedDecision(agent.name, decision);
+	try {
+		const result = await agent.execute(input, options.executeOptions);
+		return {
+			type: "applied",
+			interruptId: pending.interruptId,
+			decision,
+			result
+		};
+	} finally {
+		clearSeededDecision(agent.name);
+	}
+}
+/**
+* Apply a human's decision to a persisted interrupt — the out-of-process
+* resume entry point behind `ai.human.resume(interruptId, decision, options)`.
+*
+* **Durable v1 model — re-run, not mid-supervisor suspend.** This loads the
+* {@link PendingInterrupt} from `options.store`, validates the decision,
+* deletes the pending record, and (when an `agent` is supplied) re-executes
+* the original turn with the decision **pre-seeded**, so the gated tool call
+* resolves to the ruling instead of pausing again. It does **not** rehydrate
+* an in-flight supervisor — that is the deferred v2 lift.
+*
+* **Idempotent.** A second resume of an already-resolved (deleted) or
+* never-raised interrupt is a no-op: it returns `{ type: "already-resolved" }`
+* without re-applying the decision or re-running the turn — mirroring the
+* orchestrator resume's drain idempotency. The record is deleted **before**
+* the re-run, so even a re-run that itself raises a fresh interrupt cannot
+* collide with the one being resolved.
+*
+* **Two shapes** (see {@link ResumeOptions}):
+* - **apply-only** — omit `agent`: load, validate, delete, return
+*   `{ type: "applied", decision }` for a caller-owned re-drive.
+* - **re-run** — pass `agent`: additionally re-execute the turn; the
+*   {@link import("@warlock.js/ai").AgentResult} rides `result.result`.
+*
+* @param interruptId - Id of the persisted interrupt to resolve.
+* @param decision - The human's ruling (approve / reject / edit).
+* @param options - The durable `store` (required) plus optional re-run
+*   `agent` / `input` / `executeOptions`.
+* @returns A {@link ResumeResult} — `"applied"` or idempotent
+*   `"already-resolved"`.
+*
+* @example
+* // Process B (webhook, hours later) — apply-only:
+* const outcome = await ai.human.resume(interruptId, { type: "reject", reason: "Out of policy" }, {
+*   store,
+* });
+*
+* @example
+* // Re-run the turn with the decision pre-seeded:
+* const outcome = await ai.human.resume(interruptId, { type: "edit", args: { amount: 5 } }, {
+*   store,
+*   agent: support,
+* });
+* if (outcome.type === "applied" && outcome.result) {
+*   console.log(outcome.result.text);
+* }
+*/
+async function resume(interruptId, decision, options) {
+	assertDecision(decision);
+	const { store } = options;
+	const pending = await store.load(interruptId);
+	if (pending === void 0 || pending.status !== "pending") return {
+		type: "already-resolved",
+		interruptId
+	};
+	await store.delete(interruptId);
+	if (!options.agent) return {
+		type: "applied",
+		interruptId,
+		decision
+	};
+	return rerun(pending, decision, options);
+}
+
+//#endregion
+export { resume };
+//# sourceMappingURL=resume.mjs.map

package/esm/ai/src/human/resume.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/human/resume.ts"],"sourcesContent":["import type {\n  ApprovalDecision,\n  PendingInterrupt,\n  ResumeOptions,\n  ResumeResult,\n} from \"./contracts\";\nimport { clearSeededDecision, seedDecision } from \"./resume-seed\";\n\n/**\n * Validate that a decision is a well-formed {@link ApprovalDecision}.\n *\n * `ai.human.resume(...)` is a public, out-of-process entry point — a\n * webhook can hand it anything. Guard the closed `type` union (and the\n * per-variant required fields) before applying it, so a malformed payload\n * fails loudly here rather than silently mis-driving the re-run.\n */\nfunction assertDecision(decision: ApprovalDecision): void {\n  if (decision.type === \"approve\") {\n    return;\n  }\n\n  if (decision.type === \"reject\") {\n    if (typeof decision.reason !== \"string\") {\n      throw new TypeError(\n        \"ai.human.resume: a 'reject' decision requires a string 'reason'.\",\n      );\n    }\n\n    return;\n  }\n\n  if (decision.type === \"edit\") {\n    if (!(\"args\" in decision)) {\n      throw new TypeError(\n        \"ai.human.resume: an 'edit' decision requires replacement 'args'.\",\n      );\n    }\n\n    return;\n  }\n\n  throw new TypeError(\n    `ai.human.resume: unknown decision type '${(decision as { type: string }).type}'. Expected one of: approve, reject, edit.`,\n  );\n}\n\n/**\n * Re-run the agent for a resumed interrupt with the decision pre-seeded.\n *\n * Stages the decision in the process-local seed registry (keyed by agent\n * name), then re-executes the original prompt. The agent's\n * `ai.human.approval(...)` middleware consumes the seed on the gated tool\n * call — so this time it resolves to the human's ruling instead of pausing\n * again. The seed is cleared in a `finally` so a re-run that errors before\n * the gated call never leaks a stale seed into a later run.\n */\nasync function rerun<TOutput>(\n  pending: PendingInterrupt,\n  decision: ApprovalDecision,\n  options: ResumeOptions<TOutput>,\n): Promise<ResumeResult<TOutput>> {\n  const { agent } = options;\n\n  // `agent` is guaranteed by the caller (this is only reached on the\n  // re-run path), but narrow for the type system.\n  if (!agent) {\n    return { type: \"applied\", interruptId: pending.interruptId, decision };\n  }\n\n  const input = options.input ?? pending.request.context.originalInput ?? \"\";\n\n  seedDecision(agent.name, decision);\n\n  try {\n    const result = await agent.execute(input, options.executeOptions);\n\n    return {\n      type: \"applied\",\n      interruptId: pending.interruptId,\n      decision,\n      result,\n    };\n  } finally {\n    // If the seeded call never fired (the re-run errored early, or the\n    // policy no longer gates the tool), drop the stale seed so it cannot\n    // leak into an unrelated later run of the same agent.\n    clearSeededDecision(agent.name);\n  }\n}\n\n/**\n * Apply a human's decision to a persisted interrupt — the out-of-process\n * resume entry point behind `ai.human.resume(interruptId, decision, options)`.\n *\n * **Durable v1 model — re-run, not mid-supervisor suspend.** This loads the\n * {@link PendingInterrupt} from `options.store`, validates the decision,\n * deletes the pending record, and (when an `agent` is supplied) re-executes\n * the original turn with the decision **pre-seeded**, so the gated tool call\n * resolves to the ruling instead of pausing again. It does **not** rehydrate\n * an in-flight supervisor — that is the deferred v2 lift.\n *\n * **Idempotent.** A second resume of an already-resolved (deleted) or\n * never-raised interrupt is a no-op: it returns `{ type: \"already-resolved\" }`\n * without re-applying the decision or re-running the turn — mirroring the\n * orchestrator resume's drain idempotency. The record is deleted **before**\n * the re-run, so even a re-run that itself raises a fresh interrupt cannot\n * collide with the one being resolved.\n *\n * **Two shapes** (see {@link ResumeOptions}):\n * - **apply-only** — omit `agent`: load, validate, delete, return\n *   `{ type: \"applied\", decision }` for a caller-owned re-drive.\n * - **re-run** — pass `agent`: additionally re-execute the turn; the\n *   {@link import(\"@warlock.js/ai\").AgentResult} rides `result.result`.\n *\n * @param interruptId - Id of the persisted interrupt to resolve.\n * @param decision - The human's ruling (approve / reject / edit).\n * @param options - The durable `store` (required) plus optional re-run\n *   `agent` / `input` / `executeOptions`.\n * @returns A {@link ResumeResult} — `\"applied\"` or idempotent\n *   `\"already-resolved\"`.\n *\n * @example\n * // Process B (webhook, hours later) — apply-only:\n * const outcome = await ai.human.resume(interruptId, { type: \"reject\", reason: \"Out of policy\" }, {\n *   store,\n * });\n *\n * @example\n * // Re-run the turn with the decision pre-seeded:\n * const outcome = await ai.human.resume(interruptId, { type: \"edit\", args: { amount: 5 } }, {\n *   store,\n *   agent: support,\n * });\n * if (outcome.type === \"applied\" && outcome.result) {\n *   console.log(outcome.result.text);\n * }\n */\nexport async function resume<TOutput = unknown>(\n  interruptId: string,\n  decision: ApprovalDecision,\n  options: ResumeOptions<TOutput>,\n): Promise<ResumeResult<TOutput>> {\n  assertDecision(decision);\n\n  const { store } = options;\n  const pending = await store.load(interruptId);\n\n  // No live interrupt — already resolved + deleted, or never raised. Never\n  // double-apply; never re-run. Idempotent no-op.\n  if (pending === undefined || pending.status !== \"pending\") {\n    return { type: \"already-resolved\", interruptId };\n  }\n\n  // Resolve + delete BEFORE the re-run so a re-run that itself raises a new\n  // interrupt cannot collide with the one being resolved, and a concurrent\n  // resume of the same id sees it gone.\n  await store.delete(interruptId);\n\n  if (!options.agent) {\n    return { type: \"applied\", interruptId, decision };\n  }\n\n  return rerun(pending, decision, options);\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAS,eAAe,UAAkC;CACxD,IAAI,SAAS,SAAS,WACpB;CAGF,IAAI,SAAS,SAAS,UAAU;EAC9B,IAAI,OAAO,SAAS,WAAW,UAC7B,MAAM,IAAI,UACR,kEACF;EAGF;CACF;CAEA,IAAI,SAAS,SAAS,QAAQ;EAC5B,IAAI,EAAE,UAAU,WACd,MAAM,IAAI,UACR,kEACF;EAGF;CACF;CAEA,MAAM,IAAI,UACR,2CAA4C,SAA8B,KAAK,2CACjF;AACF;;;;;;;;;;;AAYA,eAAe,MACb,SACA,UACA,SACgC;CAChC,MAAM,EAAE,UAAU;CAIlB,IAAI,CAAC,OACH,OAAO;EAAE,MAAM;EAAW,aAAa,QAAQ;EAAa;CAAS;CAGvE,MAAM,QAAQ,QAAQ,SAAS,QAAQ,QAAQ,QAAQ,iBAAiB;CAExE,aAAa,MAAM,MAAM,QAAQ;CAEjC,IAAI;EACF,MAAM,SAAS,MAAM,MAAM,QAAQ,OAAO,QAAQ,cAAc;EAEhE,OAAO;GACL,MAAM;GACN,aAAa,QAAQ;GACrB;GACA;EACF;CACF,UAAU;EAIR,oBAAoB,MAAM,IAAI;CAChC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,eAAsB,OACpB,aACA,UACA,SACgC;CAChC,eAAe,QAAQ;CAEvB,MAAM,EAAE,UAAU;CAClB,MAAM,UAAU,MAAM,MAAM,KAAK,WAAW;CAI5C,IAAI,YAAY,UAAa,QAAQ,WAAW,WAC9C,OAAO;EAAE,MAAM;EAAoB;CAAY;CAMjD,MAAM,MAAM,OAAO,WAAW;CAE9B,IAAI,CAAC,QAAQ,OACX,OAAO;EAAE,MAAM;EAAW;EAAa;CAAS;CAGlD,OAAO,MAAM,SAAS,UAAU,OAAO;AACzC"}

package/esm/ai/src/human/stores/index.mjs

@@ -0,0 +1,5 @@
+import { memory } from "./memory.mjs";
+import { pg } from "./pg.mjs";
+import { redis } from "./redis.mjs";
+
+export {  };

package/esm/ai/src/human/stores/memory.mjs

@@ -0,0 +1,91 @@
+//#region ../@warlock.js/ai/src/human/stores/memory.ts
+/**
+* In-memory {@link InterruptStore} — pending interrupts held in a
+* process-local `Map`, never persisted to disk.
+*
+* Owns: the `interruptId → {@link PendingInterrupt}` index and the
+* last-writer-wins `save` / `load` / `delete` / `list` semantics the
+* contract declares. Does NOT own: durability, cross-process sharing, or
+* TTL eviction — it is the zero-config default for dev, tests, and
+* single-process apps whose approval flow stays interactive (the run
+* `await`s the decision in-process and never needs to survive a restart).
+* Reach for `ai.human.interrupt.pg()` / `ai.human.interrupt.redis()` when
+* a reviewer rules out-of-process, hours later.
+*
+* Front it with the {@link memory} factory — callers never `new` it.
+*/
+var MemoryInterruptStore = class {
+	constructor() {
+		this.interrupts = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Persist a pending interrupt, keyed by its own `interruptId`.
+	* Overwrites any prior record for the same id — a call has exactly one
+	* live interrupt, so a re-save replaces rather than appends.
+	*/
+	async save(record) {
+		this.interrupts.set(record.interruptId, record);
+	}
+	/**
+	* Return the interrupt for an `interruptId`, or `undefined` when none is
+	* recorded (never raised, or already resolved + deleted).
+	*/
+	async load(interruptId) {
+		return this.interrupts.get(interruptId);
+	}
+	/**
+	* Drop the interrupt for an `interruptId`. Idempotent — deleting an
+	* absent id is a no-op.
+	*/
+	async delete(interruptId) {
+		this.interrupts.delete(interruptId);
+	}
+	/**
+	* List the interrupt ids the store knows, optionally filtered by a
+	* prefix. Returns a fresh array each call so a caller can mutate it
+	* freely without touching the backing index.
+	*/
+	async list(prefix) {
+		const ids = [...this.interrupts.keys()];
+		if (prefix === void 0) return ids;
+		return ids.filter((id) => id.startsWith(prefix));
+	}
+	/**
+	* The memory store has no backing table — there is nothing to migrate.
+	* Returns an empty string so callers can treat `schema()` uniformly
+	* across drivers.
+	*/
+	schema() {
+		return "";
+	}
+};
+/**
+* Create an in-memory {@link InterruptStore}. Zero-config — no client, no
+* connection. Suitable for dev, tests, and single-process apps whose
+* approval flow stays interactive and doesn't need resume across
+* restarts.
+*
+* @example
+* import { ai } from "@warlock.js/ai";
+*
+* const store = ai.human.interrupt.memory();
+*
+* const agent = ai.agent({
+*   model,
+*   tools: [deleteAccount],
+*   middleware: [
+*     ai.human.approval({
+*       policy: { type: "allowlist", tools: ["deleteAccount"] },
+*       store,
+*       handler,
+*     }),
+*   ],
+* });
+*/
+function memory() {
+	return new MemoryInterruptStore();
+}
+
+//#endregion
+export { memory };
+//# sourceMappingURL=memory.mjs.map

package/esm/ai/src/human/stores/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/human/stores/memory.ts"],"sourcesContent":["import type {\n  InterruptStore,\n  PendingInterrupt,\n} from \"../contracts/interrupt-store.contract\";\n\n/**\n * In-memory {@link InterruptStore} — pending interrupts held in a\n * process-local `Map`, never persisted to disk.\n *\n * Owns: the `interruptId → {@link PendingInterrupt}` index and the\n * last-writer-wins `save` / `load` / `delete` / `list` semantics the\n * contract declares. Does NOT own: durability, cross-process sharing, or\n * TTL eviction — it is the zero-config default for dev, tests, and\n * single-process apps whose approval flow stays interactive (the run\n * `await`s the decision in-process and never needs to survive a restart).\n * Reach for `ai.human.interrupt.pg()` / `ai.human.interrupt.redis()` when\n * a reviewer rules out-of-process, hours later.\n *\n * Front it with the {@link memory} factory — callers never `new` it.\n */\nclass MemoryInterruptStore implements InterruptStore {\n  /** Pending interrupts keyed by their own `interruptId`. */\n  private readonly interrupts = new Map<string, PendingInterrupt>();\n\n  /**\n   * Persist a pending interrupt, keyed by its own `interruptId`.\n   * Overwrites any prior record for the same id — a call has exactly one\n   * live interrupt, so a re-save replaces rather than appends.\n   */\n  public async save(record: PendingInterrupt): Promise<void> {\n    this.interrupts.set(record.interruptId, record);\n  }\n\n  /**\n   * Return the interrupt for an `interruptId`, or `undefined` when none is\n   * recorded (never raised, or already resolved + deleted).\n   */\n  public async load(\n    interruptId: string,\n  ): Promise<PendingInterrupt | undefined> {\n    return this.interrupts.get(interruptId);\n  }\n\n  /**\n   * Drop the interrupt for an `interruptId`. Idempotent — deleting an\n   * absent id is a no-op.\n   */\n  public async delete(interruptId: string): Promise<void> {\n    this.interrupts.delete(interruptId);\n  }\n\n  /**\n   * List the interrupt ids the store knows, optionally filtered by a\n   * prefix. Returns a fresh array each call so a caller can mutate it\n   * freely without touching the backing index.\n   */\n  public async list(prefix?: string): Promise<string[]> {\n    const ids = [...this.interrupts.keys()];\n\n    if (prefix === undefined) {\n      return ids;\n    }\n\n    return ids.filter((id) => id.startsWith(prefix));\n  }\n\n  /**\n   * The memory store has no backing table — there is nothing to migrate.\n   * Returns an empty string so callers can treat `schema()` uniformly\n   * across drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create an in-memory {@link InterruptStore}. Zero-config — no client, no\n * connection. Suitable for dev, tests, and single-process apps whose\n * approval flow stays interactive and doesn't need resume across\n * restarts.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n *\n * const store = ai.human.interrupt.memory();\n *\n * const agent = ai.agent({\n *   model,\n *   tools: [deleteAccount],\n *   middleware: [\n *     ai.human.approval({\n *       policy: { type: \"allowlist\", tools: [\"deleteAccount\"] },\n *       store,\n *       handler,\n *     }),\n *   ],\n * });\n */\nexport function memory(): InterruptStore {\n  return new MemoryInterruptStore();\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoBA,IAAM,uBAAN,MAAqD;;oCAErB,IAAI,IAA8B;;;;;;;CAOhE,MAAa,KAAK,QAAyC;EACzD,KAAK,WAAW,IAAI,OAAO,aAAa,MAAM;CAChD;;;;;CAMA,MAAa,KACX,aACuC;EACvC,OAAO,KAAK,WAAW,IAAI,WAAW;CACxC;;;;;CAMA,MAAa,OAAO,aAAoC;EACtD,KAAK,WAAW,OAAO,WAAW;CACpC;;;;;;CAOA,MAAa,KAAK,QAAoC;EACpD,MAAM,MAAM,CAAC,GAAG,KAAK,WAAW,KAAK,CAAC;EAEtC,IAAI,WAAW,QACb,OAAO;EAGT,OAAO,IAAI,QAAQ,OAAO,GAAG,WAAW,MAAM,CAAC;CACjD;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,SAAyB;CACvC,OAAO,IAAI,qBAAqB;AAClC"}

package/esm/ai/src/human/stores/pg.mjs

@@ -0,0 +1,220 @@
+//#region ../@warlock.js/ai/src/human/stores/pg.ts
+/**
+* Default backing table — provisions the store with no extra config when
+* the dev runs {@link InterruptStore.schema} through their migration tool.
+*/
+const DEFAULT_TABLE = "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 = /^[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";
+/**
+* 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 = `
+The @warlock.js/ai Postgres interrupt store requires the pg package.
+Install it 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);
+	}
+	return new sdk.Pool({ connectionString });
+}
+/**
+* Coerce a Postgres timestamp/text column to an ISO string. `pg` returns
+* `TIMESTAMPTZ` as a `Date`; normalize to the ISO wire shape the
+* {@link PendingInterrupt} contract declares.
+*/
+function toIso(value) {
+	if (value instanceof Date) return value.toISOString();
+	return value;
+}
+/**
+* Map a raw DB row to a {@link PendingInterrupt}. Column names match the
+* reference DDL 1:1; the `request` JSONB rides one column, so it is parsed
+* defensively (node-postgres parses `JSONB` already, but some pool
+* wrappers hand back the raw string).
+*/
+function rowToRecord(row) {
+	const request = typeof row.request === "string" ? JSON.parse(row.request) : row.request;
+	return {
+		interruptId: row.interrupt_id,
+		request,
+		status: row.status,
+		savedAt: toIso(row.saved_at)
+	};
+}
+/**
+* Postgres-backed {@link InterruptStore} — one durable row per pending
+* interrupt, keyed by `interrupt_id`.
+*
+* Owns: durable round-tripping of the {@link PendingInterrupt} envelope so
+* a reviewer can rule out-of-process (a webhook approves hours later, in a
+* different process), the reference DDL via {@link PgInterruptStore.schema},
+* and prefix-filtered enumeration. 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 `schema()` through their own tool — never
+* auto-migrated).
+*
+* Like the snapshot store, a call has exactly one live interrupt, so
+* `save()` upserts on the `interrupt_id` primary key.
+*
+* Front it with the {@link pg} factory — callers never `new` it.
+*/
+var PgInterruptStore = class {
+	constructor(options) {
+		const table = options.table ?? DEFAULT_TABLE;
+		if (!SAFE_IDENTIFIER.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.");
+			this.clientPromise = Promise.resolve(options.client);
+			return;
+		}
+		if (options.connectionString) {
+			this.clientPromise = buildPgClient(options.connectionString);
+			return;
+		}
+		throw new TypeError("ai.human.interrupt.pg 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;
+	}
+	/**
+	* Persist a pending interrupt, keyed by its own `interrupt_id`. Upserts
+	* — a call has exactly one live interrupt, so a second save for the same
+	* id overwrites the payload rather than appending.
+	*/
+	async save(record) {
+		await (await this.client()).query(`INSERT INTO ${this.table} (interrupt_id, request, status, saved_at)
+       VALUES ($1, $2::jsonb, $3, $4)
+       ON CONFLICT (interrupt_id) DO UPDATE
+         SET request = EXCLUDED.request,
+             status = EXCLUDED.status,
+             saved_at = EXCLUDED.saved_at`, [
+			record.interruptId,
+			JSON.stringify(record.request),
+			record.status,
+			record.savedAt
+		]);
+	}
+	/**
+	* Load the interrupt for an `interruptId`, or `undefined` when none is
+	* recorded.
+	*/
+	async load(interruptId) {
+		const { rows } = await (await this.client()).query(`SELECT interrupt_id, request, status, saved_at
+       FROM ${this.table}
+       WHERE interrupt_id = $1`, [interruptId]);
+		if (rows.length === 0) return;
+		return rowToRecord(rows[0]);
+	}
+	/**
+	* Drop the interrupt for an `interruptId`. Idempotent — deleting an
+	* absent id deletes zero rows.
+	*/
+	async delete(interruptId) {
+		await (await this.client()).query(`DELETE FROM ${this.table} WHERE interrupt_id = $1`, [interruptId]);
+	}
+	/**
+	* List the interrupt ids known to the store, optionally filtered by a
+	* prefix. The `_` and `%` LIKE wildcards in the prefix are escaped so an
+	* opaque interruptId that happens to contain them is matched literally.
+	*/
+	async list(prefix) {
+		const client = await this.client();
+		if (prefix === void 0) {
+			const { rows } = await client.query(`SELECT interrupt_id FROM ${this.table}`);
+			return rows.map((row) => row.interrupt_id);
+		}
+		const escaped = prefix.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
+		const { rows } = await client.query(`SELECT interrupt_id FROM ${this.table}
+       WHERE interrupt_id LIKE $1 ESCAPE '\\'`, [`${escaped}%`]);
+		return rows.map((row) => row.interrupt_id);
+	}
+	/**
+	* Return the reference DDL for this store's backing table, interpolating
+	* the configured table name. The dev runs it through their migration
+	* tool — the framework never auto-migrates.
+	*
+	* @example
+	* await pool.query(store.schema());
+	*/
+	schema() {
+		return [
+			`CREATE TABLE IF NOT EXISTS ${this.table} (`,
+			`  interrupt_id  TEXT PRIMARY KEY,`,
+			`  request       JSONB NOT NULL,`,
+			`  status        TEXT NOT NULL,`,
+			`  saved_at      TIMESTAMPTZ NOT NULL DEFAULT now()`,
+			`);`,
+			`CREATE INDEX IF NOT EXISTS idx_${this.table}_saved_at`,
+			`  ON ${this.table} (saved_at);`
+		].join("\n");
+	}
+};
+/**
+* Create a Postgres-backed {@link InterruptStore}. 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, the curated install string surfaces on first use, never at
+* import. Run {@link InterruptStore.schema} through your migration tool
+* once before use; the store never auto-migrates.
+*
+* @example
+* import { Pool } from "pg";
+* import { ai } from "@warlock.js/ai";
+*
+* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+* const store = ai.human.interrupt.pg({ client: pool });
+*
+* // Once, via your migration tooling:
+* // await pool.query(store.schema());
+*
+* @example
+* // Let the store build its own pool from a connection string:
+* const store = ai.human.interrupt.pg({
+*   connectionString: process.env.DATABASE_URL,
+* });
+*/
+function pg(options) {
+	return new PgInterruptStore(options);
+}
+
+//#endregion
+export { pg };
+//# sourceMappingURL=pg.mjs.map

package/esm/ai/src/human/stores/pg.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/human/stores/pg.ts"],"sourcesContent":["import type {\n  InterruptStore,\n  PendingInterrupt,\n  PgClientLike,\n} from \"../contracts/interrupt-store.contract\";\n\n/**\n * Options for the Postgres {@link InterruptStore}.\n *\n * Two mutually-supportive ways to supply the connection:\n * - **`client`** — pass an already-built `pg.Pool` / `pg.Client` (anything\n *   satisfying {@link PgClientLike}). The store only ever calls `query`\n *   and never opens or closes it; a single pool can back both an\n *   orchestrator's checkpoint/snapshot stores and this interrupt table.\n * - **`connectionString`** — let the store lazily `import(\"pg\")` and build\n *   its own `Pool`. `@warlock.js/ai` takes **no** hard dependency on\n *   `pg` (it is an optional peer); when it is absent the store throws a\n *   curated install string at first use, never a raw module-resolution\n *   stack trace at import.\n *\n * Exactly one of the two must be present.\n */\nexport interface PgInterruptOptions {\n  /** An already-built `pg.Pool` / `pg.Client` — anything matching {@link PgClientLike}. */\n  client?: PgClientLike;\n\n  /** Connection string the store passes to a lazily-imported `pg.Pool`. */\n  connectionString?: string;\n\n  /**\n   * Backing table name. Defaults to `warlock_ai_human_interrupts`. Must be\n   * a safe SQL identifier — it is interpolated into DDL/DML.\n   */\n  table?: string;\n}\n\n/**\n * Default backing table — provisions the store with no extra config when\n * the dev runs {@link InterruptStore.schema} through their migration tool.\n */\nconst DEFAULT_TABLE = \"warlock_ai_human_interrupts\";\n\n/**\n * Allowed characters in a Postgres identifier (table name). The table name\n * is interpolated into DDL/DML, so anything outside this conservative\n * ASCII subset is rejected — interpolating an arbitrary string would be a\n * SQL-injection footgun (mirrors `@warlock.js/ai`'s pg stores).\n */\nconst SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Module specifier for the optional `pg` driver. Held in a `string`\n * variable so the dynamic `import()` is not statically resolved at\n * compile time — `pg` is an optional peer that need not be installed for\n * this package to type-check or for a memory-only consumer to run.\n */\nconst PG_MODULE = \"pg\";\n\n/**\n * Curated install string surfaced (at use time) when a `connectionString`\n * is configured but the optional `pg` driver is absent. Never thrown at\n * import — a memory-only consumer must be able to load this module.\n */\nconst PG_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai Postgres interrupt store requires the pg package.\nInstall it with:\n\n  npm install pg\n\nOr with your preferred package manager:\n\n  pnpm add pg\n  yarn add pg\n`.trim();\n\n/**\n * Minimal structural view of a `pg.Pool` constructor — just enough of the\n * `pg` module surface for the store to build a client when handed a\n * `connectionString`. Declared locally (rather than `typeof import(\"pg\")`)\n * so this module type-checks even when `pg` is not installed.\n */\ninterface PgModuleLike {\n  Pool: new (config: { connectionString: string }) => PgClientLike;\n}\n\n/**\n * Lazily import `pg` and return a `Pool` built from `connectionString`. A\n * bare `catch` rethrows the curated install string — a missing optional\n * peer surfaces as actionable guidance, never a raw resolution error.\n */\nasync function buildPgClient(connectionString: string): Promise<PgClientLike> {\n  let sdk: PgModuleLike;\n\n  try {\n    sdk = (await import(PG_MODULE)) as unknown as PgModuleLike;\n  } catch {\n    throw new Error(PG_INSTALL_INSTRUCTIONS);\n  }\n\n  return new sdk.Pool({ connectionString });\n}\n\n/**\n * Coerce a Postgres timestamp/text column to an ISO string. `pg` returns\n * `TIMESTAMPTZ` as a `Date`; normalize to the ISO wire shape the\n * {@link PendingInterrupt} contract declares.\n */\nfunction toIso(value: unknown): string {\n  if (value instanceof Date) {\n    return value.toISOString();\n  }\n\n  return value as string;\n}\n\n/**\n * Map a raw DB row to a {@link PendingInterrupt}. Column names match the\n * reference DDL 1:1; the `request` JSONB rides one column, so it is parsed\n * defensively (node-postgres parses `JSONB` already, but some pool\n * wrappers hand back the raw string).\n */\nfunction rowToRecord(row: Record<string, unknown>): PendingInterrupt {\n  const request =\n    typeof row.request === \"string\" ? JSON.parse(row.request) : row.request;\n\n  return {\n    interruptId: row.interrupt_id as string,\n    request: request as PendingInterrupt[\"request\"],\n    status: row.status as PendingInterrupt[\"status\"],\n    savedAt: toIso(row.saved_at),\n  };\n}\n\n/**\n * Postgres-backed {@link InterruptStore} — one durable row per pending\n * interrupt, keyed by `interrupt_id`.\n *\n * Owns: durable round-tripping of the {@link PendingInterrupt} envelope so\n * a reviewer can rule out-of-process (a webhook approves hours later, in a\n * different process), the reference DDL via {@link PgInterruptStore.schema},\n * and prefix-filtered enumeration. Does NOT own: the connection lifecycle\n * (a dev-supplied client is never closed; a store-built `Pool` from a\n * `connectionString` is also left open for the process to reuse) or schema\n * migration (the dev runs `schema()` through their own tool — never\n * auto-migrated).\n *\n * Like the snapshot store, a call has exactly one live interrupt, so\n * `save()` upserts on the `interrupt_id` primary key.\n *\n * Front it with the {@link pg} factory — callers never `new` it.\n */\nclass PgInterruptStore implements InterruptStore {\n  /** Validated backing table name, safe to interpolate into SQL. */\n  private readonly table: string;\n\n  /**\n   * A ready client, or a promise resolving to one the store builds lazily\n   * from a `connectionString`. Resolved once and memoized so the optional\n   * `pg` import happens at most once.\n   */\n  private clientPromise: Promise<PgClientLike>;\n\n  public constructor(options: PgInterruptOptions) {\n    const table = options.table ?? DEFAULT_TABLE;\n\n    if (!SAFE_IDENTIFIER.test(table)) {\n      throw new TypeError(\n        `ai.human.interrupt.pg: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n      );\n    }\n\n    this.table = table;\n\n    if (options.client) {\n      if (typeof options.client.query !== \"function\") {\n        throw new TypeError(\n          \"ai.human.interrupt.pg requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.\",\n        );\n      }\n\n      this.clientPromise = Promise.resolve(options.client);\n\n      return;\n    }\n\n    if (options.connectionString) {\n      // Defer the optional `pg` import to first use — a curated install\n      // string surfaces from `buildPgClient`, not at construction.\n      this.clientPromise = buildPgClient(options.connectionString);\n\n      return;\n    }\n\n    throw new TypeError(\n      \"ai.human.interrupt.pg requires either a 'client' or a 'connectionString' option.\",\n    );\n  }\n\n  /**\n   * Resolve the backing client, surfacing the lazy `pg` import's curated\n   * install string on the first call that needs it.\n   */\n  private client(): Promise<PgClientLike> {\n    return this.clientPromise;\n  }\n\n  /**\n   * Persist a pending interrupt, keyed by its own `interrupt_id`. Upserts\n   * — a call has exactly one live interrupt, so a second save for the same\n   * id overwrites the payload rather than appending.\n   */\n  public async save(record: PendingInterrupt): Promise<void> {\n    const client = await this.client();\n\n    await client.query(\n      `INSERT INTO ${this.table} (interrupt_id, request, status, saved_at)\n       VALUES ($1, $2::jsonb, $3, $4)\n       ON CONFLICT (interrupt_id) DO UPDATE\n         SET request = EXCLUDED.request,\n             status = EXCLUDED.status,\n             saved_at = EXCLUDED.saved_at`,\n      [\n        record.interruptId,\n        JSON.stringify(record.request),\n        record.status,\n        record.savedAt,\n      ],\n    );\n  }\n\n  /**\n   * Load the interrupt for an `interruptId`, or `undefined` when none is\n   * recorded.\n   */\n  public async load(\n    interruptId: string,\n  ): Promise<PendingInterrupt | undefined> {\n    const client = await this.client();\n\n    const { rows } = await client.query(\n      `SELECT interrupt_id, request, status, saved_at\n       FROM ${this.table}\n       WHERE interrupt_id = $1`,\n      [interruptId],\n    );\n\n    if (rows.length === 0) {\n      return undefined;\n    }\n\n    return rowToRecord(rows[0] as Record<string, unknown>);\n  }\n\n  /**\n   * Drop the interrupt for an `interruptId`. Idempotent — deleting an\n   * absent id deletes zero rows.\n   */\n  public async delete(interruptId: string): Promise<void> {\n    const client = await this.client();\n\n    await client.query(\n      `DELETE FROM ${this.table} WHERE interrupt_id = $1`,\n      [interruptId],\n    );\n  }\n\n  /**\n   * List the interrupt ids known to the store, optionally filtered by a\n   * prefix. The `_` and `%` LIKE wildcards in the prefix are escaped so an\n   * opaque interruptId that happens to contain them is matched literally.\n   */\n  public async list(prefix?: string): Promise<string[]> {\n    const client = await this.client();\n\n    if (prefix === undefined) {\n      const { rows } = await client.query(\n        `SELECT interrupt_id FROM ${this.table}`,\n      );\n\n      return rows.map(\n        (row) => (row as Record<string, unknown>).interrupt_id as string,\n      );\n    }\n\n    const escaped = prefix\n      .replace(/\\\\/g, \"\\\\\\\\\")\n      .replace(/_/g, \"\\\\_\")\n      .replace(/%/g, \"\\\\%\");\n\n    const { rows } = await client.query(\n      `SELECT interrupt_id FROM ${this.table}\n       WHERE interrupt_id LIKE $1 ESCAPE '\\\\'`,\n      [`${escaped}%`],\n    );\n\n    return rows.map(\n      (row) => (row as Record<string, unknown>).interrupt_id as string,\n    );\n  }\n\n  /**\n   * Return the reference DDL for this store's backing table, interpolating\n   * the configured table name. The dev runs it through their migration\n   * tool — the framework never auto-migrates.\n   *\n   * @example\n   * await pool.query(store.schema());\n   */\n  public schema(): string {\n    return [\n      `CREATE TABLE IF NOT EXISTS ${this.table} (`,\n      `  interrupt_id  TEXT PRIMARY KEY,`,\n      `  request       JSONB NOT NULL,`,\n      `  status        TEXT NOT NULL,`,\n      `  saved_at      TIMESTAMPTZ NOT NULL DEFAULT now()`,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${this.table}_saved_at`,\n      `  ON ${this.table} (saved_at);`,\n    ].join(\"\\n\");\n  }\n}\n\n/**\n * Create a Postgres-backed {@link InterruptStore}. Either pass a live\n * `pg.Pool` / `pg.Client` (`{ client }`) — `@warlock.js/ai` never\n * imports `pg` in that case — or a `{ connectionString }` and let the\n * store lazily `import(\"pg\")` to build its own pool. When `pg` is not\n * installed, the curated install string surfaces on first use, never at\n * import. Run {@link InterruptStore.schema} through your migration tool\n * once before use; the store never auto-migrates.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n * const store = ai.human.interrupt.pg({ client: pool });\n *\n * // Once, via your migration tooling:\n * // await pool.query(store.schema());\n *\n * @example\n * // Let the store build its own pool from a connection string:\n * const store = ai.human.interrupt.pg({\n *   connectionString: process.env.DATABASE_URL,\n * });\n */\nexport function pg(options: PgInterruptOptions): InterruptStore {\n  return new PgInterruptStore(options);\n}\n"],"mappings":"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"}