@warlock.js/ai 4.8.2 → 4.9.1

package/esm/agent/judge-config.type.d.mts

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/agent/judge-config.type.d.ts
+//#region ../ai/src/agent/judge-config.type.d.ts
 /**
  * Default number of repair re-asks the judge preset performs when the
  * model's first verdict fails to parse / validate. Two attempts balances

package/esm/agent/judge-config.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"judge-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/judge-config.type.ts"],"mappings":";;AAOA;;;;AAA0C;AAa1C;cAba,6BAAA;;;AAqBG;;;;;;;;;KARJ,WAAA;;;;;;;;EAQV,cAAc;AAAA"}
+{"version":3,"file":"judge-config.type.d.mts","names":[],"sources":["../../../../../../../ai/src/agent/judge-config.type.ts"],"mappings":";;AAOA;;;;AAA0C;AAa1C;cAba,6BAAA;;;AAqBG;;;;;;;;;KARJ,WAAA;;;;;;;;EAQV,cAAc;AAAA"}

package/esm/agent/judge-config.type.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/agent/judge-config.type.ts
+//#region ../ai/src/agent/judge-config.type.ts
 /**
 * Default number of repair re-asks the judge preset performs when the
 * model's first verdict fails to parse / validate. Two attempts balances

package/esm/agent/judge-config.type.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"judge-config.type.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/judge-config.type.ts"],"sourcesContent":["/**\n * Default number of repair re-asks the judge preset performs when the\n * model's first verdict fails to parse / validate. Two attempts balances\n * resilience against latency — a corrupted-JSON judge usually recovers on\n * the first re-ask, and a model that still can't comply after two tries is\n * unlikely to on a third.\n */\nexport const JUDGE_DEFAULT_REPAIR_ATTEMPTS = 2;\n\n/**\n * Fine-grained configuration for the judge-safe agent preset. The boolean\n * shorthand (`judge: true`) is equivalent to `judge: {}` — every field\n * below falls back to its resilient default.\n *\n * The preset targets structured-output *judges* (LLM-as-judge graders,\n * verdict classifiers) running on models that emit malformed JSON under\n * load — notably the Amazon Nova family, which wraps verdicts in fenced\n * blocks, prepends prose, or trails commentary. It trades strictness for\n * resilience (see {@link AgentConfig.judge}).\n */\nexport type JudgeConfig = {\n  /**\n   * How many repair re-asks to perform when the verdict fails to parse or\n   * validate. Defaults to {@link JUDGE_DEFAULT_REPAIR_ATTEMPTS}. Still\n   * bounded by the agent's `maxTrips` cap, so a stuck model can never loop\n   * forever. Set `0` to disable repair while keeping the lenient parser and\n   * never-throw guarantee.\n   */\n  repairAttempts?: number;\n};\n"],"mappings":";;;;;;;;AAOA,MAAa,gCAAgC"}
+{"version":3,"file":"judge-config.type.mjs","names":[],"sources":["../../../../../../../ai/src/agent/judge-config.type.ts"],"sourcesContent":["/**\n * Default number of repair re-asks the judge preset performs when the\n * model's first verdict fails to parse / validate. Two attempts balances\n * resilience against latency — a corrupted-JSON judge usually recovers on\n * the first re-ask, and a model that still can't comply after two tries is\n * unlikely to on a third.\n */\nexport const JUDGE_DEFAULT_REPAIR_ATTEMPTS = 2;\n\n/**\n * Fine-grained configuration for the judge-safe agent preset. The boolean\n * shorthand (`judge: true`) is equivalent to `judge: {}` — every field\n * below falls back to its resilient default.\n *\n * The preset targets structured-output *judges* (LLM-as-judge graders,\n * verdict classifiers) running on models that emit malformed JSON under\n * load — notably the Amazon Nova family, which wraps verdicts in fenced\n * blocks, prepends prose, or trails commentary. It trades strictness for\n * resilience (see {@link AgentConfig.judge}).\n */\nexport type JudgeConfig = {\n  /**\n   * How many repair re-asks to perform when the verdict fails to parse or\n   * validate. Defaults to {@link JUDGE_DEFAULT_REPAIR_ATTEMPTS}. Still\n   * bounded by the agent's `maxTrips` cap, so a stuck model can never loop\n   * forever. Set `0` to disable repair while keeping the lenient parser and\n   * never-throw guarantee.\n   */\n  repairAttempts?: number;\n};\n"],"mappings":";;;;;;;;AAOA,MAAa,gCAAgC"}

