@warlock.js/ai 4.3.0 → 4.5.0

package/esm/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/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/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/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/human/resume.d.mts

@@ -0,0 +1,54 @@
+import { ApprovalDecision } from "./contracts/approval.type.mjs";
+import { ResumeOptions, ResumeResult } from "./contracts/resume.type.mjs";
+//#region ../@warlock.js/ai/src/human/resume.d.ts
+/**
+ * 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);
+ * }
+ */
+declare function resume<TOutput = unknown>(interruptId: string, decision: ApprovalDecision, options: ResumeOptions<TOutput>): Promise<ResumeResult<TOutput>>;
+//#endregion
+export { resume };
+//# sourceMappingURL=resume.d.mts.map

package/esm/human/resume.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/resume.ts"],"mappings":";;;;;;;AAyIA;;;;;;;;;;;;;;;;;;;;;;AAI+B;;;;;;;;;;;;;;;;;;;;;iBAJT,MAAA,oBACpB,WAAA,UACA,QAAA,EAAU,gBAAA,EACV,OAAA,EAAS,aAAA,CAAc,OAAA,IACtB,OAAA,CAAQ,YAAA,CAAa,OAAA"}

package/esm/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/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/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/human/stores/memory.d.mts

@@ -0,0 +1,30 @@
+import { InterruptStore } from "../contracts/interrupt-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/human/stores/memory.d.ts
+/**
+ * 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,
+ *     }),
+ *   ],
+ * });
+ */
+declare function memory(): InterruptStore;
+//#endregion
+export { memory };
+//# sourceMappingURL=memory.d.mts.map

package/esm/human/stores/memory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/stores/memory.ts"],"mappings":";;;;;AAmGA;;;;AAAwC;;;;;;;;;;;;;;;;;iBAAxB,MAAA,IAAU,cAAc"}

package/esm/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/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/human/stores/pg.d.mts

@@ -0,0 +1,59 @@
+import { InterruptStore, PgClientLike } from "../contracts/interrupt-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/human/stores/pg.d.ts
+/**
+ * Options for the Postgres {@link InterruptStore}.
+ *
+ * Two mutually-supportive ways to supply the connection:
+ * - **`client`** — pass an already-built `pg.Pool` / `pg.Client` (anything
+ *   satisfying {@link PgClientLike}). The store only ever calls `query`
+ *   and never opens or closes it; a single pool can back both an
+ *   orchestrator's checkpoint/snapshot stores and this interrupt table.
+ * - **`connectionString`** — let the store lazily `import("pg")` and build
+ *   its own `Pool`. `@warlock.js/ai` takes **no** hard dependency on
+ *   `pg` (it is an optional peer); when it is absent the store throws a
+ *   curated install string at first use, never a raw module-resolution
+ *   stack trace at import.
+ *
+ * Exactly one of the two must be present.
+ */
+interface PgInterruptOptions {
+  /** An already-built `pg.Pool` / `pg.Client` — anything matching {@link PgClientLike}. */
+  client?: PgClientLike;
+  /** Connection string the store passes to a lazily-imported `pg.Pool`. */
+  connectionString?: string;
+  /**
+   * Backing table name. Defaults to `warlock_ai_human_interrupts`. Must be
+   * a safe SQL identifier — it is interpolated into DDL/DML.
+   */
+  table?: string;
+}
+/**
+ * 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,
+ * });
+ */
+declare function pg(options: PgInterruptOptions): InterruptStore;
+//#endregion
+export { PgInterruptOptions, pg };
+//# sourceMappingURL=pg.d.mts.map

package/esm/human/stores/pg.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/stores/pg.ts"],"mappings":";;;;;AAsBA;;;;;;;;;AAWO;AA0TP;;;;UArUiB,kBAAA;EAqUE;EAnUjB,MAAA,GAAS,YAAY;EAmUwC;EAhU7D,gBAAA;;;;;EAMA,KAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0Tc,EAAA,CAAG,OAAA,EAAS,kBAAA,GAAqB,cAAc"}