@warlock.js/ai 4.8.2 → 4.9.1

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

@@ -1 +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"}
+{"version":3,"file":"resume-seed.mjs","names":[],"sources":["../../../../../../../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

@@ -1,6 +1,6 @@
 import { ApprovalDecision } from "./contracts/approval.type.mjs";
 import { ResumeOptions, ResumeResult } from "./contracts/resume.type.mjs";
-//#region ../@warlock.js/ai/src/human/resume.d.ts
+//#region ../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)`.

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

@@ -1 +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"}
+{"version":3,"file":"resume.d.mts","names":[],"sources":["../../../../../../../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

@@ -1,6 +1,6 @@
 import { clearSeededDecision, seedDecision } from "./resume-seed.mjs";
 
-//#region ../@warlock.js/ai/src/human/resume.ts
+//#region ../ai/src/human/resume.ts
 /**
 * Validate that a decision is a well-formed {@link ApprovalDecision}.
 *

package/esm/human/resume.mjs.map

@@ -1 +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"}
+{"version":3,"file":"resume.mjs","names":[],"sources":["../../../../../../../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/memory.d.mts

@@ -1,6 +1,6 @@
 import { InterruptStore } from "../contracts/interrupt-store.contract.mjs";
 
-//#region ../@warlock.js/ai/src/human/stores/memory.d.ts
+//#region ../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

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

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

package/esm/human/stores/memory.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/human/stores/memory.ts
+//#region ../ai/src/human/stores/memory.ts
 /**
 * In-memory {@link InterruptStore} — pending interrupts held in a
 * process-local `Map`, never persisted to disk.

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

@@ -1 +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"}
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../../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

@@ -1,6 +1,6 @@
 import { InterruptStore, PgClientLike } from "../contracts/interrupt-store.contract.mjs";
 
-//#region ../@warlock.js/ai/src/human/stores/pg.d.ts
+//#region ../ai/src/human/stores/pg.d.ts
 /**
  * Options for the Postgres {@link InterruptStore}.
  *

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

@@ -1 +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"}
+{"version":3,"file":"pg.d.mts","names":[],"sources":["../../../../../../../../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"}

package/esm/human/stores/pg.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/human/stores/pg.ts
+//#region ../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.

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

@@ -1 +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":";;;;;AAwCA,MAAM,gBAAgB;;;;;;;AAQtB,MAAM,kBAAkB;;;;;;;AAQxB,MAAM,YAAY;;;;;;AAOlB,MAAM,0BAA0B;;;;;;;;;;EAU9B,KAAK;;;;;;AAiBP,eAAe,cAAc,kBAAiD;CAC5E,IAAI;CAEJ,IAAI;EACF,MAAO,MAAM,OAAO;CACtB,QAAQ;EACN,MAAM,IAAI,MAAM,uBAAuB;CACzC;CAEA,OAAO,IAAI,IAAI,KAAK,EAAE,iBAAiB,CAAC;AAC1C;;;;;;AAOA,SAAS,MAAM,OAAwB;CACrC,IAAI,iBAAiB,MACnB,OAAO,MAAM,YAAY;CAG3B,OAAO;AACT;;;;;;;AAQA,SAAS,YAAY,KAAgD;CACnE,MAAM,UACJ,OAAO,IAAI,YAAY,WAAW,KAAK,MAAM,IAAI,OAAO,IAAI,IAAI;CAElE,OAAO;EACL,aAAa,IAAI;EACR;EACT,QAAQ,IAAI;EACZ,SAAS,MAAM,IAAI,QAAQ;CAC7B;AACF;;;;;;;;;;;;;;;;;;;AAoBA,IAAM,mBAAN,MAAiD;CAW/C,AAAO,YAAY,SAA6B;EAC9C,MAAM,QAAQ,QAAQ,SAAS;EAE/B,IAAI,CAAC,gBAAgB,KAAK,KAAK,GAC7B,MAAM,IAAI,UACR,8CAA8C,MAAM,oCACtD;EAGF,KAAK,QAAQ;EAEb,IAAI,QAAQ,QAAQ;GAClB,IAAI,OAAO,QAAQ,OAAO,UAAU,YAClC,MAAM,IAAI,UACR,sHACF;GAGF,KAAK,gBAAgB,QAAQ,QAAQ,QAAQ,MAAM;GAEnD;EACF;EAEA,IAAI,QAAQ,kBAAkB;GAG5B,KAAK,gBAAgB,cAAc,QAAQ,gBAAgB;GAE3D;EACF;EAEA,MAAM,IAAI,UACR,kFACF;CACF;;;;;CAMA,AAAQ,SAAgC;EACtC,OAAO,KAAK;CACd;;;;;;CAOA,MAAa,KAAK,QAAyC;EAGzD,OAAM,MAFe,KAAK,OAAO,EAErB,CAAC,MACX,eAAe,KAAK,MAAM;;;;;4CAM1B;GACE,OAAO;GACP,KAAK,UAAU,OAAO,OAAO;GAC7B,OAAO;GACP,OAAO;EACT,CACF;CACF;;;;;CAMA,MAAa,KACX,aACuC;EAGvC,MAAM,EAAE,SAAS,OAAM,MAFF,KAAK,OAAO,EAEJ,CAAC,MAC5B;cACQ,KAAK,MAAM;iCAEnB,CAAC,WAAW,CACd;EAEA,IAAI,KAAK,WAAW,GAClB;EAGF,OAAO,YAAY,KAAK,EAA6B;CACvD;;;;;CAMA,MAAa,OAAO,aAAoC;EAGtD,OAAM,MAFe,KAAK,OAAO,EAErB,CAAC,MACX,eAAe,KAAK,MAAM,2BAC1B,CAAC,WAAW,CACd;CACF;;;;;;CAOA,MAAa,KAAK,QAAoC;EACpD,MAAM,SAAS,MAAM,KAAK,OAAO;EAEjC,IAAI,WAAW,QAAW;GACxB,MAAM,EAAE,SAAS,MAAM,OAAO,MAC5B,4BAA4B,KAAK,OACnC;GAEA,OAAO,KAAK,KACT,QAAS,IAAgC,YAC5C;EACF;EAEA,MAAM,UAAU,OACb,QAAQ,OAAO,MAAM,CAAC,CACtB,QAAQ,MAAM,KAAK,CAAC,CACpB,QAAQ,MAAM,KAAK;EAEtB,MAAM,EAAE,SAAS,MAAM,OAAO,MAC5B,4BAA4B,KAAK,MAAM;gDAEvC,CAAC,GAAG,QAAQ,EAAE,CAChB;EAEA,OAAO,KAAK,KACT,QAAS,IAAgC,YAC5C;CACF;;;;;;;;;CAUA,AAAO,SAAiB;EACtB,OAAO;GACL,8BAA8B,KAAK,MAAM;GACzC;GACA;GACA;GACA;GACA;GACA,kCAAkC,KAAK,MAAM;GAC7C,QAAQ,KAAK,MAAM;EACrB,CAAC,CAAC,KAAK,IAAI;CACb;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,GAAG,SAA6C;CAC9D,OAAO,IAAI,iBAAiB,OAAO;AACrC"}
+{"version":3,"file":"pg.mjs","names":[],"sources":["../../../../../../../../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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"}

package/esm/human/stores/redis.d.mts

@@ -1,6 +1,6 @@
 import { InterruptStore, RedisClientLike } from "../contracts/interrupt-store.contract.mjs";
 
-//#region ../@warlock.js/ai/src/human/stores/redis.d.ts
+//#region ../ai/src/human/stores/redis.d.ts
 /**
  * Options for the Redis {@link InterruptStore}.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"redis.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/stores/redis.ts"],"mappings":";;;;;AAqBA;;;;;;;;;AAYQ;AA+RR;;;UA3SiB,qBAAA;EA2Sc;EAzS7B,MAAA,GAAS,eAAe;EAyS6B;EAtSrD,GAAA;EAsSmE;;;;;EA/RnE,MAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBA+Rc,KAAA,CAAM,OAAA,EAAS,qBAAA,GAAwB,cAAc"}
+{"version":3,"file":"redis.d.mts","names":[],"sources":["../../../../../../../../ai/src/human/stores/redis.ts"],"mappings":";;;;;AAqBA;;;;;;;;;AAYQ;AA+RR;;;UA3SiB,qBAAA;EA2Sc;EAzS7B,MAAA,GAAS,eAAe;EAyS6B;EAtSrD,GAAA;EAsSmE;;;;;EA/RnE,MAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBA+Rc,KAAA,CAAM,OAAA,EAAS,qBAAA,GAAwB,cAAc"}

package/esm/human/stores/redis.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/human/stores/redis.ts
+//#region ../ai/src/human/stores/redis.ts
 /**
 * Default key prefix — namespaces the store's keys inside a shared Redis
 * database so interrupt records coexist with other data without collision.

package/esm/human/stores/redis.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"redis.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/stores/redis.ts"],"sourcesContent":["import type {\n  InterruptStore,\n  PendingInterrupt,\n  RedisClientLike,\n} from \"../contracts/interrupt-store.contract\";\n\n/**\n * Options for the Redis {@link InterruptStore}.\n *\n * Two mutually-supportive ways to supply the connection:\n * - **`client`** — pass an already-connected `redis` client (anything\n *   satisfying {@link RedisClientLike}). The store only calls\n *   `get` / `set` / `del` and never connects or quits it.\n * - **`url`** — let the store lazily `import(\"redis\")`, build a client\n *   from the url, and connect it. `@warlock.js/ai` takes **no** hard\n *   dependency on `redis` (it is an optional peer); when it is absent the\n *   store throws a curated install string at first use, never a raw\n *   module-resolution stack trace at import.\n *\n * Exactly one of the two must be present.\n */\nexport interface RedisInterruptOptions {\n  /** An already-connected `redis` client — anything matching {@link RedisClientLike}. */\n  client?: RedisClientLike;\n\n  /** Connection url the store passes to a lazily-imported `createClient`. */\n  url?: string;\n\n  /**\n   * Key prefix prepended to every key this store writes. Lets one Redis\n   * database back multiple stores without collision. Defaults to\n   * `warlock:ai-human:interrupt:`.\n   */\n  prefix?: string;\n}\n\n/**\n * Default key prefix — namespaces the store's keys inside a shared Redis\n * database so interrupt records coexist with other data without collision.\n */\nconst DEFAULT_PREFIX = \"warlock:ai-human:interrupt:\";\n\n/**\n * Index key (under the configured prefix) holding the JSON array of live\n * interrupt ids. The structural {@link RedisClientLike} surface exposes no\n * `SCAN` / `KEYS`, so enumeration for `list()` is self-maintained.\n */\nconst INDEX_SUFFIX = \"index\";\n\n/**\n * Module specifier for the optional `redis` driver. Held in a `string`\n * variable so the dynamic `import()` is not statically resolved at compile\n * time — `redis` is an optional peer that need not be installed for this\n * package to type-check or for a memory-only consumer to run.\n */\nconst REDIS_MODULE = \"redis\";\n\n/**\n * Curated install string surfaced (at use time) when a `url` is configured\n * but the optional `redis` driver is absent. Never thrown at import — a\n * memory-only consumer must be able to load this module.\n */\nconst REDIS_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai Redis interrupt store requires the redis package.\nInstall it with:\n\n  npm install redis\n\nOr with your preferred package manager:\n\n  pnpm add redis\n  yarn add redis\n`.trim();\n\n/**\n * Minimal structural view of the `redis` module surface — just enough to\n * build and connect a client from a url. Declared locally (rather than\n * `typeof import(\"redis\")`) so this module type-checks even when `redis`\n * is not installed.\n */\ninterface RedisModuleLike {\n  createClient(config: {\n    url: string;\n  }): RedisClientLike & { connect(): Promise<unknown> };\n}\n\n/**\n * Lazily import `redis`, build a client from `url`, and connect it. A bare\n * `catch` rethrows the curated install string — a missing optional peer\n * surfaces as actionable guidance, never a raw resolution error.\n */\nasync function buildRedisClient(url: string): Promise<RedisClientLike> {\n  let sdk: RedisModuleLike;\n\n  try {\n    sdk = (await import(REDIS_MODULE)) as unknown as RedisModuleLike;\n  } catch {\n    throw new Error(REDIS_INSTALL_INSTRUCTIONS);\n  }\n\n  const client = sdk.createClient({ url });\n  await client.connect();\n\n  return client;\n}\n\n/**\n * Redis-backed {@link InterruptStore} — one JSON string value per pending\n * interrupt, under a namespaced key, plus a self-maintained id index so\n * `list()` works without `SCAN`/`KEYS`.\n *\n * Owns: durable round-tripping of the {@link PendingInterrupt} envelope so\n * a reviewer can rule out-of-process, the namespaced key layout, and the\n * per-store id index that backs enumeration. Does NOT own: durability\n * guarantees beyond Redis's own, the connection lifecycle (a dev-supplied\n * client is never disconnected; a store-built client from a `url` is left\n * connected for the process to reuse), or migration —\n * {@link RedisInterruptStore.schema} returns an empty string.\n *\n * A call has exactly one live interrupt, so `save()` overwrites the key.\n *\n * Front it with the {@link redis} factory — callers never `new` it.\n */\nclass RedisInterruptStore implements InterruptStore {\n  /** Key prefix namespacing every key this store writes. */\n  private readonly prefix: string;\n\n  /**\n   * A ready client, or a promise resolving to one the store builds lazily\n   * from a `url`. Resolved once and memoized so the optional `redis`\n   * import + connect happens at most once.\n   */\n  private clientPromise: Promise<RedisClientLike>;\n\n  public constructor(options: RedisInterruptOptions) {\n    this.prefix = options.prefix ?? DEFAULT_PREFIX;\n\n    if (options.client) {\n      if (\n        typeof options.client.get !== \"function\" ||\n        typeof options.client.set !== \"function\" ||\n        typeof options.client.del !== \"function\"\n      ) {\n        throw new TypeError(\n          \"ai.human.interrupt.redis requires a 'client' option implementing { get, set, del } — pass a connected redis client.\",\n        );\n      }\n\n      this.clientPromise = Promise.resolve(options.client);\n\n      return;\n    }\n\n    if (options.url) {\n      // Defer the optional `redis` import to first use — a curated install\n      // string surfaces from `buildRedisClient`, not at construction.\n      this.clientPromise = buildRedisClient(options.url);\n\n      return;\n    }\n\n    throw new TypeError(\n      \"ai.human.interrupt.redis requires either a 'client' or a 'url' option.\",\n    );\n  }\n\n  /**\n   * Resolve the backing client, surfacing the lazy `redis` import's\n   * curated install string on the first call that needs it.\n   */\n  private client(): Promise<RedisClientLike> {\n    return this.clientPromise;\n  }\n\n  /**\n   * Persist a pending interrupt, keyed by its own `interruptId`, and index\n   * the id for enumeration. Overwrites any prior record for the same id —\n   * a call has exactly one live interrupt.\n   */\n  public async save(record: PendingInterrupt): Promise<void> {\n    const client = await this.client();\n\n    await client.set(this.recordKey(record.interruptId), JSON.stringify(record));\n    await this.indexId(record.interruptId);\n  }\n\n  /**\n   * Load the interrupt for an `interruptId`, or `undefined` when the key is\n   * missing. Redis returns `null` for an absent key — converted to\n   * `undefined` at the boundary.\n   */\n  public async load(\n    interruptId: string,\n  ): Promise<PendingInterrupt | undefined> {\n    const client = await this.client();\n    const raw = await client.get(this.recordKey(interruptId));\n\n    if (raw === null) {\n      return undefined;\n    }\n\n    return JSON.parse(raw) as PendingInterrupt;\n  }\n\n  /**\n   * Drop the interrupt for an `interruptId` and de-index its id. Idempotent\n   * — deleting an absent id is a no-op.\n   */\n  public async delete(interruptId: string): Promise<void> {\n    const client = await this.client();\n\n    await client.del(this.recordKey(interruptId));\n    await this.deindexId(interruptId);\n  }\n\n  /**\n   * List the interrupt ids known to the store, optionally filtered by a\n   * prefix. Reads the self-maintained index document.\n   */\n  public async list(prefix?: string): Promise<string[]> {\n    const ids = await this.readIndex();\n\n    if (prefix === undefined) {\n      return ids;\n    }\n\n    return ids.filter((id) => id.startsWith(prefix));\n  }\n\n  /**\n   * Redis needs no relational table — there is nothing to migrate. Returns\n   * an empty string so callers can treat `schema()` uniformly across\n   * drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n\n  /**\n   * Read and parse the id index, defaulting to an empty list when absent.\n   */\n  private async readIndex(): Promise<string[]> {\n    const client = await this.client();\n    const raw = await client.get(this.indexKey());\n\n    if (raw === null) {\n      return [];\n    }\n\n    return JSON.parse(raw) as string[];\n  }\n\n  /**\n   * Add an interrupt id to the index, no-op when already present.\n   */\n  private async indexId(interruptId: string): Promise<void> {\n    const ids = await this.readIndex();\n\n    if (ids.includes(interruptId)) {\n      return;\n    }\n\n    ids.push(interruptId);\n\n    const client = await this.client();\n    await client.set(this.indexKey(), JSON.stringify(ids));\n  }\n\n  /**\n   * Remove an interrupt id from the index, no-op when absent.\n   */\n  private async deindexId(interruptId: string): Promise<void> {\n    const ids = await this.readIndex();\n    const next = ids.filter((id) => id !== interruptId);\n\n    if (next.length === ids.length) {\n      return;\n    }\n\n    const client = await this.client();\n    await client.set(this.indexKey(), JSON.stringify(next));\n  }\n\n  /**\n   * Key for a single interrupt record — `<prefix><interruptId>`.\n   */\n  private recordKey(interruptId: string): string {\n    return `${this.prefix}${interruptId}`;\n  }\n\n  /**\n   * Key for the self-maintained id index — `<prefix>index`.\n   */\n  private indexKey(): string {\n    return `${this.prefix}${INDEX_SUFFIX}`;\n  }\n}\n\n/**\n * Create a Redis-backed {@link InterruptStore}. Either pass a connected\n * `redis` client (`{ client }`) — `@warlock.js/ai` never imports\n * `redis` in that case — or a `{ url }` and let the store lazily\n * `import(\"redis\")`, build, and connect a client. When `redis` is not\n * installed, the curated install string surfaces on first use, never at\n * import. {@link InterruptStore.schema} returns an empty string; Redis\n * needs no migration.\n *\n * @example\n * import { createClient } from \"redis\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const client = createClient({ url: process.env.REDIS_URL });\n * await client.connect();\n *\n * const store = ai.human.interrupt.redis({ client });\n *\n * @example\n * // Let the store build + connect its own client from a url:\n * const store = ai.human.interrupt.redis({ url: process.env.REDIS_URL });\n */\nexport function redis(options: RedisInterruptOptions): InterruptStore {\n  return new RedisInterruptStore(options);\n}\n"],"mappings":"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"}
+{"version":3,"file":"redis.mjs","names":[],"sources":["../../../../../../../../ai/src/human/stores/redis.ts"],"sourcesContent":["import type {\n  InterruptStore,\n  PendingInterrupt,\n  RedisClientLike,\n} from \"../contracts/interrupt-store.contract\";\n\n/**\n * Options for the Redis {@link InterruptStore}.\n *\n * Two mutually-supportive ways to supply the connection:\n * - **`client`** — pass an already-connected `redis` client (anything\n *   satisfying {@link RedisClientLike}). The store only calls\n *   `get` / `set` / `del` and never connects or quits it.\n * - **`url`** — let the store lazily `import(\"redis\")`, build a client\n *   from the url, and connect it. `@warlock.js/ai` takes **no** hard\n *   dependency on `redis` (it is an optional peer); when it is absent the\n *   store throws a curated install string at first use, never a raw\n *   module-resolution stack trace at import.\n *\n * Exactly one of the two must be present.\n */\nexport interface RedisInterruptOptions {\n  /** An already-connected `redis` client — anything matching {@link RedisClientLike}. */\n  client?: RedisClientLike;\n\n  /** Connection url the store passes to a lazily-imported `createClient`. */\n  url?: string;\n\n  /**\n   * Key prefix prepended to every key this store writes. Lets one Redis\n   * database back multiple stores without collision. Defaults to\n   * `warlock:ai-human:interrupt:`.\n   */\n  prefix?: string;\n}\n\n/**\n * Default key prefix — namespaces the store's keys inside a shared Redis\n * database so interrupt records coexist with other data without collision.\n */\nconst DEFAULT_PREFIX = \"warlock:ai-human:interrupt:\";\n\n/**\n * Index key (under the configured prefix) holding the JSON array of live\n * interrupt ids. The structural {@link RedisClientLike} surface exposes no\n * `SCAN` / `KEYS`, so enumeration for `list()` is self-maintained.\n */\nconst INDEX_SUFFIX = \"index\";\n\n/**\n * Module specifier for the optional `redis` driver. Held in a `string`\n * variable so the dynamic `import()` is not statically resolved at compile\n * time — `redis` is an optional peer that need not be installed for this\n * package to type-check or for a memory-only consumer to run.\n */\nconst REDIS_MODULE = \"redis\";\n\n/**\n * Curated install string surfaced (at use time) when a `url` is configured\n * but the optional `redis` driver is absent. Never thrown at import — a\n * memory-only consumer must be able to load this module.\n */\nconst REDIS_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai Redis interrupt store requires the redis package.\nInstall it with:\n\n  npm install redis\n\nOr with your preferred package manager:\n\n  pnpm add redis\n  yarn add redis\n`.trim();\n\n/**\n * Minimal structural view of the `redis` module surface — just enough to\n * build and connect a client from a url. Declared locally (rather than\n * `typeof import(\"redis\")`) so this module type-checks even when `redis`\n * is not installed.\n */\ninterface RedisModuleLike {\n  createClient(config: {\n    url: string;\n  }): RedisClientLike & { connect(): Promise<unknown> };\n}\n\n/**\n * Lazily import `redis`, build a client from `url`, and connect it. A bare\n * `catch` rethrows the curated install string — a missing optional peer\n * surfaces as actionable guidance, never a raw resolution error.\n */\nasync function buildRedisClient(url: string): Promise<RedisClientLike> {\n  let sdk: RedisModuleLike;\n\n  try {\n    sdk = (await import(REDIS_MODULE)) as unknown as RedisModuleLike;\n  } catch {\n    throw new Error(REDIS_INSTALL_INSTRUCTIONS);\n  }\n\n  const client = sdk.createClient({ url });\n  await client.connect();\n\n  return client;\n}\n\n/**\n * Redis-backed {@link InterruptStore} — one JSON string value per pending\n * interrupt, under a namespaced key, plus a self-maintained id index so\n * `list()` works without `SCAN`/`KEYS`.\n *\n * Owns: durable round-tripping of the {@link PendingInterrupt} envelope so\n * a reviewer can rule out-of-process, the namespaced key layout, and the\n * per-store id index that backs enumeration. Does NOT own: durability\n * guarantees beyond Redis's own, the connection lifecycle (a dev-supplied\n * client is never disconnected; a store-built client from a `url` is left\n * connected for the process to reuse), or migration —\n * {@link RedisInterruptStore.schema} returns an empty string.\n *\n * A call has exactly one live interrupt, so `save()` overwrites the key.\n *\n * Front it with the {@link redis} factory — callers never `new` it.\n */\nclass RedisInterruptStore implements InterruptStore {\n  /** Key prefix namespacing every key this store writes. */\n  private readonly prefix: string;\n\n  /**\n   * A ready client, or a promise resolving to one the store builds lazily\n   * from a `url`. Resolved once and memoized so the optional `redis`\n   * import + connect happens at most once.\n   */\n  private clientPromise: Promise<RedisClientLike>;\n\n  public constructor(options: RedisInterruptOptions) {\n    this.prefix = options.prefix ?? DEFAULT_PREFIX;\n\n    if (options.client) {\n      if (\n        typeof options.client.get !== \"function\" ||\n        typeof options.client.set !== \"function\" ||\n        typeof options.client.del !== \"function\"\n      ) {\n        throw new TypeError(\n          \"ai.human.interrupt.redis requires a 'client' option implementing { get, set, del } — pass a connected redis client.\",\n        );\n      }\n\n      this.clientPromise = Promise.resolve(options.client);\n\n      return;\n    }\n\n    if (options.url) {\n      // Defer the optional `redis` import to first use — a curated install\n      // string surfaces from `buildRedisClient`, not at construction.\n      this.clientPromise = buildRedisClient(options.url);\n\n      return;\n    }\n\n    throw new TypeError(\n      \"ai.human.interrupt.redis requires either a 'client' or a 'url' option.\",\n    );\n  }\n\n  /**\n   * Resolve the backing client, surfacing the lazy `redis` import's\n   * curated install string on the first call that needs it.\n   */\n  private client(): Promise<RedisClientLike> {\n    return this.clientPromise;\n  }\n\n  /**\n   * Persist a pending interrupt, keyed by its own `interruptId`, and index\n   * the id for enumeration. Overwrites any prior record for the same id —\n   * a call has exactly one live interrupt.\n   */\n  public async save(record: PendingInterrupt): Promise<void> {\n    const client = await this.client();\n\n    await client.set(this.recordKey(record.interruptId), JSON.stringify(record));\n    await this.indexId(record.interruptId);\n  }\n\n  /**\n   * Load the interrupt for an `interruptId`, or `undefined` when the key is\n   * missing. Redis returns `null` for an absent key — converted to\n   * `undefined` at the boundary.\n   */\n  public async load(\n    interruptId: string,\n  ): Promise<PendingInterrupt | undefined> {\n    const client = await this.client();\n    const raw = await client.get(this.recordKey(interruptId));\n\n    if (raw === null) {\n      return undefined;\n    }\n\n    return JSON.parse(raw) as PendingInterrupt;\n  }\n\n  /**\n   * Drop the interrupt for an `interruptId` and de-index its id. Idempotent\n   * — deleting an absent id is a no-op.\n   */\n  public async delete(interruptId: string): Promise<void> {\n    const client = await this.client();\n\n    await client.del(this.recordKey(interruptId));\n    await this.deindexId(interruptId);\n  }\n\n  /**\n   * List the interrupt ids known to the store, optionally filtered by a\n   * prefix. Reads the self-maintained index document.\n   */\n  public async list(prefix?: string): Promise<string[]> {\n    const ids = await this.readIndex();\n\n    if (prefix === undefined) {\n      return ids;\n    }\n\n    return ids.filter((id) => id.startsWith(prefix));\n  }\n\n  /**\n   * Redis needs no relational table — there is nothing to migrate. Returns\n   * an empty string so callers can treat `schema()` uniformly across\n   * drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n\n  /**\n   * Read and parse the id index, defaulting to an empty list when absent.\n   */\n  private async readIndex(): Promise<string[]> {\n    const client = await this.client();\n    const raw = await client.get(this.indexKey());\n\n    if (raw === null) {\n      return [];\n    }\n\n    return JSON.parse(raw) as string[];\n  }\n\n  /**\n   * Add an interrupt id to the index, no-op when already present.\n   */\n  private async indexId(interruptId: string): Promise<void> {\n    const ids = await this.readIndex();\n\n    if (ids.includes(interruptId)) {\n      return;\n    }\n\n    ids.push(interruptId);\n\n    const client = await this.client();\n    await client.set(this.indexKey(), JSON.stringify(ids));\n  }\n\n  /**\n   * Remove an interrupt id from the index, no-op when absent.\n   */\n  private async deindexId(interruptId: string): Promise<void> {\n    const ids = await this.readIndex();\n    const next = ids.filter((id) => id !== interruptId);\n\n    if (next.length === ids.length) {\n      return;\n    }\n\n    const client = await this.client();\n    await client.set(this.indexKey(), JSON.stringify(next));\n  }\n\n  /**\n   * Key for a single interrupt record — `<prefix><interruptId>`.\n   */\n  private recordKey(interruptId: string): string {\n    return `${this.prefix}${interruptId}`;\n  }\n\n  /**\n   * Key for the self-maintained id index — `<prefix>index`.\n   */\n  private indexKey(): string {\n    return `${this.prefix}${INDEX_SUFFIX}`;\n  }\n}\n\n/**\n * Create a Redis-backed {@link InterruptStore}. Either pass a connected\n * `redis` client (`{ client }`) — `@warlock.js/ai` never imports\n * `redis` in that case — or a `{ url }` and let the store lazily\n * `import(\"redis\")`, build, and connect a client. When `redis` is not\n * installed, the curated install string surfaces on first use, never at\n * import. {@link InterruptStore.schema} returns an empty string; Redis\n * needs no migration.\n *\n * @example\n * import { createClient } from \"redis\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const client = createClient({ url: process.env.REDIS_URL });\n * await client.connect();\n *\n * const store = ai.human.interrupt.redis({ client });\n *\n * @example\n * // Let the store build + connect its own client from a url:\n * const store = ai.human.interrupt.redis({ url: process.env.REDIS_URL });\n */\nexport function redis(options: RedisInterruptOptions): InterruptStore {\n  return new RedisInterruptStore(options);\n}\n"],"mappings":"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"}

package/esm/image/image-cost.d.mts

@@ -2,7 +2,7 @@ import { ModelPricing } from "../contracts/result/model-pricing.type.mjs";
 import { Usage } from "../contracts/result/usage.type.mjs";
 import { ImageModelPricing } from "../contracts/image-model.contract.mjs";
 
-//#region ../@warlock.js/ai/src/image/image-cost.d.ts
+//#region ../ai/src/image/image-cost.d.ts
 /**
  * Price one image-generation `Usage` against an
  * {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD

package/esm/image/image-cost.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"image-cost.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image-cost.ts"],"mappings":";;;;;;;AA4BA;;;;;;;;;;;;;;;;AAKe;;;;;iBALC,gBAAA,CACd,KAAA,EAAO,KAAA,EACP,UAAA,UACA,IAAA,sBACA,OAAA,EAAS,iBAAA,eACR,YAAA"}
+{"version":3,"file":"image-cost.d.mts","names":[],"sources":["../../../../../../../ai/src/image/image-cost.ts"],"mappings":";;;;;;;AA4BA;;;;;;;;;;;;;;;;AAKe;;;;;iBALC,gBAAA,CACd,KAAA,EAAO,KAAA,EACP,UAAA,UACA,IAAA,sBACA,OAAA,EAAS,iBAAA,eACR,YAAA"}

package/esm/image/image-cost.mjs

@@ -1,6 +1,6 @@
 import { computeCost } from "../utils/compute-cost.mjs";
 
-//#region ../@warlock.js/ai/src/image/image-cost.ts
+//#region ../ai/src/image/image-cost.ts
 /**
 * Price one image-generation `Usage` against an
 * {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD

package/esm/image/image-cost.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"image-cost.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image-cost.ts"],"sourcesContent":["import type { ImageModelPricing } from \"../contracts/image-model.contract\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { computeCost } from \"../utils/compute-cost\";\n\n/**\n * Price one image-generation `Usage` against an\n * {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD\n * breakdown so image spend folds into the exact same `Usage.cost`\n * rollup the text path uses (`accumulateCost` / `mergeUsage`). There is\n * no separate image-cost field anywhere downstream — only this one\n * function, which knows the two metering models:\n *\n * - **Per-image** (DALL·E, Imagen): `perImageBySize[size]` (when the\n *   request `size` matches a tier) else flat `perImage`, times the\n *   number of images returned, attributed to `cost.output` (the image\n *   IS the output). Token channels stay 0.\n * - **Token** (gpt-image-1): delegates to the standard\n *   {@link computeCost} against the prompt/image token `Usage`.\n *\n * Per-image wins when both shapes are configured (a provider is one or\n * the other). Returns `undefined` when no usable pricing is present —\n * the framework treats that as \"cost unknown\", never a false zero.\n *\n * @example\n * computeImageCost({ input: 0, output: 0, total: 0 }, 2, \"1024x1024\", { perImage: 0.04 });\n * // → { input: 0, output: 0.08 }\n */\nexport function computeImageCost(\n  usage: Usage,\n  imageCount: number,\n  size: string | undefined,\n  pricing: ImageModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  const perImageMetered = pricing.perImage !== undefined || pricing.perImageBySize !== undefined;\n\n  if (perImageMetered) {\n    const perImage = resolvePerImageRate(size, pricing);\n\n    if (perImage === undefined) {\n      return undefined;\n    }\n\n    return { input: 0, output: perImage * imageCount };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve the USD-per-image rate: a `perImageBySize` tier matching the\n * requested `size` wins, otherwise the flat `perImage`. Returns\n * `undefined` only when neither is set (the caller already gated on\n * per-image metering being configured at all).\n */\nfunction resolvePerImageRate(\n  size: string | undefined,\n  pricing: ImageModelPricing,\n): number | undefined {\n  if (size !== undefined && pricing.perImageBySize?.[size] !== undefined) {\n    return pricing.perImageBySize[size];\n  }\n\n  return pricing.perImage;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iBACd,OACA,YACA,MACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAKF,IAFwB,QAAQ,aAAa,UAAa,QAAQ,mBAAmB,QAEhE;EACnB,MAAM,WAAW,oBAAoB,MAAM,OAAO;EAElD,IAAI,aAAa,QACf;EAGF,OAAO;GAAE,OAAO;GAAG,QAAQ,WAAW;EAAW;CACnD;CAEA,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;;;;;;AAQA,SAAS,oBACP,MACA,SACoB;CACpB,IAAI,SAAS,UAAa,QAAQ,iBAAiB,UAAU,QAC3D,OAAO,QAAQ,eAAe;CAGhC,OAAO,QAAQ;AACjB"}
+{"version":3,"file":"image-cost.mjs","names":[],"sources":["../../../../../../../ai/src/image/image-cost.ts"],"sourcesContent":["import type { ImageModelPricing } from \"../contracts/image-model.contract\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { computeCost } from \"../utils/compute-cost\";\n\n/**\n * Price one image-generation `Usage` against an\n * {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD\n * breakdown so image spend folds into the exact same `Usage.cost`\n * rollup the text path uses (`accumulateCost` / `mergeUsage`). There is\n * no separate image-cost field anywhere downstream — only this one\n * function, which knows the two metering models:\n *\n * - **Per-image** (DALL·E, Imagen): `perImageBySize[size]` (when the\n *   request `size` matches a tier) else flat `perImage`, times the\n *   number of images returned, attributed to `cost.output` (the image\n *   IS the output). Token channels stay 0.\n * - **Token** (gpt-image-1): delegates to the standard\n *   {@link computeCost} against the prompt/image token `Usage`.\n *\n * Per-image wins when both shapes are configured (a provider is one or\n * the other). Returns `undefined` when no usable pricing is present —\n * the framework treats that as \"cost unknown\", never a false zero.\n *\n * @example\n * computeImageCost({ input: 0, output: 0, total: 0 }, 2, \"1024x1024\", { perImage: 0.04 });\n * // → { input: 0, output: 0.08 }\n */\nexport function computeImageCost(\n  usage: Usage,\n  imageCount: number,\n  size: string | undefined,\n  pricing: ImageModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  const perImageMetered = pricing.perImage !== undefined || pricing.perImageBySize !== undefined;\n\n  if (perImageMetered) {\n    const perImage = resolvePerImageRate(size, pricing);\n\n    if (perImage === undefined) {\n      return undefined;\n    }\n\n    return { input: 0, output: perImage * imageCount };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve the USD-per-image rate: a `perImageBySize` tier matching the\n * requested `size` wins, otherwise the flat `perImage`. Returns\n * `undefined` only when neither is set (the caller already gated on\n * per-image metering being configured at all).\n */\nfunction resolvePerImageRate(\n  size: string | undefined,\n  pricing: ImageModelPricing,\n): number | undefined {\n  if (size !== undefined && pricing.perImageBySize?.[size] !== undefined) {\n    return pricing.perImageBySize[size];\n  }\n\n  return pricing.perImage;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iBACd,OACA,YACA,MACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAKF,IAFwB,QAAQ,aAAa,UAAa,QAAQ,mBAAmB,QAEhE;EACnB,MAAM,WAAW,oBAAoB,MAAM,OAAO;EAElD,IAAI,aAAa,QACf;EAGF,OAAO;GAAE,OAAO;GAAG,QAAQ,WAAW;EAAW;CACnD;CAEA,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;;;;;;AAQA,SAAS,oBACP,MACA,SACoB;CACpB,IAAI,SAAS,UAAa,QAAQ,iBAAiB,UAAU,QAC3D,OAAO,QAAQ,eAAe;CAGhC,OAAO,QAAQ;AACjB"}

package/esm/image/image.d.mts

@@ -3,7 +3,7 @@ import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
 import { FlowObserveOption } from "../observe/resolve-observers.mjs";
 import { GeneratedImage, ImageModelContract } from "../contracts/image-model.contract.mjs";
 
-//#region ../@warlock.js/ai/src/image/image.d.ts
+//#region ../ai/src/image/image.d.ts
 /**
  * Parameters for {@link image}. `model` comes from an adapter's
  * `image()` factory (`openai.image({ name })` / `google.image({ name })`);

package/esm/image/image.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image.ts"],"mappings":";;;;;;;;AAsBA;;;;KAAY,WAAA;EAyBA,gEAvBV,KAAA,EAAO,kBAAA,EA6BS;EA3BhB,MAAA,UAFA;EAIA,KAAA,WAFA;EAIA,IAAA;EAEA,OAAA,WAEA;EAAA,WAAA,WAIA;EAFA,cAAA,WAIS;EAFT,MAAA,WASU;EAPV,MAAA,GAAS,WAAA;EAWT;;;;AAEgB;AAIlB;EAVE,OAAA,GAAU,iBAAA;EAEV,SAAA,WAUsB;EARtB,IAAA,WAiBqB;EAfrB,OAAA,GAAU,MAAA;AAAA;;KAIA,SAAA;EAcV,mEAZA,MAAA,EAAQ,cAAc;AAAA;;;AAcZ;AAQZ;;;KAbY,WAAA,GAAc,UAAU;EAClC,IAAA,WAcQ;EAZR,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA,GAWvB;EATA,UAAA;AAAA;;AAUmB;AA+BrB;;;KAjCY,WAAA,GAAc,aAAA,CAAc,SAAA;EACtC,IAAA;EACA,MAAA,EAAQ,WAAA;AAAA;;;;;;;AA+B2D;;;;;;;;;;;;;;;;;;;;;;iBAA/C,KAAA,CAAM,MAAA,EAAQ,WAAA,GAAc,OAAA,CAAQ,WAAA"}
+{"version":3,"file":"image.d.mts","names":[],"sources":["../../../../../../../ai/src/image/image.ts"],"mappings":";;;;;;;;AAsBA;;;;KAAY,WAAA;EAyBA,gEAvBV,KAAA,EAAO,kBAAA,EA6BS;EA3BhB,MAAA,UAFA;EAIA,KAAA,WAFA;EAIA,IAAA;EAEA,OAAA,WAEA;EAAA,WAAA,WAIA;EAFA,cAAA,WAIS;EAFT,MAAA,WASU;EAPV,MAAA,GAAS,WAAA;EAWT;;;;AAEgB;AAIlB;EAVE,OAAA,GAAU,iBAAA;EAEV,SAAA,WAUsB;EARtB,IAAA,WAiBqB;EAfrB,OAAA,GAAU,MAAA;AAAA;;KAIA,SAAA;EAcV,mEAZA,MAAA,EAAQ,cAAc;AAAA;;;AAcZ;AAQZ;;;KAbY,WAAA,GAAc,UAAU;EAClC,IAAA,WAcQ;EAZR,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA,GAWvB;EATA,UAAA;AAAA;;AAUmB;AA+BrB;;;KAjCY,WAAA,GAAc,aAAA,CAAc,SAAA;EACtC,IAAA;EACA,MAAA,EAAQ,WAAA;AAAA;;;;;;;AA+B2D;;;;;;;;;;;;;;;;;;;;;;iBAA/C,KAAA,CAAM,MAAA,EAAQ,WAAA,GAAc,OAAA,CAAQ,WAAA"}

package/esm/image/image.mjs

@@ -6,7 +6,7 @@ import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
 import { notifyObservers } from "../observe/resolve-observers.mjs";
 import { computeImageCost } from "./image-cost.mjs";
 
-//#region ../@warlock.js/ai/src/image/image.ts
+//#region ../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

package/esm/image/image.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"image.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image.ts"],"sourcesContent":["import type {\n  GeneratedImage,\n  ImageModelContract,\n} from \"../contracts/image-model.contract\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\nimport { computeImageCost } from \"./image-cost\";\n\n/**\n * Parameters for {@link image}. `model` comes from an adapter's\n * `image()` factory (`openai.image({ name })` / `google.image({ name })`);\n * the rest are provider-neutral generation knobs plus the standard\n * observability seam every verb shares.\n */\nexport type ImageParams = {\n  /** The image model to generate from (`sdk.image({ name })`). */\n  model: ImageModelContract;\n  /** Text description of the image(s) to generate. */\n  prompt: string;\n  /** How many images to generate. Adapters clamp to the provider max. */\n  count?: number;\n  /** Requested pixel size as `\"WxH\"` (e.g. `\"1024x1024\"`). */\n  size?: string;\n  /** Quality tier (e.g. `\"standard\"` / `\"hd\"`). */\n  quality?: string;\n  /** Aspect ratio (e.g. `\"1:1\"`, `\"16:9\"`) — ratio-based providers (Imagen). */\n  aspectRatio?: string;\n  /** Concepts to steer away from (Imagen `negativePrompt`). */\n  negativePrompt?: string;\n  /** Output container hint (`\"png\"` / `\"jpeg\"` / `\"webp\"`). */\n  format?: string;\n  /** Cancellation handle, wired into the provider request where supported. */\n  signal?: AbortSignal;\n  /**\n   * Observability routing for this call — same `observe` seam as\n   * agents / workflows. `true` routes to the globally registered\n   * observers; an `Observer` object routes flow-locally; `false` opts\n   * out; omitted follows the global observe-all flag.\n   */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"image\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of an {@link image} run. */\nexport type ImageData = {\n  /** The generated images, normalized to the discriminated shape. */\n  images: GeneratedImage[];\n};\n\n/**\n * The report node an {@link image} run produces — a {@link BaseReport}\n * (`type: \"image\"`) plus which model ran and how many images came back,\n * so panoptic and any flat-row consumer attribute the cost/latency\n * without special-casing.\n */\nexport type ImageReport = BaseReport & {\n  type: \"image\";\n  /** Identity of the image model this run used. */\n  model: { name: string; provider: string };\n  /** Number of images returned (0 on failure). */\n  imageCount: number;\n};\n\n/**\n * Result envelope of {@link image} — the same uniform\n * `{ data, error, usage, report }` every executable returns, narrowed\n * with the `\"image\"` discriminant.\n */\nexport type ImageResult = ExecuteResult<ImageData> & {\n  type: \"image\";\n  report: ImageReport;\n};\n\n/**\n * Generate one or more images from a text prompt — the image-output\n * counterpart to `ai.agent`, and the first verb of the output-modality\n * track (Theme I). Wraps an {@link ImageModelContract} (from\n * `openai.image(...)` / `google.image(...)`) in the framework's uniform\n * result contract:\n *\n * - **Never throws.** Provider failures (auth, rate-limit,\n *   content-filter, invalid request) surface as a typed `AIError` on\n *   `result.error`; `result.data` is then `undefined`.\n * - **Cost-truth.** When the model carries pricing, `result.usage.cost`\n *   is filled in — per-token for gpt-image-1, per-image for\n *   DALL·E / Imagen — folding into the same `Usage.cost` rollup as text.\n * - **Observable.** The completed {@link ImageReport} routes to any\n *   registered `Observer` (panoptic, OTel, …) via the shared `observe`\n *   seam, exactly like an agent run.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error, usage } = await ai.image({\n *   model: openai.image({ name: \"gpt-image-1\" }),\n *   prompt: \"an isometric office desk, soft studio lighting\",\n *   size: \"1024x1024\",\n * });\n *\n * if (error) console.warn(error.code);\n * else for (const img of data.images) save(img); // { type: \"base64\" | \"url\", ... }\n */\nexport async function image(params: ImageParams): Promise<ImageResult> {\n  const { model, prompt } = params;\n\n  const runId = generateRunId(\"image\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: ImageData | undefined;\n  let error: AIError | undefined;\n  let status: ImageReport[\"status\"] = \"completed\";\n  let imageCount = 0;\n\n  try {\n    const response = await model.generate(prompt, {\n      count: params.count,\n      size: params.size,\n      quality: params.quality,\n      aspectRatio: params.aspectRatio,\n      negativePrompt: params.negativePrompt,\n      format: params.format,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    // Preserve every usage channel the adapter reported (cached /\n    // reasoning / cache-write, and any adapter-supplied `cost`), mirroring\n    // how the agent path routes provider usage. Then honor a pre-priced\n    // response or compute image cost — `usage.cost ??= …` precedence, same\n    // as the agent path.\n    Object.assign(usage, response.usage);\n\n    if (usage.cost === undefined) {\n      const cost = computeImageCost(usage, response.images.length, params.size, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { images: response.images };\n    imageCount = response.images.length;\n  } catch (thrown) {\n    error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    // A caller-aborted run is \"cancelled\", not \"failed\" — keep the typed\n    // cause but distinguish the terminal status for dashboards/retry policy.\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: ImageReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"image\",\n    type: \"image\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    imageCount,\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"image\", data, error, usage, report };\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkHA,eAAsB,MAAM,QAA2C;CACrE,MAAM,EAAE,OAAO,WAAW;CAE1B,MAAM,QAAQ,cAAc,OAAO;CACnC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAgC;CACpC,IAAI,aAAa;CAEjB,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,SAAS,QAAQ;GAC5C,OAAO,OAAO;GACd,MAAM,OAAO;GACb,SAAS,OAAO;GAChB,aAAa,OAAO;GACpB,gBAAgB,OAAO;GACvB,QAAQ,OAAO;GACf,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAOD,OAAO,OAAO,OAAO,SAAS,KAAK;EAEnC,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,iBAAiB,OAAO,SAAS,OAAO,QAAQ,OAAO,MAAM,MAAM,OAAO;GACvF,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO,EAAE,QAAQ,SAAS,OAAO;EACjC,aAAa,SAAS,OAAO;CAC/B,SAAS,QAAQ;EACf,QAAQ,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAGnG,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAAsB;EAC1B;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD;EACA;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAS;EAAM;EAAO;EAAO;CAAO;AACrD;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}
+{"version":3,"file":"image.mjs","names":[],"sources":["../../../../../../../ai/src/image/image.ts"],"sourcesContent":["import type {\n  GeneratedImage,\n  ImageModelContract,\n} from \"../contracts/image-model.contract\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\nimport { computeImageCost } from \"./image-cost\";\n\n/**\n * Parameters for {@link image}. `model` comes from an adapter's\n * `image()` factory (`openai.image({ name })` / `google.image({ name })`);\n * the rest are provider-neutral generation knobs plus the standard\n * observability seam every verb shares.\n */\nexport type ImageParams = {\n  /** The image model to generate from (`sdk.image({ name })`). */\n  model: ImageModelContract;\n  /** Text description of the image(s) to generate. */\n  prompt: string;\n  /** How many images to generate. Adapters clamp to the provider max. */\n  count?: number;\n  /** Requested pixel size as `\"WxH\"` (e.g. `\"1024x1024\"`). */\n  size?: string;\n  /** Quality tier (e.g. `\"standard\"` / `\"hd\"`). */\n  quality?: string;\n  /** Aspect ratio (e.g. `\"1:1\"`, `\"16:9\"`) — ratio-based providers (Imagen). */\n  aspectRatio?: string;\n  /** Concepts to steer away from (Imagen `negativePrompt`). */\n  negativePrompt?: string;\n  /** Output container hint (`\"png\"` / `\"jpeg\"` / `\"webp\"`). */\n  format?: string;\n  /** Cancellation handle, wired into the provider request where supported. */\n  signal?: AbortSignal;\n  /**\n   * Observability routing for this call — same `observe` seam as\n   * agents / workflows. `true` routes to the globally registered\n   * observers; an `Observer` object routes flow-locally; `false` opts\n   * out; omitted follows the global observe-all flag.\n   */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"image\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of an {@link image} run. */\nexport type ImageData = {\n  /** The generated images, normalized to the discriminated shape. */\n  images: GeneratedImage[];\n};\n\n/**\n * The report node an {@link image} run produces — a {@link BaseReport}\n * (`type: \"image\"`) plus which model ran and how many images came back,\n * so panoptic and any flat-row consumer attribute the cost/latency\n * without special-casing.\n */\nexport type ImageReport = BaseReport & {\n  type: \"image\";\n  /** Identity of the image model this run used. */\n  model: { name: string; provider: string };\n  /** Number of images returned (0 on failure). */\n  imageCount: number;\n};\n\n/**\n * Result envelope of {@link image} — the same uniform\n * `{ data, error, usage, report }` every executable returns, narrowed\n * with the `\"image\"` discriminant.\n */\nexport type ImageResult = ExecuteResult<ImageData> & {\n  type: \"image\";\n  report: ImageReport;\n};\n\n/**\n * Generate one or more images from a text prompt — the image-output\n * counterpart to `ai.agent`, and the first verb of the output-modality\n * track (Theme I). Wraps an {@link ImageModelContract} (from\n * `openai.image(...)` / `google.image(...)`) in the framework's uniform\n * result contract:\n *\n * - **Never throws.** Provider failures (auth, rate-limit,\n *   content-filter, invalid request) surface as a typed `AIError` on\n *   `result.error`; `result.data` is then `undefined`.\n * - **Cost-truth.** When the model carries pricing, `result.usage.cost`\n *   is filled in — per-token for gpt-image-1, per-image for\n *   DALL·E / Imagen — folding into the same `Usage.cost` rollup as text.\n * - **Observable.** The completed {@link ImageReport} routes to any\n *   registered `Observer` (panoptic, OTel, …) via the shared `observe`\n *   seam, exactly like an agent run.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error, usage } = await ai.image({\n *   model: openai.image({ name: \"gpt-image-1\" }),\n *   prompt: \"an isometric office desk, soft studio lighting\",\n *   size: \"1024x1024\",\n * });\n *\n * if (error) console.warn(error.code);\n * else for (const img of data.images) save(img); // { type: \"base64\" | \"url\", ... }\n */\nexport async function image(params: ImageParams): Promise<ImageResult> {\n  const { model, prompt } = params;\n\n  const runId = generateRunId(\"image\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: ImageData | undefined;\n  let error: AIError | undefined;\n  let status: ImageReport[\"status\"] = \"completed\";\n  let imageCount = 0;\n\n  try {\n    const response = await model.generate(prompt, {\n      count: params.count,\n      size: params.size,\n      quality: params.quality,\n      aspectRatio: params.aspectRatio,\n      negativePrompt: params.negativePrompt,\n      format: params.format,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    // Preserve every usage channel the adapter reported (cached /\n    // reasoning / cache-write, and any adapter-supplied `cost`), mirroring\n    // how the agent path routes provider usage. Then honor a pre-priced\n    // response or compute image cost — `usage.cost ??= …` precedence, same\n    // as the agent path.\n    Object.assign(usage, response.usage);\n\n    if (usage.cost === undefined) {\n      const cost = computeImageCost(usage, response.images.length, params.size, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { images: response.images };\n    imageCount = response.images.length;\n  } catch (thrown) {\n    error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    // A caller-aborted run is \"cancelled\", not \"failed\" — keep the typed\n    // cause but distinguish the terminal status for dashboards/retry policy.\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: ImageReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"image\",\n    type: \"image\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    imageCount,\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"image\", data, error, usage, report };\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkHA,eAAsB,MAAM,QAA2C;CACrE,MAAM,EAAE,OAAO,WAAW;CAE1B,MAAM,QAAQ,cAAc,OAAO;CACnC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAgC;CACpC,IAAI,aAAa;CAEjB,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,SAAS,QAAQ;GAC5C,OAAO,OAAO;GACd,MAAM,OAAO;GACb,SAAS,OAAO;GAChB,aAAa,OAAO;GACpB,gBAAgB,OAAO;GACvB,QAAQ,OAAO;GACf,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAOD,OAAO,OAAO,OAAO,SAAS,KAAK;EAEnC,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,iBAAiB,OAAO,SAAS,OAAO,QAAQ,OAAO,MAAM,MAAM,OAAO;GACvF,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO,EAAE,QAAQ,SAAS,OAAO;EACjC,aAAa,SAAS,OAAO;CAC/B,SAAS,QAAQ;EACf,QAAQ,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAGnG,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAAsB;EAC1B;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD;EACA;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAS;EAAM;EAAO;EAAO;CAAO;AACrD;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}

package/esm/memory/derive-id.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/memory/derive-id.ts
+//#region ../ai/src/memory/derive-id.ts
 /**
 * Derive a stable memory id from its text when the caller didn't supply
 * one. Re-remembering identical text therefore lands on the same id and

package/esm/memory/derive-id.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"derive-id.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/derive-id.ts"],"sourcesContent":["/**\n * Derive a stable memory id from its text when the caller didn't supply\n * one. Re-remembering identical text therefore lands on the same id and\n * overwrites in place rather than duplicating.\n *\n * FNV-1a variant — cheap, dependency-free, collision-resistant enough\n * for de-duplicating memory entries. NOT cryptographic: a collision\n * would merge two distinct memories, not breach security in the current\n * trust model. Mirrors the prompt hash in\n * `middleware/builtins/semantic-cache.ts`.\n */\nexport function deriveMemoryId(text: string): string {\n  let hash = 0x811c9dc5;\n\n  for (let index = 0; index < text.length; index++) {\n    hash ^= text.charCodeAt(index);\n    hash = Math.imul(hash, 0x01000193);\n  }\n\n  return (hash >>> 0).toString(16);\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAgB,eAAe,MAAsB;CACnD,IAAI,OAAO;CAEX,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS;EAChD,QAAQ,KAAK,WAAW,KAAK;EAC7B,OAAO,KAAK,KAAK,MAAM,QAAU;CACnC;CAEA,QAAQ,SAAS,EAAC,CAAE,SAAS,EAAE;AACjC"}
+{"version":3,"file":"derive-id.mjs","names":[],"sources":["../../../../../../../ai/src/memory/derive-id.ts"],"sourcesContent":["/**\n * Derive a stable memory id from its text when the caller didn't supply\n * one. Re-remembering identical text therefore lands on the same id and\n * overwrites in place rather than duplicating.\n *\n * FNV-1a variant — cheap, dependency-free, collision-resistant enough\n * for de-duplicating memory entries. NOT cryptographic: a collision\n * would merge two distinct memories, not breach security in the current\n * trust model. Mirrors the prompt hash in\n * `middleware/builtins/semantic-cache.ts`.\n */\nexport function deriveMemoryId(text: string): string {\n  let hash = 0x811c9dc5;\n\n  for (let index = 0; index < text.length; index++) {\n    hash ^= text.charCodeAt(index);\n    hash = Math.imul(hash, 0x01000193);\n  }\n\n  return (hash >>> 0).toString(16);\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAgB,eAAe,MAAsB;CACnD,IAAI,OAAO;CAEX,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS;EAChD,QAAQ,KAAK,WAAW,KAAK;EAC7B,OAAO,KAAK,KAAK,MAAM,QAAU;CACnC;CAEA,QAAQ,SAAS,EAAC,CAAE,SAAS,EAAE;AACjC"}

package/esm/memory/episodic-memory.mjs

@@ -1,6 +1,6 @@
 import { deriveMemoryId } from "./derive-id.mjs";
 
-//#region ../@warlock.js/ai/src/memory/episodic-memory.ts
+//#region ../ai/src/memory/episodic-memory.ts
 /**
 * How many extra candidates to pull from `similar()` before re-ranking by
 * the recency-blended score and slicing to `k`. Recency can promote a

package/esm/memory/episodic-memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"episodic-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/episodic-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per episode. `ts` is the wall-clock time the episode\n * was remembered — the basis for the recency half of the blended recall\n * score. The vector lives in the driver's index (via `set({ vector })`),\n * so it is not duplicated here.\n */\ntype StoredEpisode = {\n  id: string;\n  text: string;\n  ts: number;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * How many extra candidates to pull from `similar()` before re-ranking by\n * the recency-blended score and slicing to `k`. Recency can promote a\n * slightly-less-similar-but-recent episode past a stale exact match, so\n * the raw top-`k` by similarity alone would miss it — overscan, then\n * re-rank.\n */\nconst RECALL_OVERSCAN = 5;\n\n/**\n * Episodic recall tier (memory core M2).\n *\n * Holds a durable, timestamped log of *what happened* — events/episodes —\n * and retrieves the ones most relevant to a query, **blended with\n * recency** so recent episodes outrank stale ones at equal similarity.\n * That recency weighting is the whole difference from the {@link\n * import(\"./semantic-memory\").SemanticMemory} tier (pure similarity over\n * timeless facts): episodic memory is time-anchored.\n *\n * Like the semantic tier it delegates the similarity search to the\n * `@warlock.js/cache` driver's `similar()` and never implements ANN\n * itself; it adds a stored `ts` per entry and a decay curve at recall.\n * The blended `score` stays in `[0, 1]` so a consumer can merge episodic\n * hits with the other tiers and sort on one field.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class EpisodicMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n    private readonly recencyWeight: number,\n    private readonly halfLifeMs: number,\n    private readonly now: () => number,\n  ) {}\n\n  /**\n   * Embed the episode text and index it under a namespaced, id-derived\n   * key, stamping the current time. Re-remembering the same id overwrites\n   * the prior entry (and refreshes its timestamp).\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const value: StoredEpisode = {\n      id,\n      text: item.text,\n      ts: this.now(),\n      metadata: item.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, pull the nearest episodes clearing the similarity\n   * `threshold`, then re-rank each by a recency-blended score before\n   * returning the top `k`. The similarity floor still gates relevance —\n   * recency only reorders episodes that already cleared it, it never\n   * surfaces an irrelevant-but-recent one.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredEpisode>(vector, {\n      topK: Math.max(k * RECALL_OVERSCAN, k),\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n    const now = this.now();\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredEpisode>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredEpisode>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"episodic\" as const,\n        score: this.blend(hit.score, hit.value.ts, now),\n        metadata: hit.value.metadata,\n      }))\n      .sort((first, second) => second.score - first.score)\n      .slice(0, k);\n  }\n\n  /** Drop every episode written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Combine raw similarity with an exponential recency decay:\n   * `(1 - w)·similarity + w·0.5^(age / halfLife)`. A just-remembered\n   * episode contributes a recency of `1`; one `halfLife` old, `0.5`;\n   * older trends toward `0`. With `recencyWeight` 0 the score is pure\n   * similarity (an opt-out back to semantic-style ranking).\n   */\n  private blend(similarity: number, ts: number, now: number): number {\n    const ageMs = Math.max(0, now - ts);\n    const recency = 0.5 ** (ageMs / this.halfLifeMs);\n\n    return (1 - this.recencyWeight) * similarity + this.recencyWeight * recency;\n  }\n\n  /**\n   * Namespaced key for an entry. Mirrors the semantic tier's dot\n   * separator so the prefix used here matches the `hit.key` the driver\n   * returns from `similar()`.\n   */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;;AA4BA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqBxB,IAAa,iBAAb,MAA4B;CAC1B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB,AAAiB,eACjB,AAAiB,YACjB,AAAiB,KACjB;EANiB;EACA;EACA;EACA;EACA;EACA;CAChB;;;;;;CAOH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,QAAuB;GAC3B;GACA,MAAM,KAAK;GACX,IAAI,KAAK,IAAI;GACb,UAAU,KAAK;EACjB;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;;CASA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAuB,QAAQ;GAC3D,MAAM,KAAK,IAAI,IAAI,iBAAiB,CAAC;GACrC;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EACjC,MAAM,MAAM,KAAK,IAAI;EAErB,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAAyC;GAC7C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,KAAK,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI,GAAG;GAC9C,UAAU,IAAI,MAAM;EACtB,EAAE,CAAC,CACF,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK,CAAC,CACnD,MAAM,GAAG,CAAC;CACf;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;;;CASA,AAAQ,MAAM,YAAoB,IAAY,KAAqB;EAEjE,MAAM,UAAU,OADF,KAAK,IAAI,GAAG,MAAM,EACJ,IAAI,KAAK;EAErC,QAAQ,IAAI,KAAK,iBAAiB,aAAa,KAAK,gBAAgB;CACtE;;;;;;CAOA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}
+{"version":3,"file":"episodic-memory.mjs","names":[],"sources":["../../../../../../../ai/src/memory/episodic-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per episode. `ts` is the wall-clock time the episode\n * was remembered — the basis for the recency half of the blended recall\n * score. The vector lives in the driver's index (via `set({ vector })`),\n * so it is not duplicated here.\n */\ntype StoredEpisode = {\n  id: string;\n  text: string;\n  ts: number;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * How many extra candidates to pull from `similar()` before re-ranking by\n * the recency-blended score and slicing to `k`. Recency can promote a\n * slightly-less-similar-but-recent episode past a stale exact match, so\n * the raw top-`k` by similarity alone would miss it — overscan, then\n * re-rank.\n */\nconst RECALL_OVERSCAN = 5;\n\n/**\n * Episodic recall tier (memory core M2).\n *\n * Holds a durable, timestamped log of *what happened* — events/episodes —\n * and retrieves the ones most relevant to a query, **blended with\n * recency** so recent episodes outrank stale ones at equal similarity.\n * That recency weighting is the whole difference from the {@link\n * import(\"./semantic-memory\").SemanticMemory} tier (pure similarity over\n * timeless facts): episodic memory is time-anchored.\n *\n * Like the semantic tier it delegates the similarity search to the\n * `@warlock.js/cache` driver's `similar()` and never implements ANN\n * itself; it adds a stored `ts` per entry and a decay curve at recall.\n * The blended `score` stays in `[0, 1]` so a consumer can merge episodic\n * hits with the other tiers and sort on one field.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class EpisodicMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n    private readonly recencyWeight: number,\n    private readonly halfLifeMs: number,\n    private readonly now: () => number,\n  ) {}\n\n  /**\n   * Embed the episode text and index it under a namespaced, id-derived\n   * key, stamping the current time. Re-remembering the same id overwrites\n   * the prior entry (and refreshes its timestamp).\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const value: StoredEpisode = {\n      id,\n      text: item.text,\n      ts: this.now(),\n      metadata: item.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, pull the nearest episodes clearing the similarity\n   * `threshold`, then re-rank each by a recency-blended score before\n   * returning the top `k`. The similarity floor still gates relevance —\n   * recency only reorders episodes that already cleared it, it never\n   * surfaces an irrelevant-but-recent one.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredEpisode>(vector, {\n      topK: Math.max(k * RECALL_OVERSCAN, k),\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n    const now = this.now();\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredEpisode>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredEpisode>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"episodic\" as const,\n        score: this.blend(hit.score, hit.value.ts, now),\n        metadata: hit.value.metadata,\n      }))\n      .sort((first, second) => second.score - first.score)\n      .slice(0, k);\n  }\n\n  /** Drop every episode written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Combine raw similarity with an exponential recency decay:\n   * `(1 - w)·similarity + w·0.5^(age / halfLife)`. A just-remembered\n   * episode contributes a recency of `1`; one `halfLife` old, `0.5`;\n   * older trends toward `0`. With `recencyWeight` 0 the score is pure\n   * similarity (an opt-out back to semantic-style ranking).\n   */\n  private blend(similarity: number, ts: number, now: number): number {\n    const ageMs = Math.max(0, now - ts);\n    const recency = 0.5 ** (ageMs / this.halfLifeMs);\n\n    return (1 - this.recencyWeight) * similarity + this.recencyWeight * recency;\n  }\n\n  /**\n   * Namespaced key for an entry. Mirrors the semantic tier's dot\n   * separator so the prefix used here matches the `hit.key` the driver\n   * returns from `similar()`.\n   */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;;AA4BA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqBxB,IAAa,iBAAb,MAA4B;CAC1B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB,AAAiB,eACjB,AAAiB,YACjB,AAAiB,KACjB;EANiB;EACA;EACA;EACA;EACA;EACA;CAChB;;;;;;CAOH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,QAAuB;GAC3B;GACA,MAAM,KAAK;GACX,IAAI,KAAK,IAAI;GACb,UAAU,KAAK;EACjB;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;;CASA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAuB,QAAQ;GAC3D,MAAM,KAAK,IAAI,IAAI,iBAAiB,CAAC;GACrC;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EACjC,MAAM,MAAM,KAAK,IAAI;EAErB,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAAyC;GAC7C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,KAAK,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI,GAAG;GAC9C,UAAU,IAAI,MAAM;EACtB,EAAE,CAAC,CACF,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK,CAAC,CACnD,MAAM,GAAG,CAAC;CACf;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;;;CASA,AAAQ,MAAM,YAAoB,IAAY,KAAqB;EAEjE,MAAM,UAAU,OADF,KAAK,IAAI,GAAG,MAAM,EACJ,IAAI,KAAK;EAErC,QAAQ,IAAI,KAAK,iBAAiB,aAAa,KAAK,gBAAgB;CACtE;;;;;;CAOA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}

package/esm/memory/memory.d.mts

@@ -1,7 +1,7 @@
 import { MemoryContract } from "../contracts/memory/memory.contract.mjs";
 import { MemoryConfig } from "../contracts/memory/memory-config.type.mjs";
 
-//#region ../@warlock.js/ai/src/memory/memory.d.ts
+//#region ../ai/src/memory/memory.d.ts
 /**
  * Create an agent memory store (memory core M2).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/memory.ts"],"mappings":";;;;;;AA0DA;;;;;;;;AAAiE;;;;;;;;;;;;;;;;;;;;;;;;iBAAjD,MAAA,CAAO,MAAA,GAAQ,YAAA,GAAoB,cAAc"}
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../ai/src/memory/memory.ts"],"mappings":";;;;;;AA0DA;;;;;;;;AAAiE;;;;;;;;;;;;;;;;;;;;;;;;iBAAjD,MAAA,CAAO,MAAA,GAAQ,YAAA,GAAoB,cAAc"}

package/esm/memory/memory.mjs

@@ -4,7 +4,7 @@ import { ProceduralMemory } from "./procedural-memory.mjs";
 import { SemanticMemory } from "./semantic-memory.mjs";
 import { WorkingMemory } from "./working-memory.mjs";
 
-//#region ../@warlock.js/ai/src/memory/memory.ts
+//#region ../ai/src/memory/memory.ts
 const DEFAULT_NAME = "memory";
 const DEFAULT_SEMANTIC_NAMESPACE = "ai.memory.semantic";
 const DEFAULT_EPISODIC_NAMESPACE = "ai.memory.episodic";

package/esm/memory/memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/memory.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { MemoryConfig } from \"../contracts/memory/memory-config.type\";\nimport type {\n  MemoryItem,\n  MemoryTier,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type { RecallOptions } from \"../contracts/memory/recall-options.type\";\nimport { EpisodicMemory } from \"./episodic-memory\";\nimport { ProceduralMemory } from \"./procedural-memory\";\nimport { SemanticMemory } from \"./semantic-memory\";\nimport { WorkingMemory } from \"./working-memory\";\n\nconst DEFAULT_NAME = \"memory\";\nconst DEFAULT_SEMANTIC_NAMESPACE = \"ai.memory.semantic\";\nconst DEFAULT_EPISODIC_NAMESPACE = \"ai.memory.episodic\";\nconst DEFAULT_PROCEDURAL_NAMESPACE = \"ai.memory.procedural\";\nconst DEFAULT_K = 5;\nconst DEFAULT_THRESHOLD = 0.7;\nconst DEFAULT_RECENCY_WEIGHT = 0.3;\nconst DEFAULT_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;\nconst DEFAULT_REINFORCEMENT_WEIGHT = 0.3;\n\n/**\n * Create an agent memory store (memory core M2).\n *\n * Wires up to four tiers behind the {@link MemoryContract}: **working**\n * (in-run scratch, recency), **semantic** (durable facts by cosine\n * similarity), **episodic** (durable events, similarity blended with\n * recency), and **procedural** (durable how-tos, similarity blended with\n * reinforcement). The working tier is on by default; the other three each\n * activate only when their config is supplied. The three vector tiers\n * mirror how `semanticCache` delegates similarity to the cache driver's\n * `.similar()`.\n *\n * Resolution happens once here, at construction (loud), rather than per\n * call (silent until first use): a vector-tier config with no `store` and\n * no `ai.config({ defaultStore })` throws now; enabling no tier at all\n * throws now.\n *\n * Decay / forgetting (TTL-based falloff, eviction) remains deferred.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const mem = ai.memory({\n *   semantic: { embedder, store },\n *   defaultTier: \"semantic\",\n * });\n *\n * await mem.remember({ text: \"User prefers concise answers.\" });\n * const hits = await mem.recall(\"how should I respond?\", { k: 3 });\n */\nexport function memory(config: MemoryConfig = {}): MemoryContract {\n  const name = config.name ?? DEFAULT_NAME;\n  const workingEnabled = config.working ?? true;\n  const defaultK = config.k ?? DEFAULT_K;\n  const defaultThreshold = config.threshold ?? DEFAULT_THRESHOLD;\n\n  const working = workingEnabled ? new WorkingMemory() : undefined;\n\n  const semantic = config.semantic\n    ? buildSemanticTier(config.semantic, name)\n    : undefined;\n\n  const episodic = config.episodic\n    ? buildEpisodicTier(config.episodic, name)\n    : undefined;\n\n  const procedural = config.procedural\n    ? buildProceduralTier(config.procedural, name)\n    : undefined;\n\n  const tiers: Tiers = { working, semantic, episodic, procedural };\n\n  if (!working && !semantic && !episodic && !procedural) {\n    throw new Error(\n      `memory(\"${name}\"): no tier enabled — enable \\`working\\` (default) or pass a \\`semantic\\` / \\`episodic\\` / \\`procedural\\` config; a memory with no tiers can neither store nor recall`,\n    );\n  }\n\n  const defaultTier: MemoryTier = config.defaultTier ?? \"working\";\n\n  assertTierEnabled(defaultTier, tiers, name);\n\n  return {\n    name,\n    async remember(items: MemoryItem | MemoryItem[]): Promise<void> {\n      const list = Array.isArray(items) ? items : [items];\n\n      const writes: Promise<void>[] = [];\n\n      for (const item of list) {\n        const tier = item.tier ?? defaultTier;\n\n        assertTierEnabled(tier, tiers, name);\n\n        if (tier === \"working\") {\n          working!.remember(item);\n\n          continue;\n        }\n\n        if (tier === \"semantic\") {\n          writes.push(semantic!.remember(item));\n\n          continue;\n        }\n\n        if (tier === \"episodic\") {\n          writes.push(episodic!.remember(item));\n\n          continue;\n        }\n\n        writes.push(procedural!.remember(item));\n      }\n\n      await Promise.all(writes);\n    },\n    async recall(\n      query: string,\n      options: RecallOptions = {},\n    ): Promise<RecalledMemory[]> {\n      const k = options.k ?? defaultK;\n      const threshold = options.threshold ?? defaultThreshold;\n\n      if (options.tier) {\n        assertTierEnabled(options.tier, tiers, name);\n      }\n\n      const wants = (tier: MemoryTier): boolean =>\n        !options.tier || options.tier === tier;\n\n      const [workingHits, semanticHits, episodicHits, proceduralHits] =\n        await Promise.all([\n          working && wants(\"working\")\n            ? Promise.resolve(working.recall(k))\n            : Promise.resolve([] as RecalledMemory[]),\n          semantic && wants(\"semantic\")\n            ? semantic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          episodic && wants(\"episodic\")\n            ? episodic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          procedural && wants(\"procedural\")\n            ? procedural.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n        ]);\n\n      return [\n        ...workingHits,\n        ...semanticHits,\n        ...episodicHits,\n        ...proceduralHits,\n      ]\n        .sort((first, second) => second.score - first.score)\n        .slice(0, k);\n    },\n    async clear(tier?: MemoryTier): Promise<void> {\n      const clears: Promise<void>[] = [];\n\n      if (working && (!tier || tier === \"working\")) {\n        working.clear();\n      }\n\n      if (semantic && (!tier || tier === \"semantic\")) {\n        clears.push(semantic.clear());\n      }\n\n      if (episodic && (!tier || tier === \"episodic\")) {\n        clears.push(episodic.clear());\n      }\n\n      if (procedural && (!tier || tier === \"procedural\")) {\n        clears.push(procedural.clear());\n      }\n\n      await Promise.all(clears);\n    },\n  };\n}\n\n/** The four tier instances a `memory()` composes; `undefined` when off. */\ntype Tiers = {\n  working: WorkingMemory | undefined;\n  semantic: SemanticMemory | undefined;\n  episodic: EpisodicMemory | undefined;\n  procedural: ProceduralMemory | undefined;\n};\n\n/**\n * Resolve the semantic tier's store (explicit `store` wins, else the\n * global `ai.config({ defaultStore })`) and build the tier. Throws at\n * construction when neither is available — the same loud-now contract\n * `semanticCache` follows.\n */\nfunction buildSemanticTier(\n  semanticConfig: NonNullable<MemoryConfig[\"semantic\"]>,\n  name: string,\n): SemanticMemory {\n  const store = semanticConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier has no store — pass \\`semantic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new SemanticMemory(\n    semanticConfig.embedder,\n    store,\n    semanticConfig.namespace ?? DEFAULT_SEMANTIC_NAMESPACE,\n  );\n}\n\n/**\n * Resolve the episodic tier's store (explicit `store` wins, else the\n * global default) and build the tier with its recency knobs. Throws at\n * construction when neither store is available — the same loud-now\n * contract the semantic tier follows.\n */\nfunction buildEpisodicTier(\n  episodicConfig: NonNullable<MemoryConfig[\"episodic\"]>,\n  name: string,\n): EpisodicMemory {\n  const store = episodicConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier has no store — pass \\`episodic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new EpisodicMemory(\n    episodicConfig.embedder,\n    store,\n    episodicConfig.namespace ?? DEFAULT_EPISODIC_NAMESPACE,\n    episodicConfig.recencyWeight ?? DEFAULT_RECENCY_WEIGHT,\n    episodicConfig.halfLifeMs ?? DEFAULT_HALF_LIFE_MS,\n    episodicConfig.now ?? (() => Date.now()),\n  );\n}\n\n/**\n * Resolve the procedural tier's store and build the tier with its\n * reinforcement knob. Throws at construction when no store is available.\n */\nfunction buildProceduralTier(\n  proceduralConfig: NonNullable<MemoryConfig[\"procedural\"]>,\n  name: string,\n): ProceduralMemory {\n  const store = proceduralConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier has no store — pass \\`procedural.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new ProceduralMemory(\n    proceduralConfig.embedder,\n    store,\n    proceduralConfig.namespace ?? DEFAULT_PROCEDURAL_NAMESPACE,\n    proceduralConfig.reinforcementWeight ?? DEFAULT_REINFORCEMENT_WEIGHT,\n  );\n}\n\n/**\n * Guard that a tier referenced by config / a call is actually enabled,\n * failing fast with an actionable message instead of a downstream\n * `undefined` dereference.\n */\nfunction assertTierEnabled(tier: MemoryTier, tiers: Tiers, name: string): void {\n  if (tier === \"working\" && !tiers.working) {\n    throw new Error(\n      `memory(\"${name}\"): working tier is disabled — set \\`working: true\\` (the default) to use it`,\n    );\n  }\n\n  if (tier === \"semantic\" && !tiers.semantic) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier is not configured — pass \\`semantic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"episodic\" && !tiers.episodic) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier is not configured — pass \\`episodic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"procedural\" && !tiers.procedural) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier is not configured — pass \\`procedural\\` config to use it`,\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../ai/src/memory/memory.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { MemoryConfig } from \"../contracts/memory/memory-config.type\";\nimport type {\n  MemoryItem,\n  MemoryTier,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type { RecallOptions } from \"../contracts/memory/recall-options.type\";\nimport { EpisodicMemory } from \"./episodic-memory\";\nimport { ProceduralMemory } from \"./procedural-memory\";\nimport { SemanticMemory } from \"./semantic-memory\";\nimport { WorkingMemory } from \"./working-memory\";\n\nconst DEFAULT_NAME = \"memory\";\nconst DEFAULT_SEMANTIC_NAMESPACE = \"ai.memory.semantic\";\nconst DEFAULT_EPISODIC_NAMESPACE = \"ai.memory.episodic\";\nconst DEFAULT_PROCEDURAL_NAMESPACE = \"ai.memory.procedural\";\nconst DEFAULT_K = 5;\nconst DEFAULT_THRESHOLD = 0.7;\nconst DEFAULT_RECENCY_WEIGHT = 0.3;\nconst DEFAULT_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;\nconst DEFAULT_REINFORCEMENT_WEIGHT = 0.3;\n\n/**\n * Create an agent memory store (memory core M2).\n *\n * Wires up to four tiers behind the {@link MemoryContract}: **working**\n * (in-run scratch, recency), **semantic** (durable facts by cosine\n * similarity), **episodic** (durable events, similarity blended with\n * recency), and **procedural** (durable how-tos, similarity blended with\n * reinforcement). The working tier is on by default; the other three each\n * activate only when their config is supplied. The three vector tiers\n * mirror how `semanticCache` delegates similarity to the cache driver's\n * `.similar()`.\n *\n * Resolution happens once here, at construction (loud), rather than per\n * call (silent until first use): a vector-tier config with no `store` and\n * no `ai.config({ defaultStore })` throws now; enabling no tier at all\n * throws now.\n *\n * Decay / forgetting (TTL-based falloff, eviction) remains deferred.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const mem = ai.memory({\n *   semantic: { embedder, store },\n *   defaultTier: \"semantic\",\n * });\n *\n * await mem.remember({ text: \"User prefers concise answers.\" });\n * const hits = await mem.recall(\"how should I respond?\", { k: 3 });\n */\nexport function memory(config: MemoryConfig = {}): MemoryContract {\n  const name = config.name ?? DEFAULT_NAME;\n  const workingEnabled = config.working ?? true;\n  const defaultK = config.k ?? DEFAULT_K;\n  const defaultThreshold = config.threshold ?? DEFAULT_THRESHOLD;\n\n  const working = workingEnabled ? new WorkingMemory() : undefined;\n\n  const semantic = config.semantic\n    ? buildSemanticTier(config.semantic, name)\n    : undefined;\n\n  const episodic = config.episodic\n    ? buildEpisodicTier(config.episodic, name)\n    : undefined;\n\n  const procedural = config.procedural\n    ? buildProceduralTier(config.procedural, name)\n    : undefined;\n\n  const tiers: Tiers = { working, semantic, episodic, procedural };\n\n  if (!working && !semantic && !episodic && !procedural) {\n    throw new Error(\n      `memory(\"${name}\"): no tier enabled — enable \\`working\\` (default) or pass a \\`semantic\\` / \\`episodic\\` / \\`procedural\\` config; a memory with no tiers can neither store nor recall`,\n    );\n  }\n\n  const defaultTier: MemoryTier = config.defaultTier ?? \"working\";\n\n  assertTierEnabled(defaultTier, tiers, name);\n\n  return {\n    name,\n    async remember(items: MemoryItem | MemoryItem[]): Promise<void> {\n      const list = Array.isArray(items) ? items : [items];\n\n      const writes: Promise<void>[] = [];\n\n      for (const item of list) {\n        const tier = item.tier ?? defaultTier;\n\n        assertTierEnabled(tier, tiers, name);\n\n        if (tier === \"working\") {\n          working!.remember(item);\n\n          continue;\n        }\n\n        if (tier === \"semantic\") {\n          writes.push(semantic!.remember(item));\n\n          continue;\n        }\n\n        if (tier === \"episodic\") {\n          writes.push(episodic!.remember(item));\n\n          continue;\n        }\n\n        writes.push(procedural!.remember(item));\n      }\n\n      await Promise.all(writes);\n    },\n    async recall(\n      query: string,\n      options: RecallOptions = {},\n    ): Promise<RecalledMemory[]> {\n      const k = options.k ?? defaultK;\n      const threshold = options.threshold ?? defaultThreshold;\n\n      if (options.tier) {\n        assertTierEnabled(options.tier, tiers, name);\n      }\n\n      const wants = (tier: MemoryTier): boolean =>\n        !options.tier || options.tier === tier;\n\n      const [workingHits, semanticHits, episodicHits, proceduralHits] =\n        await Promise.all([\n          working && wants(\"working\")\n            ? Promise.resolve(working.recall(k))\n            : Promise.resolve([] as RecalledMemory[]),\n          semantic && wants(\"semantic\")\n            ? semantic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          episodic && wants(\"episodic\")\n            ? episodic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          procedural && wants(\"procedural\")\n            ? procedural.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n        ]);\n\n      return [\n        ...workingHits,\n        ...semanticHits,\n        ...episodicHits,\n        ...proceduralHits,\n      ]\n        .sort((first, second) => second.score - first.score)\n        .slice(0, k);\n    },\n    async clear(tier?: MemoryTier): Promise<void> {\n      const clears: Promise<void>[] = [];\n\n      if (working && (!tier || tier === \"working\")) {\n        working.clear();\n      }\n\n      if (semantic && (!tier || tier === \"semantic\")) {\n        clears.push(semantic.clear());\n      }\n\n      if (episodic && (!tier || tier === \"episodic\")) {\n        clears.push(episodic.clear());\n      }\n\n      if (procedural && (!tier || tier === \"procedural\")) {\n        clears.push(procedural.clear());\n      }\n\n      await Promise.all(clears);\n    },\n  };\n}\n\n/** The four tier instances a `memory()` composes; `undefined` when off. */\ntype Tiers = {\n  working: WorkingMemory | undefined;\n  semantic: SemanticMemory | undefined;\n  episodic: EpisodicMemory | undefined;\n  procedural: ProceduralMemory | undefined;\n};\n\n/**\n * Resolve the semantic tier's store (explicit `store` wins, else the\n * global `ai.config({ defaultStore })`) and build the tier. Throws at\n * construction when neither is available — the same loud-now contract\n * `semanticCache` follows.\n */\nfunction buildSemanticTier(\n  semanticConfig: NonNullable<MemoryConfig[\"semantic\"]>,\n  name: string,\n): SemanticMemory {\n  const store = semanticConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier has no store — pass \\`semantic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new SemanticMemory(\n    semanticConfig.embedder,\n    store,\n    semanticConfig.namespace ?? DEFAULT_SEMANTIC_NAMESPACE,\n  );\n}\n\n/**\n * Resolve the episodic tier's store (explicit `store` wins, else the\n * global default) and build the tier with its recency knobs. Throws at\n * construction when neither store is available — the same loud-now\n * contract the semantic tier follows.\n */\nfunction buildEpisodicTier(\n  episodicConfig: NonNullable<MemoryConfig[\"episodic\"]>,\n  name: string,\n): EpisodicMemory {\n  const store = episodicConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier has no store — pass \\`episodic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new EpisodicMemory(\n    episodicConfig.embedder,\n    store,\n    episodicConfig.namespace ?? DEFAULT_EPISODIC_NAMESPACE,\n    episodicConfig.recencyWeight ?? DEFAULT_RECENCY_WEIGHT,\n    episodicConfig.halfLifeMs ?? DEFAULT_HALF_LIFE_MS,\n    episodicConfig.now ?? (() => Date.now()),\n  );\n}\n\n/**\n * Resolve the procedural tier's store and build the tier with its\n * reinforcement knob. Throws at construction when no store is available.\n */\nfunction buildProceduralTier(\n  proceduralConfig: NonNullable<MemoryConfig[\"procedural\"]>,\n  name: string,\n): ProceduralMemory {\n  const store = proceduralConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier has no store — pass \\`procedural.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new ProceduralMemory(\n    proceduralConfig.embedder,\n    store,\n    proceduralConfig.namespace ?? DEFAULT_PROCEDURAL_NAMESPACE,\n    proceduralConfig.reinforcementWeight ?? DEFAULT_REINFORCEMENT_WEIGHT,\n  );\n}\n\n/**\n * Guard that a tier referenced by config / a call is actually enabled,\n * failing fast with an actionable message instead of a downstream\n * `undefined` dereference.\n */\nfunction assertTierEnabled(tier: MemoryTier, tiers: Tiers, name: string): void {\n  if (tier === \"working\" && !tiers.working) {\n    throw new Error(\n      `memory(\"${name}\"): working tier is disabled — set \\`working: true\\` (the default) to use it`,\n    );\n  }\n\n  if (tier === \"semantic\" && !tiers.semantic) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier is not configured — pass \\`semantic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"episodic\" && !tiers.episodic) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier is not configured — pass \\`episodic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"procedural\" && !tiers.procedural) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier is not configured — pass \\`procedural\\` config to use it`,\n    );\n  }\n}\n"],"mappings":"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"}