package/esm/agent/signature.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/agent/signature.ts
+//#region ../ai/src/agent/signature.ts
 /**
 * Deterministic structural fingerprint of an agent definition.
 * Persisted on every durable snapshot so `agent.resume()` can detect

package/esm/agent/signature.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"signature.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/signature.ts"],"sourcesContent":["import type { AgentConfig } from \"./agent-config.type\";\n\n/**\n * Deterministic structural fingerprint of an agent definition.\n * Persisted on every durable snapshot so `agent.resume()` can detect\n * drift between the saved run and the current definition. Covers the\n * fields whose change would make a mid-run resume unsafe — i.e. would\n * make the persisted `messages` / `toolCalls` array inconsistent with\n * what the resumed trip loop would produce:\n *\n * - Model name + provider — a different model invalidates the prior\n *   conversation's continuation.\n * - The sorted tool names — adding / removing / renaming a tool changes\n *   which dispatches the persisted `toolCalls` could have come from.\n * - `maxTrips` — the loop bound is a semantic shape change.\n * - Whether a default `output` schema is configured — flips the\n *   structured-output instruction baked into the system turn.\n * - `version` — dev-curated; a bump is an explicit \"this changed\" signal.\n *\n * Does NOT cover: system-prompt text, middleware, per-event handlers,\n * placeholders, modelOptions — runtime knobs that don't change the\n * shape of a resumable run. Mirrors `supervisor/signature.ts`'s coarse\n * structural philosophy and reuses its FNV-1a `hash`.\n *\n * `tools` here is read off the resolved config (post-normalization), so\n * raw executables dropped into `tools: []` are already adapted to\n * `ToolContract`s carrying a stable `name`.\n */\nexport function computeAgentSignature(config: {\n  name?: string;\n  version?: AgentConfig[\"version\"];\n  model: { name?: string; provider?: string };\n  tools?: ReadonlyArray<{ name: string }>;\n  maxTrips?: number;\n  output?: unknown;\n}): string {\n  const toolNames = (config.tools ?? [])\n    .map((tool) => tool.name)\n    .sort((a, b) => a.localeCompare(b));\n\n  const fingerprint = {\n    n: config.name ?? null,\n    p: config.model?.provider ?? null,\n    m: config.model?.name ?? null,\n    t: toolNames,\n    x: config.maxTrips ?? null,\n    o: config.output ? 1 : 0,\n    v: config.version ?? null,\n  };\n\n  return hash(JSON.stringify(fingerprint));\n}\n\n/**\n * FNV-1a 32-bit — the same hash `supervisor/signature.ts` and\n * `workflow/signature.ts` use. Deterministic, no crypto dependency,\n * cheap; signatures are 8-char hex.\n */\nfunction hash(input: string): string {\n  let h = 0x811c9dc5;\n\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n  }\n\n  return h.toString(16).padStart(8, \"0\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,sBAAsB,QAO3B;CACT,MAAM,aAAa,OAAO,SAAS,CAAC,EAAC,CAClC,KAAK,SAAS,KAAK,IAAI,CAAC,CACxB,MAAM,GAAG,MAAM,EAAE,cAAc,CAAC,CAAC;CAEpC,MAAM,cAAc;EAClB,GAAG,OAAO,QAAQ;EAClB,GAAG,OAAO,OAAO,YAAY;EAC7B,GAAG,OAAO,OAAO,QAAQ;EACzB,GAAG;EACH,GAAG,OAAO,YAAY;EACtB,GAAG,OAAO,SAAS,IAAI;EACvB,GAAG,OAAO,WAAW;CACvB;CAEA,OAAO,KAAK,KAAK,UAAU,WAAW,CAAC;AACzC;;;;;;AAOA,SAAS,KAAK,OAAuB;CACnC,IAAI,IAAI;CAER,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,KAAK,MAAM,WAAW,CAAC;EACvB,IAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,SAAU;CACxE;CAEA,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;AACvC"}
+{"version":3,"file":"signature.mjs","names":[],"sources":["../../../../../../../ai/src/agent/signature.ts"],"sourcesContent":["import type { AgentConfig } from \"./agent-config.type\";\n\n/**\n * Deterministic structural fingerprint of an agent definition.\n * Persisted on every durable snapshot so `agent.resume()` can detect\n * drift between the saved run and the current definition. Covers the\n * fields whose change would make a mid-run resume unsafe — i.e. would\n * make the persisted `messages` / `toolCalls` array inconsistent with\n * what the resumed trip loop would produce:\n *\n * - Model name + provider — a different model invalidates the prior\n *   conversation's continuation.\n * - The sorted tool names — adding / removing / renaming a tool changes\n *   which dispatches the persisted `toolCalls` could have come from.\n * - `maxTrips` — the loop bound is a semantic shape change.\n * - Whether a default `output` schema is configured — flips the\n *   structured-output instruction baked into the system turn.\n * - `version` — dev-curated; a bump is an explicit \"this changed\" signal.\n *\n * Does NOT cover: system-prompt text, middleware, per-event handlers,\n * placeholders, modelOptions — runtime knobs that don't change the\n * shape of a resumable run. Mirrors `supervisor/signature.ts`'s coarse\n * structural philosophy and reuses its FNV-1a `hash`.\n *\n * `tools` here is read off the resolved config (post-normalization), so\n * raw executables dropped into `tools: []` are already adapted to\n * `ToolContract`s carrying a stable `name`.\n */\nexport function computeAgentSignature(config: {\n  name?: string;\n  version?: AgentConfig[\"version\"];\n  model: { name?: string; provider?: string };\n  tools?: ReadonlyArray<{ name: string }>;\n  maxTrips?: number;\n  output?: unknown;\n}): string {\n  const toolNames = (config.tools ?? [])\n    .map((tool) => tool.name)\n    .sort((a, b) => a.localeCompare(b));\n\n  const fingerprint = {\n    n: config.name ?? null,\n    p: config.model?.provider ?? null,\n    m: config.model?.name ?? null,\n    t: toolNames,\n    x: config.maxTrips ?? null,\n    o: config.output ? 1 : 0,\n    v: config.version ?? null,\n  };\n\n  return hash(JSON.stringify(fingerprint));\n}\n\n/**\n * FNV-1a 32-bit — the same hash `supervisor/signature.ts` and\n * `workflow/signature.ts` use. Deterministic, no crypto dependency,\n * cheap; signatures are 8-char hex.\n */\nfunction hash(input: string): string {\n  let h = 0x811c9dc5;\n\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n  }\n\n  return h.toString(16).padStart(8, \"0\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,sBAAsB,QAO3B;CACT,MAAM,aAAa,OAAO,SAAS,CAAC,EAAC,CAClC,KAAK,SAAS,KAAK,IAAI,CAAC,CACxB,MAAM,GAAG,MAAM,EAAE,cAAc,CAAC,CAAC;CAEpC,MAAM,cAAc;EAClB,GAAG,OAAO,QAAQ;EAClB,GAAG,OAAO,OAAO,YAAY;EAC7B,GAAG,OAAO,OAAO,QAAQ;EACzB,GAAG;EACH,GAAG,OAAO,YAAY;EACtB,GAAG,OAAO,SAAS,IAAI;EACvB,GAAG,OAAO,WAAW;CACvB;CAEA,OAAO,KAAK,KAAK,UAAU,WAAW,CAAC;AACzC;;;;;;AAOA,SAAS,KAAK,OAAuB;CACnC,IAAI,IAAI;CAER,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,KAAK,MAAM,WAAW,CAAC;EACvB,IAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,SAAU;CACxE;CAEA,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;AACvC"}

package/esm/agent/snapshot.mjs

@@ -3,7 +3,7 @@ import { AgentDriftError } from "../errors/agent-drift-error.mjs";
 import "../errors/index.mjs";
 import { resolveDefaultSnapshotStore } from "../config.mjs";
 
-//#region ../@warlock.js/ai/src/agent/snapshot.ts
+//#region ../ai/src/agent/snapshot.ts
 /**
 * Resolve the effective {@link SnapshotStore}: the agent's own
 * `durable.store` wins; absent that, fall back to the global default

package/esm/agent/snapshot.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/snapshot.ts"],"sourcesContent":["import { resolveDefaultSnapshotStore } from \"../config\";\nimport type {\n  AgentResumeOptions,\n} from \"../contracts/agent/agent-options.type\";\nimport type {\n  AgentSnapshot,\n  AgentSnapshotStatus,\n} from \"../contracts/agent/agent-snapshot.type\";\nimport type { SnapshotStore } from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type { LLMTrip } from \"../contracts/result/llm-trip.type\";\nimport type { ToolCall } from \"../contracts/result/tool-call.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AgentDriftError, AgentExecutionError } from \"../errors\";\n\n/**\n * The agent's `durable` config, narrowed to the fields the snapshot\n * helpers read. Kept minimal so this module doesn't depend on the full\n * resolved-config shape.\n */\nexport type AgentDurableConfig = {\n  store?: SnapshotStore<AgentSnapshot>;\n  deleteOnComplete?: boolean;\n};\n\n/**\n * Resolve the effective {@link SnapshotStore}: the agent's own\n * `durable.store` wins; absent that, fall back to the global default\n * set via `ai.config({ defaultSnapshotStore })`.\n *\n * The global default is typed for the supervisor snapshot shape, but\n * every store impl keys purely by `runId` and round-trips whatever\n * envelope it is handed — so it serves an `AgentSnapshot` just as well.\n * The cast re-tags the shape at this single boundary (Option B); the\n * agent only ever hands it an `AgentSnapshot`.\n */\nfunction resolveSnapshotStore(\n  durable: AgentDurableConfig | undefined,\n): SnapshotStore<AgentSnapshot> | undefined {\n  return (\n    durable?.store ??\n    (resolveDefaultSnapshotStore() as SnapshotStore<AgentSnapshot> | undefined)\n  );\n}\n\nexport type PersistAgentParams = {\n  durable: AgentDurableConfig | undefined;\n  runId: string;\n  agentName: string;\n  signature: string;\n  version?: string;\n  input: string;\n  systemPrompt?: string;\n  responseSchema?: Record<string, unknown>;\n  promptName?: string;\n  promptVersion?: string;\n  messages: Message[];\n  trips: LLMTrip[];\n  toolCalls: ToolCall[];\n  usage: Usage;\n  status: AgentSnapshotStatus;\n  startedAt: string;\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run state to the resolved snapshot store. No-op\n * (returns `{ ok: true }`) when neither `durable.store` nor the global\n * `defaultSnapshotStore` is configured — the common non-durable path.\n * Failures are returned as `{ ok: false }` rather than thrown so the\n * engine can surface them via logs without aborting the run — a failed\n * checkpoint loses resume-ability from that point but never breaks an\n * otherwise-healthy run.\n */\nexport async function persistAgentSnapshot(\n  params: PersistAgentParams,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  const snapshot: AgentSnapshot = {\n    runId: params.runId,\n    agentName: params.agentName,\n    signature: params.signature,\n    version: params.version,\n    input: params.input,\n    systemPrompt: params.systemPrompt,\n    responseSchema: params.responseSchema,\n    promptName: params.promptName,\n    promptVersion: params.promptVersion,\n    messages: params.messages,\n    trips: params.trips,\n    toolCalls: params.toolCalls,\n    usage: params.usage,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.save(snapshot);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Delete a persisted snapshot — used after a successful run when\n * `durable.deleteOnComplete` is set. Never throws: a failed delete is\n * surfaced as `{ ok: false }` and the engine logs it. No-op (ok) when no\n * store is configured.\n */\nexport async function deleteAgentSnapshot(params: {\n  durable: AgentDurableConfig | undefined;\n  runId: string;\n}): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  try {\n    await store.delete(params.runId);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Load a persisted snapshot for `resume()` and run the drift check.\n * Throws `AgentExecutionError` when no store is configured or when the\n * run is missing; throws `AgentDriftError` when the stored signature\n * doesn't match the current definition (unless `force` is set).\n */\nexport async function loadAgentSnapshotForResume(params: {\n  durable: AgentDurableConfig | undefined;\n  agentName: string;\n  signature: string;\n  runId: string;\n  options?: AgentResumeOptions<unknown>;\n}): Promise<AgentSnapshot> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    throw new AgentExecutionError(\n      `agent \"${params.agentName}\" has no durable store configured — set \\`durable: { store }\\` on the config or call \\`ai.config({ defaultSnapshotStore })\\` at boot before calling resume()`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  const snapshot = (await store.load(params.runId)) ?? null;\n\n  if (!snapshot) {\n    throw new AgentExecutionError(\n      `agent \"${params.agentName}\": no snapshot for runId \"${params.runId}\"`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  if (!params.options?.force && snapshot.signature !== params.signature) {\n    throw new AgentDriftError(\n      `agent \"${params.agentName}\" signature drift on resume`,\n      {\n        savedSignature: snapshot.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snapshot;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAoCA,SAAS,qBACP,SAC0C;CAC1C,OACE,SAAS,SACR,4BAA4B;AAEjC;;;;;;;;;;AAgCA,eAAsB,qBACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,MAAM,WAA0B;EAC9B,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,OAAO,OAAO;EACd,cAAc,OAAO;EACrB,gBAAgB,OAAO;EACvB,YAAY,OAAO;EACnB,eAAe,OAAO;EACtB,UAAU,OAAO;EACjB,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,KAAK,QAAQ;EAEzB,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;AAQA,eAAsB,oBAAoB,QAGd;CAC1B,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,IAAI;EACF,MAAM,MAAM,OAAO,OAAO,KAAK;EAE/B,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;AAQA,eAAsB,2BAA2B,QAMtB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,MAAM,IAAI,oBACR,UAAU,OAAO,UAAU,+JAC3B,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,MAAM,WAAY,MAAM,MAAM,KAAK,OAAO,KAAK,KAAM;CAErD,IAAI,CAAC,UACH,MAAM,IAAI,oBACR,UAAU,OAAO,UAAU,4BAA4B,OAAO,MAAM,IACpE,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,cAAc,OAAO,WAC1D,MAAM,IAAI,gBACR,UAAU,OAAO,UAAU,8BAC3B;EACE,gBAAgB,SAAS;EACzB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT"}
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../../ai/src/agent/snapshot.ts"],"sourcesContent":["import { resolveDefaultSnapshotStore } from \"../config\";\nimport type {\n  AgentResumeOptions,\n} from \"../contracts/agent/agent-options.type\";\nimport type {\n  AgentSnapshot,\n  AgentSnapshotStatus,\n} from \"../contracts/agent/agent-snapshot.type\";\nimport type { SnapshotStore } from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type { LLMTrip } from \"../contracts/result/llm-trip.type\";\nimport type { ToolCall } from \"../contracts/result/tool-call.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AgentDriftError, AgentExecutionError } from \"../errors\";\n\n/**\n * The agent's `durable` config, narrowed to the fields the snapshot\n * helpers read. Kept minimal so this module doesn't depend on the full\n * resolved-config shape.\n */\nexport type AgentDurableConfig = {\n  store?: SnapshotStore<AgentSnapshot>;\n  deleteOnComplete?: boolean;\n};\n\n/**\n * Resolve the effective {@link SnapshotStore}: the agent's own\n * `durable.store` wins; absent that, fall back to the global default\n * set via `ai.config({ defaultSnapshotStore })`.\n *\n * The global default is typed for the supervisor snapshot shape, but\n * every store impl keys purely by `runId` and round-trips whatever\n * envelope it is handed — so it serves an `AgentSnapshot` just as well.\n * The cast re-tags the shape at this single boundary (Option B); the\n * agent only ever hands it an `AgentSnapshot`.\n */\nfunction resolveSnapshotStore(\n  durable: AgentDurableConfig | undefined,\n): SnapshotStore<AgentSnapshot> | undefined {\n  return (\n    durable?.store ??\n    (resolveDefaultSnapshotStore() as SnapshotStore<AgentSnapshot> | undefined)\n  );\n}\n\nexport type PersistAgentParams = {\n  durable: AgentDurableConfig | undefined;\n  runId: string;\n  agentName: string;\n  signature: string;\n  version?: string;\n  input: string;\n  systemPrompt?: string;\n  responseSchema?: Record<string, unknown>;\n  promptName?: string;\n  promptVersion?: string;\n  messages: Message[];\n  trips: LLMTrip[];\n  toolCalls: ToolCall[];\n  usage: Usage;\n  status: AgentSnapshotStatus;\n  startedAt: string;\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run state to the resolved snapshot store. No-op\n * (returns `{ ok: true }`) when neither `durable.store` nor the global\n * `defaultSnapshotStore` is configured — the common non-durable path.\n * Failures are returned as `{ ok: false }` rather than thrown so the\n * engine can surface them via logs without aborting the run — a failed\n * checkpoint loses resume-ability from that point but never breaks an\n * otherwise-healthy run.\n */\nexport async function persistAgentSnapshot(\n  params: PersistAgentParams,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  const snapshot: AgentSnapshot = {\n    runId: params.runId,\n    agentName: params.agentName,\n    signature: params.signature,\n    version: params.version,\n    input: params.input,\n    systemPrompt: params.systemPrompt,\n    responseSchema: params.responseSchema,\n    promptName: params.promptName,\n    promptVersion: params.promptVersion,\n    messages: params.messages,\n    trips: params.trips,\n    toolCalls: params.toolCalls,\n    usage: params.usage,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.save(snapshot);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Delete a persisted snapshot — used after a successful run when\n * `durable.deleteOnComplete` is set. Never throws: a failed delete is\n * surfaced as `{ ok: false }` and the engine logs it. No-op (ok) when no\n * store is configured.\n */\nexport async function deleteAgentSnapshot(params: {\n  durable: AgentDurableConfig | undefined;\n  runId: string;\n}): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  try {\n    await store.delete(params.runId);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Load a persisted snapshot for `resume()` and run the drift check.\n * Throws `AgentExecutionError` when no store is configured or when the\n * run is missing; throws `AgentDriftError` when the stored signature\n * doesn't match the current definition (unless `force` is set).\n */\nexport async function loadAgentSnapshotForResume(params: {\n  durable: AgentDurableConfig | undefined;\n  agentName: string;\n  signature: string;\n  runId: string;\n  options?: AgentResumeOptions<unknown>;\n}): Promise<AgentSnapshot> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    throw new AgentExecutionError(\n      `agent \"${params.agentName}\" has no durable store configured — set \\`durable: { store }\\` on the config or call \\`ai.config({ defaultSnapshotStore })\\` at boot before calling resume()`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  const snapshot = (await store.load(params.runId)) ?? null;\n\n  if (!snapshot) {\n    throw new AgentExecutionError(\n      `agent \"${params.agentName}\": no snapshot for runId \"${params.runId}\"`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  if (!params.options?.force && snapshot.signature !== params.signature) {\n    throw new AgentDriftError(\n      `agent \"${params.agentName}\" signature drift on resume`,\n      {\n        savedSignature: snapshot.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snapshot;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAoCA,SAAS,qBACP,SAC0C;CAC1C,OACE,SAAS,SACR,4BAA4B;AAEjC;;;;;;;;;;AAgCA,eAAsB,qBACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,MAAM,WAA0B;EAC9B,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,OAAO,OAAO;EACd,cAAc,OAAO;EACrB,gBAAgB,OAAO;EACvB,YAAY,OAAO;EACnB,eAAe,OAAO;EACtB,UAAU,OAAO;EACjB,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,KAAK,QAAQ;EAEzB,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;AAQA,eAAsB,oBAAoB,QAGd;CAC1B,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,IAAI;EACF,MAAM,MAAM,OAAO,OAAO,KAAK;EAE/B,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;AAQA,eAAsB,2BAA2B,QAMtB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,MAAM,IAAI,oBACR,UAAU,OAAO,UAAU,+JAC3B,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,MAAM,WAAY,MAAM,MAAM,KAAK,OAAO,KAAK,KAAM;CAErD,IAAI,CAAC,UACH,MAAM,IAAI,oBACR,UAAU,OAAO,UAAU,4BAA4B,OAAO,MAAM,IACpE,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,cAAc,OAAO,WAC1D,MAAM,IAAI,gBACR,UAAU,OAAO,UAAU,8BAC3B;EACE,gBAAgB,SAAS;EACzB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT"}

package/esm/agent/spawn-sub-agent.d.mts

@@ -5,7 +5,7 @@ import { SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
 import { BudgetOptions } from "../middleware/builtins/budget.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
-//#region ../@warlock.js/ai/src/agent/spawn-sub-agent.d.ts
+//#region ../ai/src/agent/spawn-sub-agent.d.ts
 /**
  * Spec for `spawnSubAgent` — a one-shot agent invocation. `spawnSubAgent`
  * is a thin convenience wrapper: it builds a fresh `agent()` from this

package/esm/agent/spawn-sub-agent.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-sub-agent.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/spawn-sub-agent.ts"],"mappings":";;;;;;;;;;AA2BA;;;;;;;;;;;;;;;KAAY,iBAAA;EAMV,+CAJA,IAAA,UAMe;EAJf,KAAA,EAAO,aAAA,EAMC;EAJR,IAAA,UAaA;EAXA,YAAA,GAAe,oBAAA,WAaf;EAXA,KAAA,GAAQ,cAAA,sBAWkB;EAT1B,QAAA;EAWS;;;AAMA;AAsCX;;EAhDE,MAAA,GAAS,aAAA,EAiDe;EA/CxB,MAAA,GAAS,gBAAA,CAAiB,OAAA,GAgDL;EA9CrB,MAAA,GAAS,WAAA;EA8CR;;;;;EAxCD,SAAA;AAAA;;;;;AAwC4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAFR,aAAA,oBACpB,IAAA,EAAM,iBAAA,CAAkB,OAAA,IACvB,OAAA,CAAQ,WAAA,CAAY,OAAA"}
+{"version":3,"file":"spawn-sub-agent.d.mts","names":[],"sources":["../../../../../../../ai/src/agent/spawn-sub-agent.ts"],"mappings":";;;;;;;;;;AA2BA;;;;;;;;;;;;;;;KAAY,iBAAA;EAMV,+CAJA,IAAA,UAMe;EAJf,KAAA,EAAO,aAAA,EAMC;EAJR,IAAA,UAaA;EAXA,YAAA,GAAe,oBAAA,WAaf;EAXA,KAAA,GAAQ,cAAA,sBAWkB;EAT1B,QAAA;EAWS;;;AAMA;AAsCX;;EAhDE,MAAA,GAAS,aAAA,EAiDe;EA/CxB,MAAA,GAAS,gBAAA,CAAiB,OAAA,GAgDL;EA9CrB,MAAA,GAAS,WAAA;EA8CR;;;;;EAxCD,SAAA;AAAA;;;;;AAwC4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAFR,aAAA,oBACpB,IAAA,EAAM,iBAAA,CAAkB,OAAA,IACvB,OAAA,CAAQ,WAAA,CAAY,OAAA"}

package/esm/agent/spawn-sub-agent.mjs

@@ -1,7 +1,7 @@
 import { budget } from "../middleware/builtins/budget.mjs";
 import { agent } from "./agent.mjs";
 
-//#region ../@warlock.js/ai/src/agent/spawn-sub-agent.ts
+//#region ../ai/src/agent/spawn-sub-agent.ts
 /**
 * Build a fresh agent, run a single subtask through it once, and return
 * the unified {@link AgentResult}. Equivalent to

package/esm/agent/spawn-sub-agent.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-sub-agent.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/spawn-sub-agent.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { AgentExecuteOptions } from \"../contracts/agent/agent-options.type\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { AgentResult } from \"../contracts/result/agent-result.type\";\nimport type { ModelContract } from \"../contracts/model.contract\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\nimport { budget, type BudgetOptions } from \"../middleware/builtins/budget\";\nimport type { AgentToolEntry } from \"../tool/executable-as-tool\";\nimport { agent } from \"./agent\";\n\n/**\n * Spec for `spawnSubAgent` — a one-shot agent invocation. `spawnSubAgent`\n * is a thin convenience wrapper: it builds a fresh `agent()` from this\n * spec, optionally attaches a `budget` middleware, runs the `task` once,\n * and returns the `AgentResult`. There is no separate \"sub-agent\" runtime\n * — a spawn is an ordinary new `agent()` instance, so it starts from an\n * empty conversation with its own tools/prompt exactly the way every\n * `agent()` does.\n *\n * `budget` is the one field that adds something a bare `agent()` config\n * doesn't already give you ergonomically: a first-class per-task\n * cost/token cap. When set, the spawn runs under a `budget` middleware\n * that aborts the moment a cap is crossed, so a delegated subtask cannot\n * overrun its allowance. (Equivalent to passing\n * `middleware: [budget(...)]` to a plain agent — this just promotes it to\n * a spec field.) Distinct from `maxTrips`, which caps round-trips, not spend.\n */\nexport type SpawnSubAgentSpec<TOutput = unknown> = {\n  /** Stable identifier for the spawned agent. */\n  name: string;\n  /** The model the sub-agent runs against. */\n  model: ModelContract;\n  /** The subtask instruction handed to the sub-agent's `execute()`. */\n  task: string;\n  /** Optional system prompt scoping the sub-agent's behavior. */\n  systemPrompt?: SystemPromptContract | string;\n  /** Tools the spawned agent may call inside its own loop (a fresh agent, so not shared with the caller). */\n  tools?: AgentToolEntry<unknown, unknown>[];\n  /** Per-spawn round-trip cap. Forwarded to the agent. Defaults to the agent default. */\n  maxTrips?: number;\n  /**\n   * Per-task budget. When set, the spawn runs under a `budget` middleware\n   * that aborts once a cap (`maxTokens` / `maxCostUSD`) is crossed — a\n   * spend ceiling scoped to this one subtask. Because each spawn is its\n   * own `agent()` instance, that ledger starts fresh per spawn.\n   */\n  budget?: BudgetOptions;\n  /** Structured-output schema validated into `result.data`. */\n  output?: StandardSchemaV1<TOutput>;\n  /** Cancellation handle threaded into the sub-agent run. */\n  signal?: AbortSignal;\n  /**\n   * Session identifier propagated onto the sub-agent's report tree so\n   * the spawned run groups under the parent's session in flat trace\n   * queries.\n   */\n  sessionId?: string;\n};\n\n/**\n * Build a fresh agent, run a single subtask through it once, and return\n * the unified {@link AgentResult}. Equivalent to\n * `agent({ ...spec, middleware: spec.budget && [budget(spec.budget)] }).execute(spec.task, { output, signal, sessionId })`.\n *\n * **Role.** A general-purpose \"build, run, discard\" primitive: a caller\n * (an agent tool, a workflow step, a planner step, a route callback, or\n * hand-rolled orchestration) hands a self-contained subtask to a\n * single-use agent created just for it, instead of reusing a long-lived\n * agent. The spawned `report` slots under the caller's\n * `report.children[]` like any executable, so cost and traces roll up\n * uniformly. It is not tied to any one primitive — it depends only on\n * `agent()` and the optional `budget` middleware.\n *\n * **What it is NOT.** Not a sandbox or a separate runtime. Each spawn is\n * a plain new `agent()` — its fresh conversation, own tools, and own\n * middleware state are ordinary new-instance behavior, not special\n * isolation (every `agent()` already has them). It is also a *narrower*\n * surface than `agent.execute`: one-shot, with no `history`,\n * `placeholders`, per-call event handlers, or `repair`. Reach for it when\n * you want a named single-use delegation with a per-task budget cap;\n * otherwise just construct an `agent()` and call it.\n *\n * Never throws on runtime failure — the agent surfaces failures on\n * `result.error` and a `\"failed\"` / `\"cancelled\"` report status.\n *\n * @example\n * const result = await spawnSubAgent({\n *   name: \"extract-entities\",\n *   model,\n *   task: \"Pull every company name from this article: ...\",\n *   budget: { maxCostUSD: 0.05 },\n *   output: z.object({ companies: z.array(z.string()) }),\n * });\n */\nexport async function spawnSubAgent<TOutput = unknown>(\n  spec: SpawnSubAgentSpec<TOutput>,\n): Promise<AgentResult<TOutput>> {\n  const subAgent = buildSubAgent<TOutput>(spec);\n\n  const options: AgentExecuteOptions<TOutput> = {};\n\n  if (spec.output !== undefined) {\n    options.output = spec.output;\n  }\n\n  if (spec.signal !== undefined) {\n    options.signal = spec.signal;\n  }\n\n  if (spec.sessionId !== undefined) {\n    options.sessionId = spec.sessionId;\n  }\n\n  return subAgent.execute(spec.task, options);\n}\n\n/**\n * Construct the fresh agent for one spawn. Attaches a `budget`\n * middleware only when a cap was requested, so the common no-budget case\n * is just a plain agent.\n */\nfunction buildSubAgent<TOutput>(spec: SpawnSubAgentSpec<TOutput>): AgentContract<TOutput> {\n  const middleware = spec.budget !== undefined ? [budget(spec.budget)] : undefined;\n\n  return agent<TOutput>({\n    name: spec.name,\n    model: spec.model,\n    systemPrompt: spec.systemPrompt,\n    tools: spec.tools,\n    maxTrips: spec.maxTrips,\n    output: spec.output,\n    middleware,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,eAAsB,cACpB,MAC+B;CAC/B,MAAM,WAAW,cAAuB,IAAI;CAE5C,MAAM,UAAwC,CAAC;CAE/C,IAAI,KAAK,WAAW,QAClB,QAAQ,SAAS,KAAK;CAGxB,IAAI,KAAK,WAAW,QAClB,QAAQ,SAAS,KAAK;CAGxB,IAAI,KAAK,cAAc,QACrB,QAAQ,YAAY,KAAK;CAG3B,OAAO,SAAS,QAAQ,KAAK,MAAM,OAAO;AAC5C;;;;;;AAOA,SAAS,cAAuB,MAA0D;CACxF,MAAM,aAAa,KAAK,WAAW,SAAY,CAAC,OAAO,KAAK,MAAM,CAAC,IAAI;CAEvE,OAAO,MAAe;EACpB,MAAM,KAAK;EACX,OAAO,KAAK;EACZ,cAAc,KAAK;EACnB,OAAO,KAAK;EACZ,UAAU,KAAK;EACf,QAAQ,KAAK;EACb;CACF,CAAC;AACH"}
+{"version":3,"file":"spawn-sub-agent.mjs","names":[],"sources":["../../../../../../../ai/src/agent/spawn-sub-agent.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { AgentExecuteOptions } from \"../contracts/agent/agent-options.type\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { AgentResult } from \"../contracts/result/agent-result.type\";\nimport type { ModelContract } from \"../contracts/model.contract\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\nimport { budget, type BudgetOptions } from \"../middleware/builtins/budget\";\nimport type { AgentToolEntry } from \"../tool/executable-as-tool\";\nimport { agent } from \"./agent\";\n\n/**\n * Spec for `spawnSubAgent` — a one-shot agent invocation. `spawnSubAgent`\n * is a thin convenience wrapper: it builds a fresh `agent()` from this\n * spec, optionally attaches a `budget` middleware, runs the `task` once,\n * and returns the `AgentResult`. There is no separate \"sub-agent\" runtime\n * — a spawn is an ordinary new `agent()` instance, so it starts from an\n * empty conversation with its own tools/prompt exactly the way every\n * `agent()` does.\n *\n * `budget` is the one field that adds something a bare `agent()` config\n * doesn't already give you ergonomically: a first-class per-task\n * cost/token cap. When set, the spawn runs under a `budget` middleware\n * that aborts the moment a cap is crossed, so a delegated subtask cannot\n * overrun its allowance. (Equivalent to passing\n * `middleware: [budget(...)]` to a plain agent — this just promotes it to\n * a spec field.) Distinct from `maxTrips`, which caps round-trips, not spend.\n */\nexport type SpawnSubAgentSpec<TOutput = unknown> = {\n  /** Stable identifier for the spawned agent. */\n  name: string;\n  /** The model the sub-agent runs against. */\n  model: ModelContract;\n  /** The subtask instruction handed to the sub-agent's `execute()`. */\n  task: string;\n  /** Optional system prompt scoping the sub-agent's behavior. */\n  systemPrompt?: SystemPromptContract | string;\n  /** Tools the spawned agent may call inside its own loop (a fresh agent, so not shared with the caller). */\n  tools?: AgentToolEntry<unknown, unknown>[];\n  /** Per-spawn round-trip cap. Forwarded to the agent. Defaults to the agent default. */\n  maxTrips?: number;\n  /**\n   * Per-task budget. When set, the spawn runs under a `budget` middleware\n   * that aborts once a cap (`maxTokens` / `maxCostUSD`) is crossed — a\n   * spend ceiling scoped to this one subtask. Because each spawn is its\n   * own `agent()` instance, that ledger starts fresh per spawn.\n   */\n  budget?: BudgetOptions;\n  /** Structured-output schema validated into `result.data`. */\n  output?: StandardSchemaV1<TOutput>;\n  /** Cancellation handle threaded into the sub-agent run. */\n  signal?: AbortSignal;\n  /**\n   * Session identifier propagated onto the sub-agent's report tree so\n   * the spawned run groups under the parent's session in flat trace\n   * queries.\n   */\n  sessionId?: string;\n};\n\n/**\n * Build a fresh agent, run a single subtask through it once, and return\n * the unified {@link AgentResult}. Equivalent to\n * `agent({ ...spec, middleware: spec.budget && [budget(spec.budget)] }).execute(spec.task, { output, signal, sessionId })`.\n *\n * **Role.** A general-purpose \"build, run, discard\" primitive: a caller\n * (an agent tool, a workflow step, a planner step, a route callback, or\n * hand-rolled orchestration) hands a self-contained subtask to a\n * single-use agent created just for it, instead of reusing a long-lived\n * agent. The spawned `report` slots under the caller's\n * `report.children[]` like any executable, so cost and traces roll up\n * uniformly. It is not tied to any one primitive — it depends only on\n * `agent()` and the optional `budget` middleware.\n *\n * **What it is NOT.** Not a sandbox or a separate runtime. Each spawn is\n * a plain new `agent()` — its fresh conversation, own tools, and own\n * middleware state are ordinary new-instance behavior, not special\n * isolation (every `agent()` already has them). It is also a *narrower*\n * surface than `agent.execute`: one-shot, with no `history`,\n * `placeholders`, per-call event handlers, or `repair`. Reach for it when\n * you want a named single-use delegation with a per-task budget cap;\n * otherwise just construct an `agent()` and call it.\n *\n * Never throws on runtime failure — the agent surfaces failures on\n * `result.error` and a `\"failed\"` / `\"cancelled\"` report status.\n *\n * @example\n * const result = await spawnSubAgent({\n *   name: \"extract-entities\",\n *   model,\n *   task: \"Pull every company name from this article: ...\",\n *   budget: { maxCostUSD: 0.05 },\n *   output: z.object({ companies: z.array(z.string()) }),\n * });\n */\nexport async function spawnSubAgent<TOutput = unknown>(\n  spec: SpawnSubAgentSpec<TOutput>,\n): Promise<AgentResult<TOutput>> {\n  const subAgent = buildSubAgent<TOutput>(spec);\n\n  const options: AgentExecuteOptions<TOutput> = {};\n\n  if (spec.output !== undefined) {\n    options.output = spec.output;\n  }\n\n  if (spec.signal !== undefined) {\n    options.signal = spec.signal;\n  }\n\n  if (spec.sessionId !== undefined) {\n    options.sessionId = spec.sessionId;\n  }\n\n  return subAgent.execute(spec.task, options);\n}\n\n/**\n * Construct the fresh agent for one spawn. Attaches a `budget`\n * middleware only when a cap was requested, so the common no-budget case\n * is just a plain agent.\n */\nfunction buildSubAgent<TOutput>(spec: SpawnSubAgentSpec<TOutput>): AgentContract<TOutput> {\n  const middleware = spec.budget !== undefined ? [budget(spec.budget)] : undefined;\n\n  return agent<TOutput>({\n    name: spec.name,\n    model: spec.model,\n    systemPrompt: spec.systemPrompt,\n    tools: spec.tools,\n    maxTrips: spec.maxTrips,\n    output: spec.output,\n    middleware,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,eAAsB,cACpB,MAC+B;CAC/B,MAAM,WAAW,cAAuB,IAAI;CAE5C,MAAM,UAAwC,CAAC;CAE/C,IAAI,KAAK,WAAW,QAClB,QAAQ,SAAS,KAAK;CAGxB,IAAI,KAAK,WAAW,QAClB,QAAQ,SAAS,KAAK;CAGxB,IAAI,KAAK,cAAc,QACrB,QAAQ,YAAY,KAAK;CAG3B,OAAO,SAAS,QAAQ,KAAK,MAAM,OAAO;AAC5C;;;;;;AAOA,SAAS,cAAuB,MAA0D;CACxF,MAAM,aAAa,KAAK,WAAW,SAAY,CAAC,OAAO,KAAK,MAAM,CAAC,IAAI;CAEvE,OAAO,MAAe;EACpB,MAAM,KAAK;EACX,OAAO,KAAK;EACZ,cAAc,KAAK;EACnB,OAAO,KAAK;EACZ,UAAU,KAAK;EACf,QAAQ,KAAK;EACb;CACF,CAAC;AACH"}

package/esm/ai.d.mts

@@ -61,7 +61,7 @@ import { persona } from "./system-prompt/persona.mjs";
 import { step } from "./workflow/step.mjs";
 import { workflow } from "./workflow/workflow.mjs";
 
-//#region ../@warlock.js/ai/src/ai.d.ts
+//#region ../ai/src/ai.d.ts
 /**
  * The shape of the top-level `ai` namespace. Declared as an `interface` (not an
  * inferred `const` type) so satellite packages can attach their verb via

package/esm/ai.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA6EiB,EAAA;EACf,MAAA,SAAe,WAAA;EACf,IAAA,SAAa,IAAA;EACb,KAAA,SAAc,KAAA;EACd,YAAA,SAAqB,YAAA;EACrB,OAAA,SAAgB,OAAA;EAChB,WAAA,SAAoB,WAAA;EACpB,QAAA,SAAiB,QAAA;EACjB,IAAA,SAAa,IAAA;EACb,UAAA,SAAmB,UAAA;EACnB,IAAA,SAAa,IAAA;EACb,YAAA,SAAqB,YAAA;EACrB,MAAA,SAAe,QAAA;EACf,MAAA,SAAe,MAAA;EACf,OAAA,SAAgB,OAAA;EAChB,GAAA,SAAY,GAAA;IACV,eAAA,SAAwB,eAAA;IACxB,WAAA,SAAoB,WAAA;IACpB,KAAA,SAAc,KAAA;IACd,gBAAA,SAAyB,gBAAA;IACzB,aAAA,SAAsB,aAAA;IACtB,aAAA,SAAsB,aAAA;IACtB,QAAA,SAAiB,QAAA;IACjB,QAAA,SAAiB,QAAA;IACjB,OAAA,SAAgB,OAAA;IAChB,OAAA,SAAgB,OAAA;IAChB,QAAA,SAAiB,QAAA;IACjB,oBAAA,SAA6B,oBAAA;IAC7B,UAAA,SAAmB,UAAA;IACnB,UAAA,SAAmB,UAAA;EAAA;EAErB,aAAA,SAAsB,aAAA;EACtB,MAAA,SAAe,MAAA;EACf,MAAA,SAAe,MAAA;EACf,KAAA,SAAc,KAAA;EAjCC;EAmCf,YAAA,SAAqB,YAAA;EAjCP;EAmCd,KAAA,SAAc,KAAA;EAjCE;;;;;;;EAyChB,KAAA,SAAc,KAAA;EAjCC;EAmCf,MAAA,SAAe,MAAA;EAjCH;EAmCZ,UAAA,SAAmB,UAAA;EAjCG;EAmCtB,aAAA,SAAsB,aAAA;EAjCK;EAmC3B,eAAA,SAAwB,eAAA;EAjCA;EAmCxB,yBAAA,SAAkC,yBAAA;EAClC,aAAA,SAAsB,aAAA;EACtB,IAAA,SAAa,WAAA;EACb,OAAA,SAAgB,OAAA;EAChB,MAAA,SAAe,MAAA;EAjCgB;;;;;;;EAyC/B,OAAA,EAAS,UAAA,QAAkB,qBAAA;EAC3B,GAAA,SAAY,GAAA;EACZ,UAAA,SAAmB,UAAA;EACnB,UAAA;IACE,MAAA,SAAe,MAAA;IACf,SAAA,SAAkB,WAAA;IAClB,aAAA,SAAsB,aAAA;IACtB,OAAA,SAAgB,iBAAA;IAChB,OAAA,SAAgB,OAAA;IAChB,wBAAA,SAAiC,wBAAA;EAAA;EAEnC,UAAA;IACE,MAAA,SAAe,MAAA;IACf,EAAA,SAAW,EAAA;IACX,KAAA,SAAc,KAAA;EAAA;EAEhB,QAAA;IACE,MAAA,SAAe,QAAA;IACf,EAAA,SAAW,IAAA;IACX,KAAA,SAAc,OAAA;EAAA;EAVmB;;;;;;;;EAoBnC,KAAA;IACE,QAAA,SAAiB,aAAA;IACjB,MAAA,SAAe,MAAA;IACf,SAAA;MACE,MAAA,SAAe,QAAA;MACf,EAAA,SAAW,IAAA;MACX,KAAA,SAAc,OAAA;IAAA;EAAA;EArGlB;;;;;EA6GA,SAAA,SAAkB,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6CP,EAAA,EAwER,EAAE"}
+{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA6EiB,EAAA;EACf,MAAA,SAAe,WAAA;EACf,IAAA,SAAa,IAAA;EACb,KAAA,SAAc,KAAA;EACd,YAAA,SAAqB,YAAA;EACrB,OAAA,SAAgB,OAAA;EAChB,WAAA,SAAoB,WAAA;EACpB,QAAA,SAAiB,QAAA;EACjB,IAAA,SAAa,IAAA;EACb,UAAA,SAAmB,UAAA;EACnB,IAAA,SAAa,IAAA;EACb,YAAA,SAAqB,YAAA;EACrB,MAAA,SAAe,QAAA;EACf,MAAA,SAAe,MAAA;EACf,OAAA,SAAgB,OAAA;EAChB,GAAA,SAAY,GAAA;IACV,eAAA,SAAwB,eAAA;IACxB,WAAA,SAAoB,WAAA;IACpB,KAAA,SAAc,KAAA;IACd,gBAAA,SAAyB,gBAAA;IACzB,aAAA,SAAsB,aAAA;IACtB,aAAA,SAAsB,aAAA;IACtB,QAAA,SAAiB,QAAA;IACjB,QAAA,SAAiB,QAAA;IACjB,OAAA,SAAgB,OAAA;IAChB,OAAA,SAAgB,OAAA;IAChB,QAAA,SAAiB,QAAA;IACjB,oBAAA,SAA6B,oBAAA;IAC7B,UAAA,SAAmB,UAAA;IACnB,UAAA,SAAmB,UAAA;EAAA;EAErB,aAAA,SAAsB,aAAA;EACtB,MAAA,SAAe,MAAA;EACf,MAAA,SAAe,MAAA;EACf,KAAA,SAAc,KAAA;EAjCC;EAmCf,YAAA,SAAqB,YAAA;EAjCP;EAmCd,KAAA,SAAc,KAAA;EAjCE;;;;;;;EAyChB,KAAA,SAAc,KAAA;EAjCC;EAmCf,MAAA,SAAe,MAAA;EAjCH;EAmCZ,UAAA,SAAmB,UAAA;EAjCG;EAmCtB,aAAA,SAAsB,aAAA;EAjCK;EAmC3B,eAAA,SAAwB,eAAA;EAjCA;EAmCxB,yBAAA,SAAkC,yBAAA;EAClC,aAAA,SAAsB,aAAA;EACtB,IAAA,SAAa,WAAA;EACb,OAAA,SAAgB,OAAA;EAChB,MAAA,SAAe,MAAA;EAjCgB;;;;;;;EAyC/B,OAAA,EAAS,UAAA,QAAkB,qBAAA;EAC3B,GAAA,SAAY,GAAA;EACZ,UAAA,SAAmB,UAAA;EACnB,UAAA;IACE,MAAA,SAAe,MAAA;IACf,SAAA,SAAkB,WAAA;IAClB,aAAA,SAAsB,aAAA;IACtB,OAAA,SAAgB,iBAAA;IAChB,OAAA,SAAgB,OAAA;IAChB,wBAAA,SAAiC,wBAAA;EAAA;EAEnC,UAAA;IACE,MAAA,SAAe,MAAA;IACf,EAAA,SAAW,EAAA;IACX,KAAA,SAAc,KAAA;EAAA;EAEhB,QAAA;IACE,MAAA,SAAe,QAAA;IACf,EAAA,SAAW,IAAA;IACX,KAAA,SAAc,OAAA;EAAA;EAVmB;;;;;;;;EAoBnC,KAAA;IACE,QAAA,SAAiB,aAAA;IACjB,MAAA,SAAe,MAAA;IACf,SAAA;MACE,MAAA,SAAe,QAAA;MACf,EAAA,SAAW,IAAA;MACX,KAAA,SAAc,OAAA;IAAA;EAAA;EArGlB;;;;;EA6GA,SAAA,SAAkB,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6CP,EAAA,EAwER,EAAE"}

package/esm/ai.mjs

@@ -72,7 +72,7 @@ import { team } from "./team/team.mjs";
 import { step } from "./workflow/step.mjs";
 import { workflow } from "./workflow/workflow.mjs";
 
-//#region ../@warlock.js/ai/src/ai.ts
+//#region ../ai/src/ai.ts
 /**
 * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.
 *

package/esm/ai.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ai.mjs","names":["checkpointMemory","checkpointPg","checkpointRedis","snapshotMemory","snapshotPg","snapshotRedis","guardrailSuite"],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"sourcesContent":["import { agent } from \"./agent/agent\";\nimport { batch } from \"./batch\";\nimport { streamObject } from \"./object-stream\";\nimport { serve } from \"./serve\";\nimport {\n  checkpointMemory,\n  checkpointPg,\n  checkpointRedis,\n} from \"./checkpoint\";\nimport { setAIConfig } from \"./config\";\nimport { dataset, evalScorers } from \"./eval\";\nimport { humanApproval } from \"./human/human-approval\";\nimport { human } from \"./human/register\";\nimport { image } from \"./image\";\nimport { speech } from \"./speech\";\nimport {\n  audioFromBuffer,\n  audioFromFile,\n  audioMediaTypeForFilename,\n  transcribe,\n} from \"./transcribe\";\nimport { resume } from \"./human/resume\";\nimport {\n  interruptMemory,\n  interruptPg,\n  interruptRedis,\n} from \"./human/stores\";\nimport { guardrail as guardrailSuite } from \"./guard/guardrail\";\nimport { budget, readBudgetFallbackSignal } from \"./middleware/builtins/budget\";\nimport { memory } from \"./memory\";\nimport { guardrail } from \"./middleware/builtins/guardrail\";\nimport { semanticCache } from \"./middleware/builtins/semantic-cache\";\nimport { composeMiddleware, forTool } from \"./middleware/helpers\";\nimport { mockRouter } from \"./mock\";\nimport { fallbackModel } from \"./model\";\nimport { orchestrator } from \"./orchestrator\";\nimport { planner } from \"./planner\";\nimport { defaultPromptsManager } from \"./prompts/prompts-manager\";\nimport {\n  bm25Rank,\n  cacheVectorStore,\n  chunk,\n  hybridRank,\n  keywordReranker,\n  llmReranker,\n  loadHtml,\n  loadPdf,\n  loadText,\n  loadWeb,\n  multiQuery,\n  pgVectorStore,\n  rag,\n  reciprocalRankFusion,\n  vectorLiteral,\n} from \"./rag\";\nimport { spawnSubAgent } from \"./agent/spawn-sub-agent\";\nimport { skills } from \"./skills\";\nimport { prompt } from \"./prompt\";\nimport { vcr } from \"./vcr\";\nimport { snapshotMemory, snapshotPg, snapshotRedis } from \"./snapshot\";\nimport { fanOut, router } from \"./supervisor\";\nimport { supervisor } from \"./supervisor/supervisor\";\nimport { team } from \"./team/team\";\nimport { instruction } from \"./system-prompt/instruction\";\nimport { persona } from \"./system-prompt/persona\";\nimport { systemPrompt } from \"./system-prompt/system-prompt\";\nimport { tool } from \"./tool/tool\";\nimport { step } from \"./workflow/step\";\nimport { workflow } from \"./workflow/workflow\";\n\n/**\n * The shape of the top-level `ai` namespace. Declared as an `interface` (not an\n * inferred `const` type) so satellite packages can attach their verb via\n * `declare module \"@warlock.js/ai\" { interface Ai { … } }` — e.g. `ai.workspace`,\n * `ai.tools`, `ai.mcp`, `ai.human`. The runtime object below is asserted to this\n * type; a satellite assigns its member on import.\n */\nexport interface Ai {\n  config: typeof setAIConfig;\n  tool: typeof tool;\n  agent: typeof agent;\n  systemPrompt: typeof systemPrompt;\n  persona: typeof persona;\n  instruction: typeof instruction;\n  workflow: typeof workflow;\n  step: typeof step;\n  supervisor: typeof supervisor;\n  team: typeof team;\n  orchestrator: typeof orchestrator;\n  memory: typeof memory;\n  skills: typeof skills;\n  planner: typeof planner;\n  rag: typeof rag & {\n    keywordReranker: typeof keywordReranker;\n    llmReranker: typeof llmReranker;\n    chunk: typeof chunk;\n    cacheVectorStore: typeof cacheVectorStore;\n    pgVectorStore: typeof pgVectorStore;\n    vectorLiteral: typeof vectorLiteral;\n    loadText: typeof loadText;\n    loadHtml: typeof loadHtml;\n    loadWeb: typeof loadWeb;\n    loadPdf: typeof loadPdf;\n    bm25Rank: typeof bm25Rank;\n    reciprocalRankFusion: typeof reciprocalRankFusion;\n    hybridRank: typeof hybridRank;\n    multiQuery: typeof multiQuery;\n  };\n  spawnSubAgent: typeof spawnSubAgent;\n  router: typeof router;\n  fanOut: typeof fanOut;\n  batch: typeof batch;\n  /** Structured-output streaming — partial-object snapshots + a strict final parse (A1). */\n  streamObject: typeof streamObject;\n  /** Serve an executable as an SSE HTTP endpoint — production serving primitive (A3). */\n  serve: typeof serve;\n  /**\n   * Generate images from a text prompt — the image-output verb of the\n   * output-modality track (Theme I). Wraps an `ImageModelContract` (from\n   * `openai.image(...)` / `google.image(...)`) in the uniform\n   * never-throws `{ data, error, usage, report }` envelope with cost-truth\n   * and observability.\n   */\n  image: typeof image;\n  /** Text-to-speech (TTS) — the audio-output verb of the modality track (Theme I). */\n  speech: typeof speech;\n  /** Speech-to-text (STT / transcription) — the audio-input verb of the modality track (Theme I). */\n  transcribe: typeof transcribe;\n  /** Read an audio file from disk → `AudioInput` for `ai.transcribe` (non-AI file plumbing). */\n  audioFromFile: typeof audioFromFile;\n  /** Package raw audio bytes → `AudioInput` for `ai.transcribe`. */\n  audioFromBuffer: typeof audioFromBuffer;\n  /** Resolve the audio media type from a filename's extension. */\n  audioMediaTypeForFilename: typeof audioMediaTypeForFilename;\n  fallbackModel: typeof fallbackModel;\n  eval: typeof evalScorers;\n  dataset: typeof dataset;\n  prompt: typeof prompt;\n  /**\n   * Process-wide registry of named, versioned `systemPrompt(...)` builders,\n   * keyed by `name@version`. A `systemPrompt(input, { name })` (or any\n   * `.meta({ name })` rename) auto-registers here; `ai.prompts.get(name)` /\n   * `.resolve(name)` reads them back, and `systemPrompt().merge(name)` folds a\n   * registered prompt into a new one.\n   */\n  prompts: ReturnType<typeof defaultPromptsManager>;\n  vcr: typeof vcr;\n  mockRouter: typeof mockRouter;\n  middleware: {\n    budget: typeof budget;\n    guardrail: typeof guardrail;\n    semanticCache: typeof semanticCache;\n    compose: typeof composeMiddleware;\n    forTool: typeof forTool;\n    readBudgetFallbackSignal: typeof readBudgetFallbackSignal;\n  };\n  checkpoint: {\n    memory: typeof checkpointMemory;\n    pg: typeof checkpointPg;\n    redis: typeof checkpointRedis;\n  };\n  snapshot: {\n    memory: typeof snapshotMemory;\n    pg: typeof snapshotPg;\n    redis: typeof snapshotRedis;\n  };\n  /**\n   * Human-in-the-loop tool approval (interrupt / resume).\n   *\n   * - `human.approval(options)` — the `tool.before` approval-gate middleware.\n   * - `human.resume(id, decision, options)` — out-of-process durable resume.\n   * - `human.interrupt.{memory,pg,redis}()` — durable {@link InterruptStore}\n   *   factories (memory ships real; pg/redis are lazy optional peers).\n   */\n  human: {\n    approval: typeof humanApproval;\n    resume: typeof resume;\n    interrupt: {\n      memory: typeof interruptMemory;\n      pg: typeof interruptPg;\n      redis: typeof interruptRedis;\n    };\n  };\n  /**\n   * Content-intelligence guardrail. `ai.guardrail(options)` builds a composed\n   * input / output / tool middleware; `ai.guardrail.{pii,topic,injection,moderation}`\n   * are the built-in detector factories.\n   */\n  guardrail: typeof guardrailSuite;\n}\n\n/**\n * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.\n *\n * Factories:\n * - `ai.tool(...)` — wrap an async function with a schema-validated input.\n * - `ai.agent(...)` — build an executable agent from model + tools + prompt.\n * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.\n * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).\n * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).\n * - `ai.orchestrator(...)` — session-state manager wrapped around a supervisor (durable session, drift detection, resume, commands).\n * - `ai.memory(...)` — build an agent-memory store with WORKING (in-run scratch) and SEMANTIC (cache-driver `.similar()` recall) tiers.\n * - `ai.skills(...)` — build a runtime skills library (always-injected metadata catalog + on-demand loadSkill tool).\n * - `ai.planner(...)` — build an executable that generates an ordered plan over registered capabilities, then runs it step-by-step.\n * - `ai.spawnSubAgent(spec)` — thin wrapper that builds a fresh one-shot `agent()` with an optional per-task `budget` and runs the task once. A general primitive (not planner-specific).\n * - `ai.router(...)` — build a supervisor-compatible routing agent from named intents.\n * - `ai.fanOut(unit, count)` — spread one agent/workflow into N intent entries for voting / self-consistency.\n * - `ai.batch(executable, items, opts?)` — run any executable over a dataset with bounded concurrency + per-item retry.\n * - `ai.fallbackModel(models, opts?)` — wrap an ordered model list that fails over to the next on transient provider errors.\n * - `ai.eval.{exact,contains,predicate,judge}(...)` — built-in scorer factories for `agent.eval(...)`.\n * - `ai.mockRouter(decisions, opts?)` — deterministic supervisor `route` callback for tests.\n * - `ai.checkpoint.{memory,pg,redis}()` — durable orchestrator session checkpoint stores.\n * - `ai.snapshot.{memory,pg,redis}()` — supervisor-run snapshot stores for `iterate: true` resume.\n * - `ai.human.approval(...)` / `ai.human.resume(...)` / `ai.human.interrupt.{memory,pg,redis}()` — human-in-the-loop tool approval (interrupt / resume).\n * - `ai.guardrail(options)` + `ai.guardrail.{pii,topic,injection,moderation}(...)` — content-intelligence guardrails (moderation / PII / injection / topic).\n * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.\n *\n * @example\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n * const replyIn = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);\n *\n * const myAgent = ai.agent({\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   systemPrompt: prompt,\n *   tools: [myTool],\n * });\n *\n * const result = await myAgent.execute(\"What is the weather in Cairo?\", {\n *   placeholders: { language: \"Arabic\" },\n * });\n */\nexport const ai = {\n  config: setAIConfig,\n  tool,\n  agent,\n  systemPrompt,\n  persona,\n  instruction,\n  workflow,\n  step,\n  supervisor,\n  team,\n  orchestrator,\n  memory,\n  skills,\n  planner,\n  rag: Object.assign(rag, {\n    keywordReranker,\n    llmReranker,\n    chunk,\n    cacheVectorStore,\n    pgVectorStore,\n    vectorLiteral,\n    loadText,\n    loadHtml,\n    loadWeb,\n    loadPdf,\n    bm25Rank,\n    reciprocalRankFusion,\n    hybridRank,\n    multiQuery,\n  }),\n  spawnSubAgent,\n  router,\n  fanOut,\n  batch,\n  streamObject,\n  serve,\n  image,\n  speech,\n  transcribe,\n  audioFromFile,\n  audioFromBuffer,\n  audioMediaTypeForFilename,\n  fallbackModel,\n  eval: evalScorers,\n  dataset,\n  prompt,\n  prompts: defaultPromptsManager(),\n  vcr,\n  mockRouter,\n  middleware: {\n    budget,\n    guardrail,\n    semanticCache,\n    compose: composeMiddleware,\n    forTool,\n    readBudgetFallbackSignal,\n  },\n  checkpoint: {\n    memory: checkpointMemory,\n    pg: checkpointPg,\n    redis: checkpointRedis,\n  },\n  snapshot: {\n    memory: snapshotMemory,\n    pg: snapshotPg,\n    redis: snapshotRedis,\n  },\n  human,\n  guardrail: guardrailSuite,\n  // Asserted (not `: Ai`) so a consumer build that augments `Ai` with a\n  // satellite verb (e.g. `workspace`) doesn't flag this literal as missing it.\n} as Ai;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyOA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,KAAK,OAAO,OAAO,KAAK;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,MAAM;CACN;CACA;CACA,SAAS,sBAAsB;CAC/B;CACA;CACA,YAAY;EACV;EACA;EACA;EACA,SAAS;EACT;EACA;CACF;CACA,YAAY;EACV,QAAQA;EACJC;EACGC;CACT;CACA,UAAU;EACR,QAAQC;EACR,IAAIC;EACJ,OAAOC;CACT;CACA;CACA,WAAWC;AAGb"}
+{"version":3,"file":"ai.mjs","names":["checkpointMemory","checkpointPg","checkpointRedis","snapshotMemory","snapshotPg","snapshotRedis","guardrailSuite"],"sources":["../../../../../../ai/src/ai.ts"],"sourcesContent":["import { agent } from \"./agent/agent\";\nimport { batch } from \"./batch\";\nimport { streamObject } from \"./object-stream\";\nimport { serve } from \"./serve\";\nimport {\n  checkpointMemory,\n  checkpointPg,\n  checkpointRedis,\n} from \"./checkpoint\";\nimport { setAIConfig } from \"./config\";\nimport { dataset, evalScorers } from \"./eval\";\nimport { humanApproval } from \"./human/human-approval\";\nimport { human } from \"./human/register\";\nimport { image } from \"./image\";\nimport { speech } from \"./speech\";\nimport {\n  audioFromBuffer,\n  audioFromFile,\n  audioMediaTypeForFilename,\n  transcribe,\n} from \"./transcribe\";\nimport { resume } from \"./human/resume\";\nimport {\n  interruptMemory,\n  interruptPg,\n  interruptRedis,\n} from \"./human/stores\";\nimport { guardrail as guardrailSuite } from \"./guard/guardrail\";\nimport { budget, readBudgetFallbackSignal } from \"./middleware/builtins/budget\";\nimport { memory } from \"./memory\";\nimport { guardrail } from \"./middleware/builtins/guardrail\";\nimport { semanticCache } from \"./middleware/builtins/semantic-cache\";\nimport { composeMiddleware, forTool } from \"./middleware/helpers\";\nimport { mockRouter } from \"./mock\";\nimport { fallbackModel } from \"./model\";\nimport { orchestrator } from \"./orchestrator\";\nimport { planner } from \"./planner\";\nimport { defaultPromptsManager } from \"./prompts/prompts-manager\";\nimport {\n  bm25Rank,\n  cacheVectorStore,\n  chunk,\n  hybridRank,\n  keywordReranker,\n  llmReranker,\n  loadHtml,\n  loadPdf,\n  loadText,\n  loadWeb,\n  multiQuery,\n  pgVectorStore,\n  rag,\n  reciprocalRankFusion,\n  vectorLiteral,\n} from \"./rag\";\nimport { spawnSubAgent } from \"./agent/spawn-sub-agent\";\nimport { skills } from \"./skills\";\nimport { prompt } from \"./prompt\";\nimport { vcr } from \"./vcr\";\nimport { snapshotMemory, snapshotPg, snapshotRedis } from \"./snapshot\";\nimport { fanOut, router } from \"./supervisor\";\nimport { supervisor } from \"./supervisor/supervisor\";\nimport { team } from \"./team/team\";\nimport { instruction } from \"./system-prompt/instruction\";\nimport { persona } from \"./system-prompt/persona\";\nimport { systemPrompt } from \"./system-prompt/system-prompt\";\nimport { tool } from \"./tool/tool\";\nimport { step } from \"./workflow/step\";\nimport { workflow } from \"./workflow/workflow\";\n\n/**\n * The shape of the top-level `ai` namespace. Declared as an `interface` (not an\n * inferred `const` type) so satellite packages can attach their verb via\n * `declare module \"@warlock.js/ai\" { interface Ai { … } }` — e.g. `ai.workspace`,\n * `ai.tools`, `ai.mcp`, `ai.human`. The runtime object below is asserted to this\n * type; a satellite assigns its member on import.\n */\nexport interface Ai {\n  config: typeof setAIConfig;\n  tool: typeof tool;\n  agent: typeof agent;\n  systemPrompt: typeof systemPrompt;\n  persona: typeof persona;\n  instruction: typeof instruction;\n  workflow: typeof workflow;\n  step: typeof step;\n  supervisor: typeof supervisor;\n  team: typeof team;\n  orchestrator: typeof orchestrator;\n  memory: typeof memory;\n  skills: typeof skills;\n  planner: typeof planner;\n  rag: typeof rag & {\n    keywordReranker: typeof keywordReranker;\n    llmReranker: typeof llmReranker;\n    chunk: typeof chunk;\n    cacheVectorStore: typeof cacheVectorStore;\n    pgVectorStore: typeof pgVectorStore;\n    vectorLiteral: typeof vectorLiteral;\n    loadText: typeof loadText;\n    loadHtml: typeof loadHtml;\n    loadWeb: typeof loadWeb;\n    loadPdf: typeof loadPdf;\n    bm25Rank: typeof bm25Rank;\n    reciprocalRankFusion: typeof reciprocalRankFusion;\n    hybridRank: typeof hybridRank;\n    multiQuery: typeof multiQuery;\n  };\n  spawnSubAgent: typeof spawnSubAgent;\n  router: typeof router;\n  fanOut: typeof fanOut;\n  batch: typeof batch;\n  /** Structured-output streaming — partial-object snapshots + a strict final parse (A1). */\n  streamObject: typeof streamObject;\n  /** Serve an executable as an SSE HTTP endpoint — production serving primitive (A3). */\n  serve: typeof serve;\n  /**\n   * Generate images from a text prompt — the image-output verb of the\n   * output-modality track (Theme I). Wraps an `ImageModelContract` (from\n   * `openai.image(...)` / `google.image(...)`) in the uniform\n   * never-throws `{ data, error, usage, report }` envelope with cost-truth\n   * and observability.\n   */\n  image: typeof image;\n  /** Text-to-speech (TTS) — the audio-output verb of the modality track (Theme I). */\n  speech: typeof speech;\n  /** Speech-to-text (STT / transcription) — the audio-input verb of the modality track (Theme I). */\n  transcribe: typeof transcribe;\n  /** Read an audio file from disk → `AudioInput` for `ai.transcribe` (non-AI file plumbing). */\n  audioFromFile: typeof audioFromFile;\n  /** Package raw audio bytes → `AudioInput` for `ai.transcribe`. */\n  audioFromBuffer: typeof audioFromBuffer;\n  /** Resolve the audio media type from a filename's extension. */\n  audioMediaTypeForFilename: typeof audioMediaTypeForFilename;\n  fallbackModel: typeof fallbackModel;\n  eval: typeof evalScorers;\n  dataset: typeof dataset;\n  prompt: typeof prompt;\n  /**\n   * Process-wide registry of named, versioned `systemPrompt(...)` builders,\n   * keyed by `name@version`. A `systemPrompt(input, { name })` (or any\n   * `.meta({ name })` rename) auto-registers here; `ai.prompts.get(name)` /\n   * `.resolve(name)` reads them back, and `systemPrompt().merge(name)` folds a\n   * registered prompt into a new one.\n   */\n  prompts: ReturnType<typeof defaultPromptsManager>;\n  vcr: typeof vcr;\n  mockRouter: typeof mockRouter;\n  middleware: {\n    budget: typeof budget;\n    guardrail: typeof guardrail;\n    semanticCache: typeof semanticCache;\n    compose: typeof composeMiddleware;\n    forTool: typeof forTool;\n    readBudgetFallbackSignal: typeof readBudgetFallbackSignal;\n  };\n  checkpoint: {\n    memory: typeof checkpointMemory;\n    pg: typeof checkpointPg;\n    redis: typeof checkpointRedis;\n  };\n  snapshot: {\n    memory: typeof snapshotMemory;\n    pg: typeof snapshotPg;\n    redis: typeof snapshotRedis;\n  };\n  /**\n   * Human-in-the-loop tool approval (interrupt / resume).\n   *\n   * - `human.approval(options)` — the `tool.before` approval-gate middleware.\n   * - `human.resume(id, decision, options)` — out-of-process durable resume.\n   * - `human.interrupt.{memory,pg,redis}()` — durable {@link InterruptStore}\n   *   factories (memory ships real; pg/redis are lazy optional peers).\n   */\n  human: {\n    approval: typeof humanApproval;\n    resume: typeof resume;\n    interrupt: {\n      memory: typeof interruptMemory;\n      pg: typeof interruptPg;\n      redis: typeof interruptRedis;\n    };\n  };\n  /**\n   * Content-intelligence guardrail. `ai.guardrail(options)` builds a composed\n   * input / output / tool middleware; `ai.guardrail.{pii,topic,injection,moderation}`\n   * are the built-in detector factories.\n   */\n  guardrail: typeof guardrailSuite;\n}\n\n/**\n * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.\n *\n * Factories:\n * - `ai.tool(...)` — wrap an async function with a schema-validated input.\n * - `ai.agent(...)` — build an executable agent from model + tools + prompt.\n * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.\n * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).\n * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).\n * - `ai.orchestrator(...)` — session-state manager wrapped around a supervisor (durable session, drift detection, resume, commands).\n * - `ai.memory(...)` — build an agent-memory store with WORKING (in-run scratch) and SEMANTIC (cache-driver `.similar()` recall) tiers.\n * - `ai.skills(...)` — build a runtime skills library (always-injected metadata catalog + on-demand loadSkill tool).\n * - `ai.planner(...)` — build an executable that generates an ordered plan over registered capabilities, then runs it step-by-step.\n * - `ai.spawnSubAgent(spec)` — thin wrapper that builds a fresh one-shot `agent()` with an optional per-task `budget` and runs the task once. A general primitive (not planner-specific).\n * - `ai.router(...)` — build a supervisor-compatible routing agent from named intents.\n * - `ai.fanOut(unit, count)` — spread one agent/workflow into N intent entries for voting / self-consistency.\n * - `ai.batch(executable, items, opts?)` — run any executable over a dataset with bounded concurrency + per-item retry.\n * - `ai.fallbackModel(models, opts?)` — wrap an ordered model list that fails over to the next on transient provider errors.\n * - `ai.eval.{exact,contains,predicate,judge}(...)` — built-in scorer factories for `agent.eval(...)`.\n * - `ai.mockRouter(decisions, opts?)` — deterministic supervisor `route` callback for tests.\n * - `ai.checkpoint.{memory,pg,redis}()` — durable orchestrator session checkpoint stores.\n * - `ai.snapshot.{memory,pg,redis}()` — supervisor-run snapshot stores for `iterate: true` resume.\n * - `ai.human.approval(...)` / `ai.human.resume(...)` / `ai.human.interrupt.{memory,pg,redis}()` — human-in-the-loop tool approval (interrupt / resume).\n * - `ai.guardrail(options)` + `ai.guardrail.{pii,topic,injection,moderation}(...)` — content-intelligence guardrails (moderation / PII / injection / topic).\n * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.\n *\n * @example\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n * const replyIn = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);\n *\n * const myAgent = ai.agent({\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   systemPrompt: prompt,\n *   tools: [myTool],\n * });\n *\n * const result = await myAgent.execute(\"What is the weather in Cairo?\", {\n *   placeholders: { language: \"Arabic\" },\n * });\n */\nexport const ai = {\n  config: setAIConfig,\n  tool,\n  agent,\n  systemPrompt,\n  persona,\n  instruction,\n  workflow,\n  step,\n  supervisor,\n  team,\n  orchestrator,\n  memory,\n  skills,\n  planner,\n  rag: Object.assign(rag, {\n    keywordReranker,\n    llmReranker,\n    chunk,\n    cacheVectorStore,\n    pgVectorStore,\n    vectorLiteral,\n    loadText,\n    loadHtml,\n    loadWeb,\n    loadPdf,\n    bm25Rank,\n    reciprocalRankFusion,\n    hybridRank,\n    multiQuery,\n  }),\n  spawnSubAgent,\n  router,\n  fanOut,\n  batch,\n  streamObject,\n  serve,\n  image,\n  speech,\n  transcribe,\n  audioFromFile,\n  audioFromBuffer,\n  audioMediaTypeForFilename,\n  fallbackModel,\n  eval: evalScorers,\n  dataset,\n  prompt,\n  prompts: defaultPromptsManager(),\n  vcr,\n  mockRouter,\n  middleware: {\n    budget,\n    guardrail,\n    semanticCache,\n    compose: composeMiddleware,\n    forTool,\n    readBudgetFallbackSignal,\n  },\n  checkpoint: {\n    memory: checkpointMemory,\n    pg: checkpointPg,\n    redis: checkpointRedis,\n  },\n  snapshot: {\n    memory: snapshotMemory,\n    pg: snapshotPg,\n    redis: snapshotRedis,\n  },\n  human,\n  guardrail: guardrailSuite,\n  // Asserted (not `: Ai`) so a consumer build that augments `Ai` with a\n  // satellite verb (e.g. `workspace`) doesn't flag this literal as missing it.\n} as Ai;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyOA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,KAAK,OAAO,OAAO,KAAK;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,MAAM;CACN;CACA;CACA,SAAS,sBAAsB;CAC/B;CACA;CACA,YAAY;EACV;EACA;EACA;EACA,SAAS;EACT;EACA;CACF;CACA,YAAY;EACV,QAAQA;EACJC;EACGC;CACT;CACA,UAAU;EACR,QAAQC;EACR,IAAIC;EACJ,OAAOC;CACT;CACA;CACA,WAAWC;AAGb"}

package/esm/batch/batch.d.mts

@@ -3,7 +3,7 @@ import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
 import { ExecutableContract } from "../contracts/executable.contract.mjs";
 import { BatchOptions, BatchResult } from "./batch.type.mjs";
 
-//#region ../@warlock.js/ai/src/batch/batch.d.ts
+//#region ../ai/src/batch/batch.d.ts
 /**
  * Run an executable AI primitive (agent, workflow, supervisor, tool,
  * or anything satisfying {@link ExecutableContract}) over a dataset

package/esm/batch/batch.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/batch/batch.ts"],"mappings":";;;;;;;;AAyDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAsB,KAAA,mCAAwC,UAAA,GAAa,aAAA,EACzE,UAAA,EAAY,kBAAA,CAAmB,MAAA,EAAQ,QAAA,EAAU,OAAA,GACjD,KAAA,WAAgB,MAAA,IAChB,OAAA,GAAS,YAAA,CAAa,OAAA,IACrB,OAAA,CAAQ,WAAA,CAAY,OAAA"}
+{"version":3,"file":"batch.d.mts","names":[],"sources":["../../../../../../../ai/src/batch/batch.ts"],"mappings":";;;;;;;;AAyDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAsB,KAAA,mCAAwC,UAAA,GAAa,aAAA,EACzE,UAAA,EAAY,kBAAA,CAAmB,MAAA,EAAQ,QAAA,EAAU,OAAA,GACjD,KAAA,WAAgB,MAAA,IAChB,OAAA,GAAS,YAAA,CAAa,OAAA,IACrB,OAAA,CAAQ,WAAA,CAAY,OAAA"}

package/esm/batch/batch.mjs

@@ -5,7 +5,7 @@ import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
 import { runBatchItem } from "./run-batch-item.mjs";
 import { runWithConcurrency } from "./run-with-concurrency.mjs";
 
-//#region ../@warlock.js/ai/src/batch/batch.ts
+//#region ../ai/src/batch/batch.ts
 /** Batch size above which an unset (unbounded) concurrency warns once (D5). */
 const BATCH_UNBOUNDED_WARN_THRESHOLD = 50;
 /** Process-lifetime flag so the unbounded-batch warning fires at most once. */

package/esm/batch/batch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"batch.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/batch/batch.ts"],"sourcesContent":["import type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { ExecutableContract } from \"../contracts/executable.contract\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { accumulateCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\nimport type {\n  BatchItemResult,\n  BatchOptions,\n  BatchReport,\n  BatchResult,\n} from \"./batch.type\";\nimport { runBatchItem } from \"./run-batch-item\";\nimport { runWithConcurrency } from \"./run-with-concurrency\";\n\n/** Batch size above which an unset (unbounded) concurrency warns once (D5). */\nconst BATCH_UNBOUNDED_WARN_THRESHOLD = 50;\n\n/** Process-lifetime flag so the unbounded-batch warning fires at most once. */\nlet warnedUnboundedBatch = false;\n\n/**\n * Run an executable AI primitive (agent, workflow, supervisor, tool,\n * or anything satisfying {@link ExecutableContract}) over a dataset\n * with bounded concurrency and per-item retry, returning per-item\n * outcomes plus rolled-up usage and a walkable report tree.\n *\n * **Role.** The fan-out primitive of `@warlock.js/ai`. Where an agent\n * runs once, `batch` runs the SAME executable N times — once per item\n * — and aggregates the results into the unified {@link ExecuteResult}\n * envelope, so a batch slots into cost dashboards and trace tooling\n * exactly like a single run does.\n *\n * **Isolation.** Items are independent: one item's failure (after its\n * retries are exhausted) never cancels a sibling, and the batch as a\n * whole never rejects — failures live on each {@link BatchItemResult}.\n * Reach for `result.report.failed` / `item.status` to inspect them.\n *\n * **Usage rollup.** `result.usage` and `result.report.usage` sum every\n * item's usage, satisfying the universal rollup invariant (\"own cost\n * + sum of children\"; a batch has zero own cost). Each item's own\n * report is attached under `report.children[]`, in original item\n * order, so a trace walker sees every run.\n *\n * @example\n * const result = await batch(summarizer, articles, {\n *   concurrency: 4,\n *   retry: { attempts: 3, backoff: \"exponential\" },\n *   onItem: (item) => log.info(\"batch\", \"item\", \"settled\", { index: item.index }),\n * });\n *\n * console.log(`${result.report.succeeded}/${result.report.total} ok`);\n * console.log(`${result.usage.total} tokens total`);\n */\nexport async function batch<TInput, TOptions, TResult extends BaseResult = ExecuteResult>(\n  executable: ExecutableContract<TInput, TOptions, TResult>,\n  items: readonly TInput[],\n  options: BatchOptions<TResult> = {},\n): Promise<BatchResult<TResult>> {\n  return new BatchRun(executable, items, options).run();\n}\n\n/**\n * Per-call orchestration state for one {@link batch} invocation.\n * Instantiated fresh inside the factory so the mutable accumulators\n * (`results`, `usage`) are never shared across batches. Unexported —\n * callers only ever see the plain {@link BatchResult}.\n */\nclass BatchRun<TInput, TOptions, TResult extends BaseResult> {\n  private readonly runId: string;\n  private readonly results: BatchItemResult<TResult>[];\n  private readonly startedAt = new Date().toISOString();\n  private readonly startPerf = performance.now();\n\n  public constructor(\n    private readonly executable: ExecutableContract<TInput, TOptions, TResult>,\n    private readonly items: readonly TInput[],\n    private readonly options: BatchOptions<TResult>,\n  ) {\n    this.runId = generateRunId(\"batch\");\n    this.results = new Array<BatchItemResult<TResult>>(items.length);\n  }\n\n  /**\n   * Dispatch every item through the concurrency pool, then assemble\n   * the rolled-up {@link BatchResult}. Runs once per `batch()` call.\n   */\n  public async run(): Promise<BatchResult<TResult>> {\n    const concurrency = this.resolveConcurrency();\n\n    await runWithConcurrency(this.items.length, concurrency, (index) =>\n      this.processItem(index),\n    );\n\n    return this.buildResult();\n  }\n\n  /**\n   * Resolve the effective concurrency from {@link BatchOptions.concurrency}\n   * (D5). An explicit number or `\"unbounded\"` is honored as-is; an omitted\n   * value runs unbounded for back-compat but warns once (outside tests)\n   * for a large batch so an accidental all-at-once run is visible.\n   */\n  private resolveConcurrency(): number {\n    const configured = this.options.concurrency;\n\n    if (configured === \"unbounded\") {\n      return this.items.length;\n    }\n    if (typeof configured === \"number\") {\n      return configured;\n    }\n\n    if (\n      this.items.length > BATCH_UNBOUNDED_WARN_THRESHOLD &&\n      !warnedUnboundedBatch &&\n      !process.env.VITEST &&\n      process.env.NODE_ENV !== \"test\"\n    ) {\n      warnedUnboundedBatch = true;\n      console.warn(\n        `[warlock-ai] ai.batch() is running ${this.items.length} items with unbounded concurrency (no \\`concurrency\\` set). ` +\n          'Each concurrent item consumes tokens/quota/memory — pass an explicit `concurrency` cap, or `concurrency: \"unbounded\"` to silence this.',\n      );\n    }\n\n    return this.items.length;\n  }\n\n  /**\n   * Run a single item with retry, record it positionally, then fire\n   * the `onItem` hook. A throw from the hook is swallowed — a progress\n   * callback must never break the batch.\n   */\n  private async processItem(index: number): Promise<void> {\n    const item = await runBatchItem({\n      index,\n      input: this.items[index] as TInput,\n      executable: this.executable,\n      retry: this.options.retry,\n      signal: this.options.signal,\n    });\n\n    this.results[index] = item;\n\n    if (this.options.onItem) {\n      try {\n        await this.options.onItem(item);\n      } catch {\n        // A progress hook must never break the batch — swallow its throw.\n      }\n    }\n  }\n\n  /**\n   * Fold the per-item outcomes into rolled-up usage, the child report\n   * list, and the final {@link BatchResult}, then stamp lineage across\n   * the whole subtree so every child shares this batch's root run id.\n   */\n  private buildResult(): BatchResult<TResult> {\n    const usage: Usage = { input: 0, output: 0, total: 0 };\n    const children: BaseReport[] = [];\n    const data: (unknown | undefined)[] = new Array(this.items.length).fill(undefined);\n\n    let succeeded = 0;\n    let failed = 0;\n    let cancelled = 0;\n\n    for (const item of this.results) {\n      if (item.status === \"completed\") {\n        succeeded += 1;\n      } else if (item.status === \"failed\") {\n        failed += 1;\n      } else {\n        cancelled += 1;\n      }\n\n      const itemResult = item.result;\n      if (itemResult) {\n        this.mergeUsage(usage, itemResult.usage);\n\n        if (\"report\" in itemResult && itemResult.report) {\n          children.push(itemResult.report as BaseReport);\n        }\n\n        if (item.status === \"completed\" && \"data\" in itemResult) {\n          data[item.index] = (itemResult as { data?: unknown }).data;\n        }\n      }\n    }\n\n    const report = this.buildReport(usage, children, { succeeded, failed, cancelled });\n\n    stampReportLineage(report, {\n      rootRunId: this.runId,\n      sessionId: this.options.sessionId,\n    });\n\n    return {\n      type: \"batch\",\n      data,\n      usage,\n      report,\n      items: this.results,\n    };\n  }\n\n  /**\n   * Add a child's usage into the running batch total. Scalar token\n   * channels sum directly; the optional cost breakdown merges via\n   * {@link accumulateCost} so a single unpriced child can't erase the\n   * cost of priced siblings. Optional token sub-channels\n   * (`cachedTokens`, etc.) accumulate only when some child reports\n   * them, preserving the \"never reported anywhere\" signal.\n   */\n  private mergeUsage(target: Usage, child: Usage): void {\n    target.input += child.input;\n    target.output += child.output;\n    target.total += child.total;\n\n    if (child.cachedTokens !== undefined) {\n      target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;\n    }\n\n    if (child.reasoningTokens !== undefined) {\n      target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;\n    }\n\n    if (child.cacheWriteTokens !== undefined) {\n      target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;\n    }\n\n    const mergedCost = accumulateCost(target.cost, child.cost);\n    if (mergedCost !== undefined) {\n      target.cost = mergedCost;\n    }\n  }\n\n  /**\n   * Build the batch's own {@link BatchReport} node. `parentRunId` /\n   * `rootRunId` are placeholders here — {@link stampReportLineage}\n   * rewrites them across the whole subtree right after.\n   */\n  private buildReport(\n    usage: Usage,\n    children: BaseReport[],\n    counts: { succeeded: number; failed: number; cancelled: number },\n  ): BatchReport {\n    const status = counts.failed > 0 || counts.cancelled > 0 ? \"failed\" : \"completed\";\n\n    return {\n      runId: this.runId,\n      rootRunId: this.runId,\n      name: this.options.name ?? \"batch\",\n      type: \"batch\",\n      status,\n      startedAt: this.startedAt,\n      endedAt: new Date().toISOString(),\n      duration: performance.now() - this.startPerf,\n      usage,\n      children,\n      total: this.items.length,\n      succeeded: counts.succeeded,\n      failed: counts.failed,\n      cancelled: counts.cancelled,\n      reportSchemaVersion: REPORT_SCHEMA_VERSION,\n    };\n  }\n}\n"],"mappings":";;;;;;;;;AAmBA,MAAM,iCAAiC;;AAGvC,IAAI,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmC3B,eAAsB,MACpB,YACA,OACA,UAAiC,CAAC,GACH;CAC/B,OAAO,IAAI,SAAS,YAAY,OAAO,OAAO,CAAC,CAAC,IAAI;AACtD;;;;;;;AAQA,IAAM,WAAN,MAA6D;CAM3D,AAAO,YACL,AAAiB,YACjB,AAAiB,OACjB,AAAiB,SACjB;EAHiB;EACA;EACA;oCANU,IAAI,KAAK,EAAC,CAAC,YAAY;mBACvB,YAAY,IAAI;EAO3C,KAAK,QAAQ,cAAc,OAAO;EAClC,KAAK,UAAU,IAAI,MAAgC,MAAM,MAAM;CACjE;;;;;CAMA,MAAa,MAAqC;EAChD,MAAM,cAAc,KAAK,mBAAmB;EAE5C,MAAM,mBAAmB,KAAK,MAAM,QAAQ,cAAc,UACxD,KAAK,YAAY,KAAK,CACxB;EAEA,OAAO,KAAK,YAAY;CAC1B;;;;;;;CAQA,AAAQ,qBAA6B;EACnC,MAAM,aAAa,KAAK,QAAQ;EAEhC,IAAI,eAAe,aACjB,OAAO,KAAK,MAAM;EAEpB,IAAI,OAAO,eAAe,UACxB,OAAO;EAGT,IACE,KAAK,MAAM,SAAS,kCACpB,CAAC,wBACD,CAAC,QAAQ,IAAI,UACb,QAAQ,IAAI,aAAa,QACzB;GACA,uBAAuB;GACvB,QAAQ,KACN,sCAAsC,KAAK,MAAM,OAAO,uMAE1D;EACF;EAEA,OAAO,KAAK,MAAM;CACpB;;;;;;CAOA,MAAc,YAAY,OAA8B;EACtD,MAAM,OAAO,MAAM,aAAa;GAC9B;GACA,OAAO,KAAK,MAAM;GAClB,YAAY,KAAK;GACjB,OAAO,KAAK,QAAQ;GACpB,QAAQ,KAAK,QAAQ;EACvB,CAAC;EAED,KAAK,QAAQ,SAAS;EAEtB,IAAI,KAAK,QAAQ,QACf,IAAI;GACF,MAAM,KAAK,QAAQ,OAAO,IAAI;EAChC,QAAQ,CAER;CAEJ;;;;;;CAOA,AAAQ,cAAoC;EAC1C,MAAM,QAAe;GAAE,OAAO;GAAG,QAAQ;GAAG,OAAO;EAAE;EACrD,MAAM,WAAyB,CAAC;EAChC,MAAM,OAAgC,IAAI,MAAM,KAAK,MAAM,MAAM,CAAC,CAAC,KAAK,MAAS;EAEjF,IAAI,YAAY;EAChB,IAAI,SAAS;EACb,IAAI,YAAY;EAEhB,KAAK,MAAM,QAAQ,KAAK,SAAS;GAC/B,IAAI,KAAK,WAAW,aAClB,aAAa;QACR,IAAI,KAAK,WAAW,UACzB,UAAU;QAEV,aAAa;GAGf,MAAM,aAAa,KAAK;GACxB,IAAI,YAAY;IACd,KAAK,WAAW,OAAO,WAAW,KAAK;IAEvC,IAAI,YAAY,cAAc,WAAW,QACvC,SAAS,KAAK,WAAW,MAAoB;IAG/C,IAAI,KAAK,WAAW,eAAe,UAAU,YAC3C,KAAK,KAAK,SAAU,WAAkC;GAE1D;EACF;EAEA,MAAM,SAAS,KAAK,YAAY,OAAO,UAAU;GAAE;GAAW;GAAQ;EAAU,CAAC;EAEjF,mBAAmB,QAAQ;GACzB,WAAW,KAAK;GAChB,WAAW,KAAK,QAAQ;EAC1B,CAAC;EAED,OAAO;GACL,MAAM;GACN;GACA;GACA;GACA,OAAO,KAAK;EACd;CACF;;;;;;;;;CAUA,AAAQ,WAAW,QAAe,OAAoB;EACpD,OAAO,SAAS,MAAM;EACtB,OAAO,UAAU,MAAM;EACvB,OAAO,SAAS,MAAM;EAEtB,IAAI,MAAM,iBAAiB,QACzB,OAAO,gBAAgB,OAAO,gBAAgB,KAAK,MAAM;EAG3D,IAAI,MAAM,oBAAoB,QAC5B,OAAO,mBAAmB,OAAO,mBAAmB,KAAK,MAAM;EAGjE,IAAI,MAAM,qBAAqB,QAC7B,OAAO,oBAAoB,OAAO,oBAAoB,KAAK,MAAM;EAGnE,MAAM,aAAa,eAAe,OAAO,MAAM,MAAM,IAAI;EACzD,IAAI,eAAe,QACjB,OAAO,OAAO;CAElB;;;;;;CAOA,AAAQ,YACN,OACA,UACA,QACa;EACb,MAAM,SAAS,OAAO,SAAS,KAAK,OAAO,YAAY,IAAI,WAAW;EAEtE,OAAO;GACL,OAAO,KAAK;GACZ,WAAW,KAAK;GAChB,MAAM,KAAK,QAAQ,QAAQ;GAC3B,MAAM;GACN;GACA,WAAW,KAAK;GAChB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;GAChC,UAAU,YAAY,IAAI,IAAI,KAAK;GACnC;GACA;GACA,OAAO,KAAK,MAAM;GAClB,WAAW,OAAO;GAClB,QAAQ,OAAO;GACf,WAAW,OAAO;GAClB;EACF;CACF;AACF"}
+{"version":3,"file":"batch.mjs","names":[],"sources":["../../../../../../../ai/src/batch/batch.ts"],"sourcesContent":["import type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { ExecutableContract } from \"../contracts/executable.contract\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { accumulateCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\nimport type {\n  BatchItemResult,\n  BatchOptions,\n  BatchReport,\n  BatchResult,\n} from \"./batch.type\";\nimport { runBatchItem } from \"./run-batch-item\";\nimport { runWithConcurrency } from \"./run-with-concurrency\";\n\n/** Batch size above which an unset (unbounded) concurrency warns once (D5). */\nconst BATCH_UNBOUNDED_WARN_THRESHOLD = 50;\n\n/** Process-lifetime flag so the unbounded-batch warning fires at most once. */\nlet warnedUnboundedBatch = false;\n\n/**\n * Run an executable AI primitive (agent, workflow, supervisor, tool,\n * or anything satisfying {@link ExecutableContract}) over a dataset\n * with bounded concurrency and per-item retry, returning per-item\n * outcomes plus rolled-up usage and a walkable report tree.\n *\n * **Role.** The fan-out primitive of `@warlock.js/ai`. Where an agent\n * runs once, `batch` runs the SAME executable N times — once per item\n * — and aggregates the results into the unified {@link ExecuteResult}\n * envelope, so a batch slots into cost dashboards and trace tooling\n * exactly like a single run does.\n *\n * **Isolation.** Items are independent: one item's failure (after its\n * retries are exhausted) never cancels a sibling, and the batch as a\n * whole never rejects — failures live on each {@link BatchItemResult}.\n * Reach for `result.report.failed` / `item.status` to inspect them.\n *\n * **Usage rollup.** `result.usage` and `result.report.usage` sum every\n * item's usage, satisfying the universal rollup invariant (\"own cost\n * + sum of children\"; a batch has zero own cost). Each item's own\n * report is attached under `report.children[]`, in original item\n * order, so a trace walker sees every run.\n *\n * @example\n * const result = await batch(summarizer, articles, {\n *   concurrency: 4,\n *   retry: { attempts: 3, backoff: \"exponential\" },\n *   onItem: (item) => log.info(\"batch\", \"item\", \"settled\", { index: item.index }),\n * });\n *\n * console.log(`${result.report.succeeded}/${result.report.total} ok`);\n * console.log(`${result.usage.total} tokens total`);\n */\nexport async function batch<TInput, TOptions, TResult extends BaseResult = ExecuteResult>(\n  executable: ExecutableContract<TInput, TOptions, TResult>,\n  items: readonly TInput[],\n  options: BatchOptions<TResult> = {},\n): Promise<BatchResult<TResult>> {\n  return new BatchRun(executable, items, options).run();\n}\n\n/**\n * Per-call orchestration state for one {@link batch} invocation.\n * Instantiated fresh inside the factory so the mutable accumulators\n * (`results`, `usage`) are never shared across batches. Unexported —\n * callers only ever see the plain {@link BatchResult}.\n */\nclass BatchRun<TInput, TOptions, TResult extends BaseResult> {\n  private readonly runId: string;\n  private readonly results: BatchItemResult<TResult>[];\n  private readonly startedAt = new Date().toISOString();\n  private readonly startPerf = performance.now();\n\n  public constructor(\n    private readonly executable: ExecutableContract<TInput, TOptions, TResult>,\n    private readonly items: readonly TInput[],\n    private readonly options: BatchOptions<TResult>,\n  ) {\n    this.runId = generateRunId(\"batch\");\n    this.results = new Array<BatchItemResult<TResult>>(items.length);\n  }\n\n  /**\n   * Dispatch every item through the concurrency pool, then assemble\n   * the rolled-up {@link BatchResult}. Runs once per `batch()` call.\n   */\n  public async run(): Promise<BatchResult<TResult>> {\n    const concurrency = this.resolveConcurrency();\n\n    await runWithConcurrency(this.items.length, concurrency, (index) =>\n      this.processItem(index),\n    );\n\n    return this.buildResult();\n  }\n\n  /**\n   * Resolve the effective concurrency from {@link BatchOptions.concurrency}\n   * (D5). An explicit number or `\"unbounded\"` is honored as-is; an omitted\n   * value runs unbounded for back-compat but warns once (outside tests)\n   * for a large batch so an accidental all-at-once run is visible.\n   */\n  private resolveConcurrency(): number {\n    const configured = this.options.concurrency;\n\n    if (configured === \"unbounded\") {\n      return this.items.length;\n    }\n    if (typeof configured === \"number\") {\n      return configured;\n    }\n\n    if (\n      this.items.length > BATCH_UNBOUNDED_WARN_THRESHOLD &&\n      !warnedUnboundedBatch &&\n      !process.env.VITEST &&\n      process.env.NODE_ENV !== \"test\"\n    ) {\n      warnedUnboundedBatch = true;\n      console.warn(\n        `[warlock-ai] ai.batch() is running ${this.items.length} items with unbounded concurrency (no \\`concurrency\\` set). ` +\n          'Each concurrent item consumes tokens/quota/memory — pass an explicit `concurrency` cap, or `concurrency: \"unbounded\"` to silence this.',\n      );\n    }\n\n    return this.items.length;\n  }\n\n  /**\n   * Run a single item with retry, record it positionally, then fire\n   * the `onItem` hook. A throw from the hook is swallowed — a progress\n   * callback must never break the batch.\n   */\n  private async processItem(index: number): Promise<void> {\n    const item = await runBatchItem({\n      index,\n      input: this.items[index] as TInput,\n      executable: this.executable,\n      retry: this.options.retry,\n      signal: this.options.signal,\n    });\n\n    this.results[index] = item;\n\n    if (this.options.onItem) {\n      try {\n        await this.options.onItem(item);\n      } catch {\n        // A progress hook must never break the batch — swallow its throw.\n      }\n    }\n  }\n\n  /**\n   * Fold the per-item outcomes into rolled-up usage, the child report\n   * list, and the final {@link BatchResult}, then stamp lineage across\n   * the whole subtree so every child shares this batch's root run id.\n   */\n  private buildResult(): BatchResult<TResult> {\n    const usage: Usage = { input: 0, output: 0, total: 0 };\n    const children: BaseReport[] = [];\n    const data: (unknown | undefined)[] = new Array(this.items.length).fill(undefined);\n\n    let succeeded = 0;\n    let failed = 0;\n    let cancelled = 0;\n\n    for (const item of this.results) {\n      if (item.status === \"completed\") {\n        succeeded += 1;\n      } else if (item.status === \"failed\") {\n        failed += 1;\n      } else {\n        cancelled += 1;\n      }\n\n      const itemResult = item.result;\n      if (itemResult) {\n        this.mergeUsage(usage, itemResult.usage);\n\n        if (\"report\" in itemResult && itemResult.report) {\n          children.push(itemResult.report as BaseReport);\n        }\n\n        if (item.status === \"completed\" && \"data\" in itemResult) {\n          data[item.index] = (itemResult as { data?: unknown }).data;\n        }\n      }\n    }\n\n    const report = this.buildReport(usage, children, { succeeded, failed, cancelled });\n\n    stampReportLineage(report, {\n      rootRunId: this.runId,\n      sessionId: this.options.sessionId,\n    });\n\n    return {\n      type: \"batch\",\n      data,\n      usage,\n      report,\n      items: this.results,\n    };\n  }\n\n  /**\n   * Add a child's usage into the running batch total. Scalar token\n   * channels sum directly; the optional cost breakdown merges via\n   * {@link accumulateCost} so a single unpriced child can't erase the\n   * cost of priced siblings. Optional token sub-channels\n   * (`cachedTokens`, etc.) accumulate only when some child reports\n   * them, preserving the \"never reported anywhere\" signal.\n   */\n  private mergeUsage(target: Usage, child: Usage): void {\n    target.input += child.input;\n    target.output += child.output;\n    target.total += child.total;\n\n    if (child.cachedTokens !== undefined) {\n      target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;\n    }\n\n    if (child.reasoningTokens !== undefined) {\n      target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;\n    }\n\n    if (child.cacheWriteTokens !== undefined) {\n      target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;\n    }\n\n    const mergedCost = accumulateCost(target.cost, child.cost);\n    if (mergedCost !== undefined) {\n      target.cost = mergedCost;\n    }\n  }\n\n  /**\n   * Build the batch's own {@link BatchReport} node. `parentRunId` /\n   * `rootRunId` are placeholders here — {@link stampReportLineage}\n   * rewrites them across the whole subtree right after.\n   */\n  private buildReport(\n    usage: Usage,\n    children: BaseReport[],\n    counts: { succeeded: number; failed: number; cancelled: number },\n  ): BatchReport {\n    const status = counts.failed > 0 || counts.cancelled > 0 ? \"failed\" : \"completed\";\n\n    return {\n      runId: this.runId,\n      rootRunId: this.runId,\n      name: this.options.name ?? \"batch\",\n      type: \"batch\",\n      status,\n      startedAt: this.startedAt,\n      endedAt: new Date().toISOString(),\n      duration: performance.now() - this.startPerf,\n      usage,\n      children,\n      total: this.items.length,\n      succeeded: counts.succeeded,\n      failed: counts.failed,\n      cancelled: counts.cancelled,\n      reportSchemaVersion: REPORT_SCHEMA_VERSION,\n    };\n  }\n}\n"],"mappings":";;;;;;;;;AAmBA,MAAM,iCAAiC;;AAGvC,IAAI,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmC3B,eAAsB,MACpB,YACA,OACA,UAAiC,CAAC,GACH;CAC/B,OAAO,IAAI,SAAS,YAAY,OAAO,OAAO,CAAC,CAAC,IAAI;AACtD;;;;;;;AAQA,IAAM,WAAN,MAA6D;CAM3D,AAAO,YACL,AAAiB,YACjB,AAAiB,OACjB,AAAiB,SACjB;EAHiB;EACA;EACA;oCANU,IAAI,KAAK,EAAC,CAAC,YAAY;mBACvB,YAAY,IAAI;EAO3C,KAAK,QAAQ,cAAc,OAAO;EAClC,KAAK,UAAU,IAAI,MAAgC,MAAM,MAAM;CACjE;;;;;CAMA,MAAa,MAAqC;EAChD,MAAM,cAAc,KAAK,mBAAmB;EAE5C,MAAM,mBAAmB,KAAK,MAAM,QAAQ,cAAc,UACxD,KAAK,YAAY,KAAK,CACxB;EAEA,OAAO,KAAK,YAAY;CAC1B;;;;;;;CAQA,AAAQ,qBAA6B;EACnC,MAAM,aAAa,KAAK,QAAQ;EAEhC,IAAI,eAAe,aACjB,OAAO,KAAK,MAAM;EAEpB,IAAI,OAAO,eAAe,UACxB,OAAO;EAGT,IACE,KAAK,MAAM,SAAS,kCACpB,CAAC,wBACD,CAAC,QAAQ,IAAI,UACb,QAAQ,IAAI,aAAa,QACzB;GACA,uBAAuB;GACvB,QAAQ,KACN,sCAAsC,KAAK,MAAM,OAAO,uMAE1D;EACF;EAEA,OAAO,KAAK,MAAM;CACpB;;;;;;CAOA,MAAc,YAAY,OAA8B;EACtD,MAAM,OAAO,MAAM,aAAa;GAC9B;GACA,OAAO,KAAK,MAAM;GAClB,YAAY,KAAK;GACjB,OAAO,KAAK,QAAQ;GACpB,QAAQ,KAAK,QAAQ;EACvB,CAAC;EAED,KAAK,QAAQ,SAAS;EAEtB,IAAI,KAAK,QAAQ,QACf,IAAI;GACF,MAAM,KAAK,QAAQ,OAAO,IAAI;EAChC,QAAQ,CAER;CAEJ;;;;;;CAOA,AAAQ,cAAoC;EAC1C,MAAM,QAAe;GAAE,OAAO;GAAG,QAAQ;GAAG,OAAO;EAAE;EACrD,MAAM,WAAyB,CAAC;EAChC,MAAM,OAAgC,IAAI,MAAM,KAAK,MAAM,MAAM,CAAC,CAAC,KAAK,MAAS;EAEjF,IAAI,YAAY;EAChB,IAAI,SAAS;EACb,IAAI,YAAY;EAEhB,KAAK,MAAM,QAAQ,KAAK,SAAS;GAC/B,IAAI,KAAK,WAAW,aAClB,aAAa;QACR,IAAI,KAAK,WAAW,UACzB,UAAU;QAEV,aAAa;GAGf,MAAM,aAAa,KAAK;GACxB,IAAI,YAAY;IACd,KAAK,WAAW,OAAO,WAAW,KAAK;IAEvC,IAAI,YAAY,cAAc,WAAW,QACvC,SAAS,KAAK,WAAW,MAAoB;IAG/C,IAAI,KAAK,WAAW,eAAe,UAAU,YAC3C,KAAK,KAAK,SAAU,WAAkC;GAE1D;EACF;EAEA,MAAM,SAAS,KAAK,YAAY,OAAO,UAAU;GAAE;GAAW;GAAQ;EAAU,CAAC;EAEjF,mBAAmB,QAAQ;GACzB,WAAW,KAAK;GAChB,WAAW,KAAK,QAAQ;EAC1B,CAAC;EAED,OAAO;GACL,MAAM;GACN;GACA;GACA;GACA,OAAO,KAAK;EACd;CACF;;;;;;;;;CAUA,AAAQ,WAAW,QAAe,OAAoB;EACpD,OAAO,SAAS,MAAM;EACtB,OAAO,UAAU,MAAM;EACvB,OAAO,SAAS,MAAM;EAEtB,IAAI,MAAM,iBAAiB,QACzB,OAAO,gBAAgB,OAAO,gBAAgB,KAAK,MAAM;EAG3D,IAAI,MAAM,oBAAoB,QAC5B,OAAO,mBAAmB,OAAO,mBAAmB,KAAK,MAAM;EAGjE,IAAI,MAAM,qBAAqB,QAC7B,OAAO,oBAAoB,OAAO,oBAAoB,KAAK,MAAM;EAGnE,MAAM,aAAa,eAAe,OAAO,MAAM,MAAM,IAAI;EACzD,IAAI,eAAe,QACjB,OAAO,OAAO;CAElB;;;;;;CAOA,AAAQ,YACN,OACA,UACA,QACa;EACb,MAAM,SAAS,OAAO,SAAS,KAAK,OAAO,YAAY,IAAI,WAAW;EAEtE,OAAO;GACL,OAAO,KAAK;GACZ,WAAW,KAAK;GAChB,MAAM,KAAK,QAAQ,QAAQ;GAC3B,MAAM;GACN;GACA,WAAW,KAAK;GAChB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;GAChC,UAAU,YAAY,IAAI,IAAI,KAAK;GACnC;GACA;GACA,OAAO,KAAK,MAAM;GAClB,WAAW,OAAO;GAClB,QAAQ,OAAO;GACf,WAAW,OAAO;GAClB;EACF;CACF;AACF"}

package/esm/batch/batch.type.d.mts

@@ -4,7 +4,7 @@ import { BaseReport } from "../contracts/result/base-report.type.mjs";
 import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
 import { RetryConfig } from "../contracts/workflow/retry-config.type.mjs";
 
-//#region ../@warlock.js/ai/src/batch/batch.type.d.ts
+//#region ../ai/src/batch/batch.type.d.ts
 /**
  * Terminal status of a single batch item. Mirrors the relevant subset
  * of {@link import("../contracts/result/base-report.type").ReportStatus}

package/esm/batch/batch.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/batch/batch.type.ts"],"mappings":";;;;;;;;;AAaA;;;;AAA2B;KAAf,eAAA;;;;;;;;;;;;;;;;;;;;;;AAuCF;AAUV;;KAvBY,eAAA,iBAAgC,UAAA,GAAa,aAAA;EAuBrB,mEArBlC,KAAA,UAsBA;EApBA,MAAA,EAAQ,eAAA;EAwBR;;;;EAnBA,MAAA,GAAS,OAAA,EA8CC;EA5CV,KAAA,GAAQ,OAAA,EA4Ca;EA1CrB,QAAA;AAAA;;;;;;;;KAUU,WAAA,GAAc,UAAU;EAClC,IAAA,WA+BmD;EA7BnD,KAAA,UA8BA;EA5BA,SAAA,UAqCA;EAnCA,MAAA,UAqCO;EAnCP,SAAA;AAAA;;;AAqCmB;AAYrB;;;;;;;;;;;;;;;;;KA1BY,WAAA,iBAA4B,UAAA,GAAa,aAAA,IAAiB,IAAA,CACpE,aAAA;EAGA,IAAA;EAgCU;;;;;EA1BV,IAAA,2BAgD0B;EA9C1B,KAAA,EAAO,eAAA,CAAgB,OAAA,KAqDd;EAnDT,MAAA,EAAQ,WAAA;AAAA;;;;;;;;;;KAYE,gBAAA,iBAAiC,UAAA,GAAa,aAAA,KACxD,IAAA,EAAM,eAAA,CAAgB,OAAA,aACZ,OAAA;;;;;AA6CN;;KArCM,YAAA,iBAA6B,UAAA,GAAa,aAAA;;;;;;;;;;;;;EAapD,WAAA;;;;;;;EAOA,KAAA,GAAQ,WAAA;EAER,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;;EAO1B,MAAA,GAAS,WAAA;;;;;;EAMT,SAAA;EAEA,IAAA;AAAA"}
+{"version":3,"file":"batch.type.d.mts","names":[],"sources":["../../../../../../../ai/src/batch/batch.type.ts"],"mappings":";;;;;;;;;AAaA;;;;AAA2B;KAAf,eAAA;;;;;;;;;;;;;;;;;;;;;;AAuCF;AAUV;;KAvBY,eAAA,iBAAgC,UAAA,GAAa,aAAA;EAuBrB,mEArBlC,KAAA,UAsBA;EApBA,MAAA,EAAQ,eAAA;EAwBR;;;;EAnBA,MAAA,GAAS,OAAA,EA8CC;EA5CV,KAAA,GAAQ,OAAA,EA4Ca;EA1CrB,QAAA;AAAA;;;;;;;;KAUU,WAAA,GAAc,UAAU;EAClC,IAAA,WA+BmD;EA7BnD,KAAA,UA8BA;EA5BA,SAAA,UAqCA;EAnCA,MAAA,UAqCO;EAnCP,SAAA;AAAA;;;AAqCmB;AAYrB;;;;;;;;;;;;;;;;;KA1BY,WAAA,iBAA4B,UAAA,GAAa,aAAA,IAAiB,IAAA,CACpE,aAAA;EAGA,IAAA;EAgCU;;;;;EA1BV,IAAA,2BAgD0B;EA9C1B,KAAA,EAAO,eAAA,CAAgB,OAAA,KAqDd;EAnDT,MAAA,EAAQ,WAAA;AAAA;;;;;;;;;;KAYE,gBAAA,iBAAiC,UAAA,GAAa,aAAA,KACxD,IAAA,EAAM,eAAA,CAAgB,OAAA,aACZ,OAAA;;;;;AA6CN;;KArCM,YAAA,iBAA6B,UAAA,GAAa,aAAA;;;;;;;;;;;;;EAapD,WAAA;;;;;;;EAOA,KAAA,GAAQ,WAAA;EAER,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;;EAO1B,MAAA,GAAS,WAAA;;;;;;EAMT,SAAA;EAEA,IAAA;AAAA"}

package/esm/batch/run-batch-item.mjs

@@ -1,7 +1,7 @@
 import { isAbortError, resolveBackoff, resolveRetryConfig } from "../workflow/retry.mjs";
 import { toAIError } from "../workflow/step-runner.mjs";
 
-//#region ../@warlock.js/ai/src/batch/run-batch-item.ts
+//#region ../ai/src/batch/run-batch-item.ts
 /**
 * Sleep for `ms`, settling early (without throwing) if `signal`
 * aborts during the wait. The caller re-checks `signal.aborted` after

package/esm/batch/run-batch-item.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run-batch-item.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/batch/run-batch-item.ts"],"sourcesContent":["import type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { ExecutableContract } from \"../contracts/executable.contract\";\nimport type { RetryConfig } from \"../contracts/workflow/retry-config.type\";\nimport { isAbortError, resolveBackoff, resolveRetryConfig } from \"../workflow/retry\";\nimport { toAIError } from \"../workflow/step-runner\";\nimport type { BatchItemResult } from \"./batch.type\";\n\n/**\n * Parameters for {@link runBatchItem}. Kept as a plain bag so the\n * concurrency pool can build it once per index without a long\n * positional argument list.\n */\nexport type RunBatchItemParams<TInput, TOptions, TResult extends BaseResult> = {\n  index: number;\n  input: TInput;\n  executable: ExecutableContract<TInput, TOptions, TResult>;\n  retry: RetryConfig | undefined;\n  signal: AbortSignal | undefined;\n};\n\n/**\n * Sleep for `ms`, settling early (without throwing) if `signal`\n * aborts during the wait. The caller re-checks `signal.aborted` after\n * this resolves, so a silent early return is enough — we never want a\n * pending timer to keep the batch alive past cancellation.\n */\nfunction sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {\n  return new Promise((resolve) => {\n    const timer = setTimeout(() => {\n      signal?.removeEventListener(\"abort\", onAbort);\n      resolve();\n    }, ms);\n\n    const onAbort = (): void => {\n      clearTimeout(timer);\n      resolve();\n    };\n\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n  });\n}\n\n/**\n * Execute one item with per-item retry, isolated so a failure can\n * neither throw nor disturb sibling items running in the same pool.\n *\n * Reuses the workflow retry vocabulary verbatim\n * ({@link resolveRetryConfig} / {@link resolveBackoff}) so batch and\n * workflow steps retry identically. An item is `\"completed\"` when the\n * primitive's own result carries no `error`; a primitive that returns\n * `result.error` (rather than throwing) is treated as a failed attempt\n * and re-run under the same policy.\n *\n * Cancellation short-circuits: if the signal is already aborted on\n * entry the item is reported `\"cancelled\"` without executing; an abort\n * observed mid-flight surfaces as `\"cancelled\"` too.\n */\nexport async function runBatchItem<TInput, TOptions, TResult extends BaseResult>(\n  params: RunBatchItemParams<TInput, TOptions, TResult>,\n): Promise<BatchItemResult<TResult>> {\n  const { index, input, executable, signal } = params;\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", attempts: 0 };\n  }\n\n  const retryConfig = resolveRetryConfig({ retry: params.retry }, undefined);\n  const totalAttempts = Math.max(1, retryConfig.attempts ?? 1);\n\n  let lastResult: TResult | undefined;\n  let lastError: unknown;\n  let attemptsMade = 0;\n\n  for (let attempt = 1; attempt <= totalAttempts; attempt++) {\n    if (signal?.aborted) {\n      return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n    }\n\n    attemptsMade = attempt;\n\n    try {\n      const result = await executable.execute(input, { signal } as TOptions);\n      lastResult = result;\n\n      if (!result.error) {\n        return { index, status: \"completed\", result, attempts: attempt };\n      }\n\n      lastError = result.error;\n    } catch (error) {\n      if (isAbortError(error)) {\n        return { index, status: \"cancelled\", result: lastResult, attempts: attempt };\n      }\n\n      lastError = error;\n    }\n\n    const canRetry =\n      attempt < totalAttempts &&\n      (retryConfig.retryOn ? retryConfig.retryOn(lastError, attempt) !== false : true);\n\n    if (!canRetry) {\n      break;\n    }\n\n    retryConfig.onRetry?.(attempt + 1, lastError);\n\n    const delay = resolveBackoff(attempt, retryConfig.backoff);\n    if (delay > 0) {\n      await sleep(delay, signal);\n    }\n  }\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n  }\n\n  return {\n    index,\n    status: \"failed\",\n    result: lastResult,\n    error: toAIError(lastError),\n    attempts: attemptsMade,\n  };\n}\n"],"mappings":";;;;;;;;;;AA0BA,SAAS,MAAM,IAAY,QAAgD;CACzE,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,QAAQ,iBAAiB;GAC7B,QAAQ,oBAAoB,SAAS,OAAO;GAC5C,QAAQ;EACV,GAAG,EAAE;EAEL,MAAM,gBAAsB;GAC1B,aAAa,KAAK;GAClB,QAAQ;EACV;EAEA,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC3D,CAAC;AACH;;;;;;;;;;;;;;;;AAiBA,eAAsB,aACpB,QACmC;CACnC,MAAM,EAAE,OAAO,OAAO,YAAY,WAAW;CAE7C,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,UAAU;CAAE;CAGnD,MAAM,cAAc,mBAAmB,EAAE,OAAO,OAAO,MAAM,GAAG,MAAS;CACzE,MAAM,gBAAgB,KAAK,IAAI,GAAG,YAAY,YAAY,CAAC;CAE3D,IAAI;CACJ,IAAI;CACJ,IAAI,eAAe;CAEnB,KAAK,IAAI,UAAU,GAAG,WAAW,eAAe,WAAW;EACzD,IAAI,QAAQ,SACV,OAAO;GAAE;GAAO,QAAQ;GAAa,QAAQ;GAAY,UAAU;EAAa;EAGlF,eAAe;EAEf,IAAI;GACF,MAAM,SAAS,MAAM,WAAW,QAAQ,OAAO,EAAE,OAAO,CAAa;GACrE,aAAa;GAEb,IAAI,CAAC,OAAO,OACV,OAAO;IAAE;IAAO,QAAQ;IAAa;IAAQ,UAAU;GAAQ;GAGjE,YAAY,OAAO;EACrB,SAAS,OAAO;GACd,IAAI,aAAa,KAAK,GACpB,OAAO;IAAE;IAAO,QAAQ;IAAa,QAAQ;IAAY,UAAU;GAAQ;GAG7E,YAAY;EACd;EAMA,IAAI,EAHF,UAAU,kBACT,YAAY,UAAU,YAAY,QAAQ,WAAW,OAAO,MAAM,QAAQ,QAG3E;EAGF,YAAY,UAAU,UAAU,GAAG,SAAS;EAE5C,MAAM,QAAQ,eAAe,SAAS,YAAY,OAAO;EACzD,IAAI,QAAQ,GACV,MAAM,MAAM,OAAO,MAAM;CAE7B;CAEA,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,QAAQ;EAAY,UAAU;CAAa;CAGlF,OAAO;EACL;EACA,QAAQ;EACR,QAAQ;EACR,OAAO,UAAU,SAAS;EAC1B,UAAU;CACZ;AACF"}
+{"version":3,"file":"run-batch-item.mjs","names":[],"sources":["../../../../../../../ai/src/batch/run-batch-item.ts"],"sourcesContent":["import type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { ExecutableContract } from \"../contracts/executable.contract\";\nimport type { RetryConfig } from \"../contracts/workflow/retry-config.type\";\nimport { isAbortError, resolveBackoff, resolveRetryConfig } from \"../workflow/retry\";\nimport { toAIError } from \"../workflow/step-runner\";\nimport type { BatchItemResult } from \"./batch.type\";\n\n/**\n * Parameters for {@link runBatchItem}. Kept as a plain bag so the\n * concurrency pool can build it once per index without a long\n * positional argument list.\n */\nexport type RunBatchItemParams<TInput, TOptions, TResult extends BaseResult> = {\n  index: number;\n  input: TInput;\n  executable: ExecutableContract<TInput, TOptions, TResult>;\n  retry: RetryConfig | undefined;\n  signal: AbortSignal | undefined;\n};\n\n/**\n * Sleep for `ms`, settling early (without throwing) if `signal`\n * aborts during the wait. The caller re-checks `signal.aborted` after\n * this resolves, so a silent early return is enough — we never want a\n * pending timer to keep the batch alive past cancellation.\n */\nfunction sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {\n  return new Promise((resolve) => {\n    const timer = setTimeout(() => {\n      signal?.removeEventListener(\"abort\", onAbort);\n      resolve();\n    }, ms);\n\n    const onAbort = (): void => {\n      clearTimeout(timer);\n      resolve();\n    };\n\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n  });\n}\n\n/**\n * Execute one item with per-item retry, isolated so a failure can\n * neither throw nor disturb sibling items running in the same pool.\n *\n * Reuses the workflow retry vocabulary verbatim\n * ({@link resolveRetryConfig} / {@link resolveBackoff}) so batch and\n * workflow steps retry identically. An item is `\"completed\"` when the\n * primitive's own result carries no `error`; a primitive that returns\n * `result.error` (rather than throwing) is treated as a failed attempt\n * and re-run under the same policy.\n *\n * Cancellation short-circuits: if the signal is already aborted on\n * entry the item is reported `\"cancelled\"` without executing; an abort\n * observed mid-flight surfaces as `\"cancelled\"` too.\n */\nexport async function runBatchItem<TInput, TOptions, TResult extends BaseResult>(\n  params: RunBatchItemParams<TInput, TOptions, TResult>,\n): Promise<BatchItemResult<TResult>> {\n  const { index, input, executable, signal } = params;\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", attempts: 0 };\n  }\n\n  const retryConfig = resolveRetryConfig({ retry: params.retry }, undefined);\n  const totalAttempts = Math.max(1, retryConfig.attempts ?? 1);\n\n  let lastResult: TResult | undefined;\n  let lastError: unknown;\n  let attemptsMade = 0;\n\n  for (let attempt = 1; attempt <= totalAttempts; attempt++) {\n    if (signal?.aborted) {\n      return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n    }\n\n    attemptsMade = attempt;\n\n    try {\n      const result = await executable.execute(input, { signal } as TOptions);\n      lastResult = result;\n\n      if (!result.error) {\n        return { index, status: \"completed\", result, attempts: attempt };\n      }\n\n      lastError = result.error;\n    } catch (error) {\n      if (isAbortError(error)) {\n        return { index, status: \"cancelled\", result: lastResult, attempts: attempt };\n      }\n\n      lastError = error;\n    }\n\n    const canRetry =\n      attempt < totalAttempts &&\n      (retryConfig.retryOn ? retryConfig.retryOn(lastError, attempt) !== false : true);\n\n    if (!canRetry) {\n      break;\n    }\n\n    retryConfig.onRetry?.(attempt + 1, lastError);\n\n    const delay = resolveBackoff(attempt, retryConfig.backoff);\n    if (delay > 0) {\n      await sleep(delay, signal);\n    }\n  }\n\n  if (signal?.aborted) {\n    return { index, status: \"cancelled\", result: lastResult, attempts: attemptsMade };\n  }\n\n  return {\n    index,\n    status: \"failed\",\n    result: lastResult,\n    error: toAIError(lastError),\n    attempts: attemptsMade,\n  };\n}\n"],"mappings":";;;;;;;;;;AA0BA,SAAS,MAAM,IAAY,QAAgD;CACzE,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,QAAQ,iBAAiB;GAC7B,QAAQ,oBAAoB,SAAS,OAAO;GAC5C,QAAQ;EACV,GAAG,EAAE;EAEL,MAAM,gBAAsB;GAC1B,aAAa,KAAK;GAClB,QAAQ;EACV;EAEA,QAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC3D,CAAC;AACH;;;;;;;;;;;;;;;;AAiBA,eAAsB,aACpB,QACmC;CACnC,MAAM,EAAE,OAAO,OAAO,YAAY,WAAW;CAE7C,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,UAAU;CAAE;CAGnD,MAAM,cAAc,mBAAmB,EAAE,OAAO,OAAO,MAAM,GAAG,MAAS;CACzE,MAAM,gBAAgB,KAAK,IAAI,GAAG,YAAY,YAAY,CAAC;CAE3D,IAAI;CACJ,IAAI;CACJ,IAAI,eAAe;CAEnB,KAAK,IAAI,UAAU,GAAG,WAAW,eAAe,WAAW;EACzD,IAAI,QAAQ,SACV,OAAO;GAAE;GAAO,QAAQ;GAAa,QAAQ;GAAY,UAAU;EAAa;EAGlF,eAAe;EAEf,IAAI;GACF,MAAM,SAAS,MAAM,WAAW,QAAQ,OAAO,EAAE,OAAO,CAAa;GACrE,aAAa;GAEb,IAAI,CAAC,OAAO,OACV,OAAO;IAAE;IAAO,QAAQ;IAAa;IAAQ,UAAU;GAAQ;GAGjE,YAAY,OAAO;EACrB,SAAS,OAAO;GACd,IAAI,aAAa,KAAK,GACpB,OAAO;IAAE;IAAO,QAAQ;IAAa,QAAQ;IAAY,UAAU;GAAQ;GAG7E,YAAY;EACd;EAMA,IAAI,EAHF,UAAU,kBACT,YAAY,UAAU,YAAY,QAAQ,WAAW,OAAO,MAAM,QAAQ,QAG3E;EAGF,YAAY,UAAU,UAAU,GAAG,SAAS;EAE5C,MAAM,QAAQ,eAAe,SAAS,YAAY,OAAO;EACzD,IAAI,QAAQ,GACV,MAAM,MAAM,OAAO,MAAM;CAE7B;CAEA,IAAI,QAAQ,SACV,OAAO;EAAE;EAAO,QAAQ;EAAa,QAAQ;EAAY,UAAU;CAAa;CAGlF,OAAO;EACL;EACA,QAAQ;EACR,QAAQ;EACR,OAAO,UAAU,SAAS;EAC1B,UAAU;CACZ;AACF"}

package/esm/batch/run-with-concurrency.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/batch/run-with-concurrency.ts
+//#region ../ai/src/batch/run-with-concurrency.ts
 /**
 * Run an async `worker` over every index `0..total-1` with at most
 * `limit` workers in flight at any moment, preserving nothing about

package/esm/batch/run-with-concurrency.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run-with-concurrency.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/batch/run-with-concurrency.ts"],"sourcesContent":["/**\n * Run an async `worker` over every index `0..total-1` with at most\n * `limit` workers in flight at any moment, preserving nothing about\n * completion order (the worker is responsible for recording results\n * positionally). Resolves once every index has settled.\n *\n * A fixed pool of `limit` runners each pull the next unclaimed index\n * from a shared cursor — this keeps exactly `limit` items in flight\n * even when item durations vary wildly, unlike fixed-size chunking\n * which stalls a chunk on its slowest member.\n *\n * `limit` is clamped to `[1, total]`: a non-positive limit runs fully\n * serially, a limit larger than `total` simply starts every item.\n * `total === 0` resolves immediately.\n *\n * The worker must never reject — it owns its own try/catch and records\n * outcomes. A rejection here would abort sibling runners, which is not\n * the batch contract (one item's failure never cancels another's).\n */\nexport async function runWithConcurrency(\n  total: number,\n  limit: number,\n  worker: (index: number) => Promise<void>,\n): Promise<void> {\n  if (total <= 0) {\n    return;\n  }\n\n  const poolSize = Math.max(1, Math.min(limit, total));\n  let cursor = 0;\n\n  const runner = async (): Promise<void> => {\n    while (cursor < total) {\n      const index = cursor;\n      cursor += 1;\n      await worker(index);\n    }\n  };\n\n  const pool: Promise<void>[] = [];\n  for (let slot = 0; slot < poolSize; slot++) {\n    pool.push(runner());\n  }\n\n  await Promise.all(pool);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAmBA,eAAsB,mBACpB,OACA,OACA,QACe;CACf,IAAI,SAAS,GACX;CAGF,MAAM,WAAW,KAAK,IAAI,GAAG,KAAK,IAAI,OAAO,KAAK,CAAC;CACnD,IAAI,SAAS;CAEb,MAAM,SAAS,YAA2B;EACxC,OAAO,SAAS,OAAO;GACrB,MAAM,QAAQ;GACd,UAAU;GACV,MAAM,OAAO,KAAK;EACpB;CACF;CAEA,MAAM,OAAwB,CAAC;CAC/B,KAAK,IAAI,OAAO,GAAG,OAAO,UAAU,QAClC,KAAK,KAAK,OAAO,CAAC;CAGpB,MAAM,QAAQ,IAAI,IAAI;AACxB"}
+{"version":3,"file":"run-with-concurrency.mjs","names":[],"sources":["../../../../../../../ai/src/batch/run-with-concurrency.ts"],"sourcesContent":["/**\n * Run an async `worker` over every index `0..total-1` with at most\n * `limit` workers in flight at any moment, preserving nothing about\n * completion order (the worker is responsible for recording results\n * positionally). Resolves once every index has settled.\n *\n * A fixed pool of `limit` runners each pull the next unclaimed index\n * from a shared cursor — this keeps exactly `limit` items in flight\n * even when item durations vary wildly, unlike fixed-size chunking\n * which stalls a chunk on its slowest member.\n *\n * `limit` is clamped to `[1, total]`: a non-positive limit runs fully\n * serially, a limit larger than `total` simply starts every item.\n * `total === 0` resolves immediately.\n *\n * The worker must never reject — it owns its own try/catch and records\n * outcomes. A rejection here would abort sibling runners, which is not\n * the batch contract (one item's failure never cancels another's).\n */\nexport async function runWithConcurrency(\n  total: number,\n  limit: number,\n  worker: (index: number) => Promise<void>,\n): Promise<void> {\n  if (total <= 0) {\n    return;\n  }\n\n  const poolSize = Math.max(1, Math.min(limit, total));\n  let cursor = 0;\n\n  const runner = async (): Promise<void> => {\n    while (cursor < total) {\n      const index = cursor;\n      cursor += 1;\n      await worker(index);\n    }\n  };\n\n  const pool: Promise<void>[] = [];\n  for (let slot = 0; slot < poolSize; slot++) {\n    pool.push(runner());\n  }\n\n  await Promise.all(pool);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAmBA,eAAsB,mBACpB,OACA,OACA,QACe;CACf,IAAI,SAAS,GACX;CAGF,MAAM,WAAW,KAAK,IAAI,GAAG,KAAK,IAAI,OAAO,KAAK,CAAC;CACnD,IAAI,SAAS;CAEb,MAAM,SAAS,YAA2B;EACxC,OAAO,SAAS,OAAO;GACrB,MAAM,QAAQ;GACd,UAAU;GACV,MAAM,OAAO,KAAK;EACpB;CACF;CAEA,MAAM,OAAwB,CAAC;CAC/B,KAAK,IAAI,OAAO,GAAG,OAAO,UAAU,QAClC,KAAK,KAAK,OAAO,CAAC;CAGpB,MAAM,QAAQ,IAAI,IAAI;AACxB"}

package/esm/checkpoint/memory.d.mts

@@ -1,6 +1,6 @@
 import { CheckpointStore } from "../contracts/orchestrator/checkpoint-store.contract.mjs";
 
-//#region ../@warlock.js/ai/src/checkpoint/memory.d.ts
+//#region ../ai/src/checkpoint/memory.d.ts
 /**
  * Create an in-memory {@link CheckpointStore}. Zero-config — no client,
  * no connection. Suitable for dev, tests, and single-process apps that

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/memory.ts"],"mappings":";;;;;AAmKA;;;;AAAyC;;;;;;;;iBAAzB,MAAA,IAAU,eAAe"}
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../ai/src/checkpoint/memory.ts"],"mappings":";;;;;AAmKA;;;;AAAyC;;;;;;;;iBAAzB,MAAA,IAAU,eAAe"}

package/esm/checkpoint/memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/memory.ts"],"sourcesContent":["import type {\n  CheckpointRecord,\n  CheckpointStore,\n} from \"../contracts/orchestrator/checkpoint-store.contract\";\n\n/**\n * Composite key for the in-memory session index — one bucket per\n * `(orchestratorName, sessionId)` pair. The separator can't appear in\n * the segments in practice (names are identifiers, sessionIds are\n * dev-owned opaque strings), so a simple join is collision-safe enough\n * for an in-process store.\n */\nfunction bucketKey(orchestratorName: string, sessionId: string): string {\n  return `${orchestratorName}\u0000${sessionId}`;\n}\n\n/**\n * In-memory {@link CheckpointStore} — append-only session checkpoints\n * held in a process-local `Map`, never persisted to disk.\n *\n * Owns: the per-session bucket of {@link CheckpointRecord} rows and the\n * \"latest turn wins\" load semantics. Does NOT own: durability,\n * cross-process sharing, or TTL eviction — it is the zero-config\n * default for dev, tests, and single-process apps that don't need\n * resume across restarts. Reach for `ai.checkpoint.pg()` /\n * `ai.checkpoint.redis()` (Phase 2) when durability matters.\n *\n * Front it with the {@link memory} factory — callers never `new` it.\n */\nclass MemoryCheckpointStore implements CheckpointStore {\n  /** Per-session append-only row buckets, keyed by `(orchestratorName, sessionId)`. */\n  private readonly sessions = new Map<string, CheckpointRecord[]>();\n\n  /**\n   * Return the latest checkpoint (highest `turn_index`) for a session,\n   * or `undefined` when the session has no rows. Rows are appended in\n   * turn order, so the last element is the latest — no scan needed.\n   */\n  public async load(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<CheckpointRecord | undefined> {\n    const rows = this.sessions.get(bucketKey(orchestratorName, sessionId));\n\n    if (!rows || rows.length === 0) {\n      return undefined;\n    }\n\n    return rows[rows.length - 1];\n  }\n\n  /**\n   * Append a checkpoint row to its session bucket. Append-only — an\n   * existing `turn_index` is never overwritten; a fresh row is pushed.\n   */\n  public async save(record: CheckpointRecord): Promise<void> {\n    const key = bucketKey(record.orchestrator_name, record.session_id);\n    const rows = this.sessions.get(key);\n\n    if (rows) {\n      rows.push(record);\n\n      return;\n    }\n\n    this.sessions.set(key, [record]);\n  }\n\n  /**\n   * Drop every row for a session, ending it.\n   */\n  public async delete(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    this.sessions.delete(bucketKey(orchestratorName, sessionId));\n  }\n\n  /**\n   * List the session ids known for an orchestrator, optionally filtered\n   * by a session-id prefix. Reads the latest row of each bucket so the\n   * authoritative `session_id` is returned even if the key encoding\n   * ever changes.\n   */\n  public async list(\n    orchestratorName: string,\n    prefix?: string,\n  ): Promise<string[]> {\n    const sessionIds: string[] = [];\n\n    for (const rows of this.sessions.values()) {\n      const latest = rows[rows.length - 1];\n\n      if (!latest || latest.orchestrator_name !== orchestratorName) {\n        continue;\n      }\n\n      if (prefix !== undefined && !latest.session_id.startsWith(prefix)) {\n        continue;\n      }\n\n      sessionIds.push(latest.session_id);\n    }\n\n    return sessionIds;\n  }\n\n  /**\n   * Drop every row for a session whose `turn_index` is strictly below\n   * `keepBeforeTurnIndex`, enforcing the `keepSnapshots` retention bound\n   * (§4 Phase 6, Q20). Rebuilds the bucket in place with the surviving\n   * tail; an emptied bucket is removed so `list()` no longer reports the\n   * session.\n   */\n  public async prune(\n    orchestratorName: string,\n    sessionId: string,\n    keepBeforeTurnIndex: number,\n  ): Promise<void> {\n    const key = bucketKey(orchestratorName, sessionId);\n    const rows = this.sessions.get(key);\n\n    if (!rows) {\n      return;\n    }\n\n    const kept = rows.filter((row) => row.turn_index >= keepBeforeTurnIndex);\n\n    if (kept.length === 0) {\n      this.sessions.delete(key);\n\n      return;\n    }\n\n    if (kept.length !== rows.length) {\n      this.sessions.set(key, kept);\n    }\n  }\n\n  /**\n   * The memory store has no backing table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create an in-memory {@link CheckpointStore}. Zero-config — no client,\n * no connection. Suitable for dev, tests, and single-process apps that\n * don't need resume across restarts.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   checkpointStore: ai.checkpoint.memory(),\n * });\n */\nexport function memory(): CheckpointStore {\n  return new MemoryCheckpointStore();\n}\n"],"mappings":";;;;;;;;AAYA,SAAS,UAAU,kBAA0B,WAA2B;CACtE,OAAO,GAAG,iBAAiB,GAAG;AAChC;;;;;;;;;;;;;;AAeA,IAAM,wBAAN,MAAuD;;kCAEzB,IAAI,IAAgC;;;;;;;CAOhE,MAAa,KACX,kBACA,WACuC;EACvC,MAAM,OAAO,KAAK,SAAS,IAAI,UAAU,kBAAkB,SAAS,CAAC;EAErE,IAAI,CAAC,QAAQ,KAAK,WAAW,GAC3B;EAGF,OAAO,KAAK,KAAK,SAAS;CAC5B;;;;;CAMA,MAAa,KAAK,QAAyC;EACzD,MAAM,MAAM,UAAU,OAAO,mBAAmB,OAAO,UAAU;EACjE,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,MAAM;GACR,KAAK,KAAK,MAAM;GAEhB;EACF;EAEA,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC;CACjC;;;;CAKA,MAAa,OACX,kBACA,WACe;EACf,KAAK,SAAS,OAAO,UAAU,kBAAkB,SAAS,CAAC;CAC7D;;;;;;;CAQA,MAAa,KACX,kBACA,QACmB;EACnB,MAAM,aAAuB,CAAC;EAE9B,KAAK,MAAM,QAAQ,KAAK,SAAS,OAAO,GAAG;GACzC,MAAM,SAAS,KAAK,KAAK,SAAS;GAElC,IAAI,CAAC,UAAU,OAAO,sBAAsB,kBAC1C;GAGF,IAAI,WAAW,UAAa,CAAC,OAAO,WAAW,WAAW,MAAM,GAC9D;GAGF,WAAW,KAAK,OAAO,UAAU;EACnC;EAEA,OAAO;CACT;;;;;;;;CASA,MAAa,MACX,kBACA,WACA,qBACe;EACf,MAAM,MAAM,UAAU,kBAAkB,SAAS;EACjD,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,CAAC,MACH;EAGF,MAAM,OAAO,KAAK,QAAQ,QAAQ,IAAI,cAAc,mBAAmB;EAEvE,IAAI,KAAK,WAAW,GAAG;GACrB,KAAK,SAAS,OAAO,GAAG;GAExB;EACF;EAEA,IAAI,KAAK,WAAW,KAAK,QACvB,KAAK,SAAS,IAAI,KAAK,IAAI;CAE/B;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;AAgBA,SAAgB,SAA0B;CACxC,OAAO,IAAI,sBAAsB;AACnC"}
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../ai/src/checkpoint/memory.ts"],"sourcesContent":["import type {\n  CheckpointRecord,\n  CheckpointStore,\n} from \"../contracts/orchestrator/checkpoint-store.contract\";\n\n/**\n * Composite key for the in-memory session index — one bucket per\n * `(orchestratorName, sessionId)` pair. The separator can't appear in\n * the segments in practice (names are identifiers, sessionIds are\n * dev-owned opaque strings), so a simple join is collision-safe enough\n * for an in-process store.\n */\nfunction bucketKey(orchestratorName: string, sessionId: string): string {\n  return `${orchestratorName}\u0000${sessionId}`;\n}\n\n/**\n * In-memory {@link CheckpointStore} — append-only session checkpoints\n * held in a process-local `Map`, never persisted to disk.\n *\n * Owns: the per-session bucket of {@link CheckpointRecord} rows and the\n * \"latest turn wins\" load semantics. Does NOT own: durability,\n * cross-process sharing, or TTL eviction — it is the zero-config\n * default for dev, tests, and single-process apps that don't need\n * resume across restarts. Reach for `ai.checkpoint.pg()` /\n * `ai.checkpoint.redis()` (Phase 2) when durability matters.\n *\n * Front it with the {@link memory} factory — callers never `new` it.\n */\nclass MemoryCheckpointStore implements CheckpointStore {\n  /** Per-session append-only row buckets, keyed by `(orchestratorName, sessionId)`. */\n  private readonly sessions = new Map<string, CheckpointRecord[]>();\n\n  /**\n   * Return the latest checkpoint (highest `turn_index`) for a session,\n   * or `undefined` when the session has no rows. Rows are appended in\n   * turn order, so the last element is the latest — no scan needed.\n   */\n  public async load(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<CheckpointRecord | undefined> {\n    const rows = this.sessions.get(bucketKey(orchestratorName, sessionId));\n\n    if (!rows || rows.length === 0) {\n      return undefined;\n    }\n\n    return rows[rows.length - 1];\n  }\n\n  /**\n   * Append a checkpoint row to its session bucket. Append-only — an\n   * existing `turn_index` is never overwritten; a fresh row is pushed.\n   */\n  public async save(record: CheckpointRecord): Promise<void> {\n    const key = bucketKey(record.orchestrator_name, record.session_id);\n    const rows = this.sessions.get(key);\n\n    if (rows) {\n      rows.push(record);\n\n      return;\n    }\n\n    this.sessions.set(key, [record]);\n  }\n\n  /**\n   * Drop every row for a session, ending it.\n   */\n  public async delete(\n    orchestratorName: string,\n    sessionId: string,\n  ): Promise<void> {\n    this.sessions.delete(bucketKey(orchestratorName, sessionId));\n  }\n\n  /**\n   * List the session ids known for an orchestrator, optionally filtered\n   * by a session-id prefix. Reads the latest row of each bucket so the\n   * authoritative `session_id` is returned even if the key encoding\n   * ever changes.\n   */\n  public async list(\n    orchestratorName: string,\n    prefix?: string,\n  ): Promise<string[]> {\n    const sessionIds: string[] = [];\n\n    for (const rows of this.sessions.values()) {\n      const latest = rows[rows.length - 1];\n\n      if (!latest || latest.orchestrator_name !== orchestratorName) {\n        continue;\n      }\n\n      if (prefix !== undefined && !latest.session_id.startsWith(prefix)) {\n        continue;\n      }\n\n      sessionIds.push(latest.session_id);\n    }\n\n    return sessionIds;\n  }\n\n  /**\n   * Drop every row for a session whose `turn_index` is strictly below\n   * `keepBeforeTurnIndex`, enforcing the `keepSnapshots` retention bound\n   * (§4 Phase 6, Q20). Rebuilds the bucket in place with the surviving\n   * tail; an emptied bucket is removed so `list()` no longer reports the\n   * session.\n   */\n  public async prune(\n    orchestratorName: string,\n    sessionId: string,\n    keepBeforeTurnIndex: number,\n  ): Promise<void> {\n    const key = bucketKey(orchestratorName, sessionId);\n    const rows = this.sessions.get(key);\n\n    if (!rows) {\n      return;\n    }\n\n    const kept = rows.filter((row) => row.turn_index >= keepBeforeTurnIndex);\n\n    if (kept.length === 0) {\n      this.sessions.delete(key);\n\n      return;\n    }\n\n    if (kept.length !== rows.length) {\n      this.sessions.set(key, kept);\n    }\n  }\n\n  /**\n   * The memory store has no backing table — there is nothing to\n   * migrate. Returns an empty string so callers can treat `schema()`\n   * uniformly across drivers.\n   */\n  public schema(): string {\n    return \"\";\n  }\n}\n\n/**\n * Create an in-memory {@link CheckpointStore}. Zero-config — no client,\n * no connection. Suitable for dev, tests, and single-process apps that\n * don't need resume across restarts.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n *\n * const orchestrator = ai.orchestrator({\n *   name: \"support\",\n *   intents: { ... },\n *   checkpointStore: ai.checkpoint.memory(),\n * });\n */\nexport function memory(): CheckpointStore {\n  return new MemoryCheckpointStore();\n}\n"],"mappings":";;;;;;;;AAYA,SAAS,UAAU,kBAA0B,WAA2B;CACtE,OAAO,GAAG,iBAAiB,GAAG;AAChC;;;;;;;;;;;;;;AAeA,IAAM,wBAAN,MAAuD;;kCAEzB,IAAI,IAAgC;;;;;;;CAOhE,MAAa,KACX,kBACA,WACuC;EACvC,MAAM,OAAO,KAAK,SAAS,IAAI,UAAU,kBAAkB,SAAS,CAAC;EAErE,IAAI,CAAC,QAAQ,KAAK,WAAW,GAC3B;EAGF,OAAO,KAAK,KAAK,SAAS;CAC5B;;;;;CAMA,MAAa,KAAK,QAAyC;EACzD,MAAM,MAAM,UAAU,OAAO,mBAAmB,OAAO,UAAU;EACjE,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,MAAM;GACR,KAAK,KAAK,MAAM;GAEhB;EACF;EAEA,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC;CACjC;;;;CAKA,MAAa,OACX,kBACA,WACe;EACf,KAAK,SAAS,OAAO,UAAU,kBAAkB,SAAS,CAAC;CAC7D;;;;;;;CAQA,MAAa,KACX,kBACA,QACmB;EACnB,MAAM,aAAuB,CAAC;EAE9B,KAAK,MAAM,QAAQ,KAAK,SAAS,OAAO,GAAG;GACzC,MAAM,SAAS,KAAK,KAAK,SAAS;GAElC,IAAI,CAAC,UAAU,OAAO,sBAAsB,kBAC1C;GAGF,IAAI,WAAW,UAAa,CAAC,OAAO,WAAW,WAAW,MAAM,GAC9D;GAGF,WAAW,KAAK,OAAO,UAAU;EACnC;EAEA,OAAO;CACT;;;;;;;;CASA,MAAa,MACX,kBACA,WACA,qBACe;EACf,MAAM,MAAM,UAAU,kBAAkB,SAAS;EACjD,MAAM,OAAO,KAAK,SAAS,IAAI,GAAG;EAElC,IAAI,CAAC,MACH;EAGF,MAAM,OAAO,KAAK,QAAQ,QAAQ,IAAI,cAAc,mBAAmB;EAEvE,IAAI,KAAK,WAAW,GAAG;GACrB,KAAK,SAAS,OAAO,GAAG;GAExB;EACF;EAEA,IAAI,KAAK,WAAW,KAAK,QACvB,KAAK,SAAS,IAAI,KAAK,IAAI;CAE/B;;;;;;CAOA,AAAO,SAAiB;EACtB,OAAO;CACT;AACF;;;;;;;;;;;;;;;AAgBA,SAAgB,SAA0B;CACxC,OAAO,IAAI,sBAAsB;AACnC"}

package/esm/checkpoint/pg.d.mts

@@ -1,7 +1,7 @@
 import { PgClientLike } from "../contracts/orchestrator/snapshot-store.contract.mjs";
 import { CheckpointStore } from "../contracts/orchestrator/checkpoint-store.contract.mjs";
 
-//#region ../@warlock.js/ai/src/checkpoint/pg.d.ts
+//#region ../ai/src/checkpoint/pg.d.ts
 /**
  * Options for the Postgres {@link CheckpointStore} (orchestrator.md §8.3).
  *

package/esm/checkpoint/pg.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"pg.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/checkpoint/pg.ts"],"mappings":";;;;;;AAaA;;;;;KAAY,mBAAA;EAIV,yFAFA,MAAA,EAAQ,YAAY,EAIjB;EAFH,KAAA,WAyWc;EAvWd,GAAA;AAAA;;;;;;AAuW+D;;;;;;;;;;;;iBAAjD,EAAA,CAAG,OAAA,EAAS,mBAAA,GAAsB,eAAe"}
+{"version":3,"file":"pg.d.mts","names":[],"sources":["../../../../../../../ai/src/checkpoint/pg.ts"],"mappings":";;;;;;AAaA;;;;;KAAY,mBAAA;EAIV,yFAFA,MAAA,EAAQ,YAAY,EAIjB;EAFH,KAAA,WAyWc;EAvWd,GAAA;AAAA;;;;;;AAuW+D;;;;;;;;;;;;iBAAjD,EAAA,CAAG,OAAA,EAAS,mBAAA,GAAsB,eAAe"}

package/esm/checkpoint/pg.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/checkpoint/pg.ts
+//#region ../ai/src/checkpoint/pg.ts
 /**
 * Default backing table — matches the §8.6 reference DDL verbatim so a
 * stock migration provisions the store with no extra config.