@warlock.js/ai 4.4.0 → 4.6.0

package/esm/ai.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ai.mjs","names":["checkpointMemory","checkpointPg","checkpointRedis","snapshotMemory","snapshotPg","snapshotRedis"],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"sourcesContent":["import { agent } from \"./agent/agent\";\nimport { batch } from \"./batch\";\nimport {\n  checkpointMemory,\n  checkpointPg,\n  checkpointRedis,\n} from \"./checkpoint\";\nimport { setAIConfig } from \"./config\";\nimport { evalScorers } from \"./eval\";\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 { spawnSubAgent } from \"./agent/spawn-sub-agent\";\nimport { snapshotMemory, snapshotPg, snapshotRedis } from \"./snapshot\";\nimport { fanOut, router } from \"./supervisor\";\nimport { supervisor } from \"./supervisor/supervisor\";\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 * 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.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.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  orchestrator,\n  memory,\n  planner,\n  spawnSubAgent,\n  router,\n  fanOut,\n  batch,\n  fallbackModel,\n  eval: evalScorers,\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};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,MAAM;CACN;CACA,YAAY;EACV;EACA;EACA;EACA,SAAS;EACT;EACA;CACF;CACA,YAAY;EACFA;EACJC;EACGC;CACT;CACA,UAAU;EACR,QAAQC;EACR,IAAIC;EACJ,OAAOC;CACT;AACF"}
+{"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"}

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":";;;;;;;;AAmDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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":["../../../../../../../@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"}

package/esm/batch/batch.mjs

@@ -6,6 +6,10 @@ import { runBatchItem } from "./run-batch-item.mjs";
 import { runWithConcurrency } from "./run-with-concurrency.mjs";
 
 //#region ../@warlock.js/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. */
+let warnedUnboundedBatch = false;
 /**
 * Run an executable AI primitive (agent, workflow, supervisor, tool,
 * or anything satisfying {@link ExecutableContract}) over a dataset
@@ -63,11 +67,27 @@ var BatchRun = class {
 	* the rolled-up {@link BatchResult}. Runs once per `batch()` call.
 	*/
 	async run() {
-		const concurrency = this.options.concurrency ?? this.items.length;
+		const concurrency = this.resolveConcurrency();
 		await runWithConcurrency(this.items.length, concurrency, (index) => this.processItem(index));
 		return this.buildResult();
 	}
 	/**
+	* Resolve the effective concurrency from {@link BatchOptions.concurrency}
+	* (D5). An explicit number or `"unbounded"` is honored as-is; an omitted
+	* value runs unbounded for back-compat but warns once (outside tests)
+	* for a large batch so an accidental all-at-once run is visible.
+	*/
+	resolveConcurrency() {
+		const configured = this.options.concurrency;
+		if (configured === "unbounded") return this.items.length;
+		if (typeof configured === "number") return configured;
+		if (this.items.length > BATCH_UNBOUNDED_WARN_THRESHOLD && !warnedUnboundedBatch && !process.env.VITEST && process.env.NODE_ENV !== "test") {
+			warnedUnboundedBatch = true;
+			console.warn(`[warlock-ai] ai.batch() is running ${this.items.length} items with unbounded concurrency (no \`concurrency\` set). Each concurrent item consumes tokens/quota/memory — pass an explicit \`concurrency\` cap, or \`concurrency: "unbounded"\` to silence this.`);
+		}
+		return this.items.length;
+	}
+	/**
 	* Run a single item with retry, record it positionally, then fire
 	* the `onItem` hook. A throw from the hook is swallowed — a progress
 	* callback must never break the batch.

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/**\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.options.concurrency ?? this.items.length;\n\n    await runWithConcurrency(this.items.length, concurrency, (index) =>\n      this.processItem(index),\n    );\n\n    return this.buildResult();\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":"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"}
+{"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":"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"}

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

@@ -111,11 +111,18 @@ type BatchItemHandler<TResult extends BaseResult = ExecuteResult> = (item: Batch
  */
 type BatchOptions<TResult extends BaseResult = ExecuteResult> = {
   /**
-   * Maximum number of items running at once. A positive integer.
-   * Defaults to `items.length` (all at once). Values `<= 0` are
-   * treated as `1` (fully serial).
+   * Maximum number of items running at once. A positive integer, or the
+   * literal `"unbounded"` to run the whole dataset at once (every item
+   * concurrent). Values `<= 0` are treated as `1` (fully serial).
+   *
+   * Omitting it still runs unbounded (back-compat), but for a large batch
+   * (> 50 items) that emits a one-time warning (outside tests) — each
+   * concurrent item can consume tokens, provider quota, and memory, so an
+   * accidental unbounded run is a cost/DoS foot-gun. Pass an explicit
+   * number to cap it, or `"unbounded"` to acknowledge the all-at-once
+   * behavior and silence the warning. (D5)
    */
-  concurrency?: number;
+  concurrency?: number | "unbounded";
   /**
    * Per-item retry policy, reusing the workflow {@link RetryConfig}
    * semantics (attempts, backoff, `retryOn`, `onRetry`). Applied

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,2BAyC0B;EAvC1B,KAAA,EAAO,eAAA,CAAgB,OAAA,KA8Cd;EA5CT,MAAA,EAAQ,WAAA;AAAA;;;;;;;;;;KAYE,gBAAA,iBAAiC,UAAA,GAAa,aAAA,KACxD,IAAA,EAAM,eAAA,CAAgB,OAAA,aACZ,OAAA;;;;;AAsCN;;KA9BM,YAAA,iBAA6B,UAAA,GAAa,aAAA;;;;;;EAMpD,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":["../../../../../../../@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"}

package/esm/config.d.mts

@@ -23,8 +23,25 @@ import { CacheDriver } from "@warlock.js/cache";
  * Phase 3.2 deliberately removed the previous `configureAI()` bag
  * because it was growing unbounded. Treat new fields here with the
  * same suspicion.
+ *
+ * **Augmentable.** Declared as an `interface` (not a `type` alias) so
+ * observability/tooling packages can attach their own opaque config slot
+ * via declaration merging WITHOUT core importing them — keeping core
+ * dependency-free. For example `@warlock.js/ai-panoptic` adds a
+ * `panoptic?` field:
+ *
+ * ```ts
+ * declare module "@warlock.js/ai" {
+ *   interface AIConfig {
+ *     panoptic?: PanopticConfig;
+ *   }
+ * }
+ * ```
+ *
+ * `setAIConfig` stores the whole object via `Object.assign`, so any
+ * augmented field is preserved even though core never reads it.
  */
-type AIConfig = {
+interface AIConfig {
   /**
    * Default `@warlock.js/cache` driver for cache-backed consumers that
    * didn't supply their own `store` — currently the `semanticCache`
@@ -75,7 +92,26 @@ type AIConfig = {
    * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });
    */
   defaultSnapshotStore?: SnapshotStore;
-};
+}
+/** A listener notified after every `setAIConfig` merge. */
+type ConfigListener = (config: AIConfig) => void;
+/**
+ * Subscribe to config changes. The listener fires after every
+ * {@link setAIConfig} merge with a fresh snapshot of the full config —
+ * the seam observability/tooling packages use to react when their
+ * augmented slot (e.g. `panoptic`) is set, WITHOUT core importing them.
+ *
+ * Mirrors the dependency-inversion of the `Observer` registry: core
+ * exposes the structural hook; the tool subscribes on its side-effect
+ * import. To also catch config that was applied *before* the subscription,
+ * read {@link getAIConfig} once right after subscribing.
+ *
+ * @example
+ * import { onConfigApplied, getAIConfig } from "@warlock.js/ai";
+ * onConfigApplied((config) => applyPanopticConfig(config.panoptic));
+ * applyPanopticConfig(getAIConfig().panoptic); // catch pre-set config
+ */
+declare function onConfigApplied(listener: ConfigListener): void;
 /**
  * Set or extend process-wide AI configuration. Merges over existing
  * values — fields not present in `partial` keep whatever was set
@@ -122,5 +158,5 @@ declare function resolveDefaultCheckpointStore(): CheckpointStore | undefined;
  */
 declare function resolveDefaultSnapshotStore(): SnapshotStore | undefined;
 //#endregion
-export { AIConfig, getAIConfig, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig };
+export { AIConfig, getAIConfig, onConfigApplied, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig };
 //# sourceMappingURL=config.d.mts.map

package/esm/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"mappings":";;;;;;;AAyBA;;;;;;;;;;;;;;;AAoDsC;AAoBtC;;;KAxEY,QAAA;EAwEyB;;;;;;;;;AAA4B;AAUjE;;;;AAAuC;AAYvC;;;;AAAkD;AAUlD;;;EAhFE,YAAA,GAAe,WAAA;EAgF+C;AAUhE;;;;AAA4D;;;;;;;EA5E1D,sBAAA,GAAyB,eAAA;;;;;;;;;;;;;EAczB,oBAAA,GAAuB,aAAA;AAAA;;;;;;;;;;;;;;;;iBAoBT,WAAA,CAAY,OAAA,EAAS,OAAA,CAAQ,QAAA,IAAY,QAAA;;;;;;iBAUzC,WAAA,IAAe,QAAQ;;;;;;;;;iBAYvB,mBAAA,IAAuB,WAAW;;;;;;;iBAUlC,6BAAA,IAAiC,eAAe;;;;;;;iBAUhD,2BAAA,IAA+B,aAAa"}
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"mappings":";;;;;;;AA0CA;;;;;;;;;;;;;;;AAoDsC;AACrC;;;;AAKsC;AAoBvC;;;;AAAwD;AAmBxD;;;;;;;;;;UAjGiB,QAAA;EAiGwC;;AAAQ;AAuBjE;;;;AAAuC;AAYvC;;;;AAAkD;AAUlD;;;;AAAgE;AAUhE;;;;AAA4D;EAhI1D,YAAA,GAAe,WAAA;;;;;;;;;;;;;EAcf,sBAAA,GAAyB,eAAA;;;;;;;;;;;;;EAczB,oBAAA,GAAuB,aAAA;AAAA;;KAMpB,cAAA,IAAkB,MAAgB,EAAR,QAAQ;;;;;;;;;;;;;;;;;iBAoBvB,eAAA,CAAgB,QAAwB,EAAd,cAAc;;;;;;;;;;;;;;;;iBAmBxC,WAAA,CAAY,OAAA,EAAS,OAAA,CAAQ,QAAA,IAAY,QAAA;;;;;;iBAuBzC,WAAA,IAAe,QAAQ;;;;;;;;;iBAYvB,mBAAA,IAAuB,WAAW;;;;;;;iBAUlC,6BAAA,IAAiC,eAAe;;;;;;;iBAUhD,2BAAA,IAA+B,aAAa"}

package/esm/config.mjs

@@ -1,5 +1,25 @@
 //#region ../@warlock.js/ai/src/config.ts
 const aiConfig = {};
+const configListeners = [];
+/**
+* Subscribe to config changes. The listener fires after every
+* {@link setAIConfig} merge with a fresh snapshot of the full config —
+* the seam observability/tooling packages use to react when their
+* augmented slot (e.g. `panoptic`) is set, WITHOUT core importing them.
+*
+* Mirrors the dependency-inversion of the `Observer` registry: core
+* exposes the structural hook; the tool subscribes on its side-effect
+* import. To also catch config that was applied *before* the subscription,
+* read {@link getAIConfig} once right after subscribing.
+*
+* @example
+* import { onConfigApplied, getAIConfig } from "@warlock.js/ai";
+* onConfigApplied((config) => applyPanopticConfig(config.panoptic));
+* applyPanopticConfig(getAIConfig().panoptic); // catch pre-set config
+*/
+function onConfigApplied(listener) {
+	configListeners.push(listener);
+}
 /**
 * Set or extend process-wide AI configuration. Merges over existing
 * values — fields not present in `partial` keep whatever was set
@@ -17,7 +37,11 @@ const aiConfig = {};
 */
 function setAIConfig(partial) {
 	Object.assign(aiConfig, partial);
-	return { ...aiConfig };
+	const snapshot = { ...aiConfig };
+	for (const listener of configListeners) try {
+		listener(snapshot);
+	} catch {}
+	return snapshot;
 }
 /**
 * Read the current AI config snapshot. Returns a shallow copy so
@@ -58,5 +82,5 @@ function resolveDefaultSnapshotStore() {
 }
 
 //#endregion
-export { getAIConfig, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig };
+export { getAIConfig, onConfigApplied, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig };
 //# sourceMappingURL=config.mjs.map

package/esm/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { CheckpointStore } from \"./contracts/orchestrator/checkpoint-store.contract\";\nimport type { SnapshotStore } from \"./contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n */\nexport type AIConfig = {\n  /**\n   * Default `@warlock.js/cache` driver for cache-backed consumers that\n   * didn't supply their own `store` — currently the `semanticCache`\n   * middleware's vector store. Declaring it once here removes the\n   * repetition across middleware declarations.\n   *\n   * NOT the snapshot-persistence fallback anymore. Supervisor /\n   * workflow / orchestrator resume snapshots resolve through\n   * {@link AIConfig.defaultSnapshotStore} (a {@link SnapshotStore}),\n   * never this driver.\n   *\n   * Per-declaration overrides (`semanticCache({ store })`) win when\n   * supplied. Set this once at app boot, *after* you've constructed\n   * your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n\n  /**\n   * Default {@link CheckpointStore} for every orchestrator that didn't\n   * supply its own `checkpointStore` (orchestrator.md §15.2). Holds\n   * durable session state — `state`, `turn_index`, drift `signature`,\n   * compaction locks. Per-orchestrator `checkpointStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultCheckpointStore: ai.checkpoint.memory() });\n   */\n  defaultCheckpointStore?: CheckpointStore;\n\n  /**\n   * Default {@link SnapshotStore} for every orchestrator that didn't\n   * supply its own `snapshotStore` (orchestrator.md §15.2). Holds the\n   * internal supervisor run state used to resume an interrupted\n   * `iterate: true` turn. Per-orchestrator `snapshotStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });\n   */\n  defaultSnapshotStore?: SnapshotStore;\n};\n\nconst aiConfig: AIConfig = {};\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  return { ...aiConfig };\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective `@warlock.js/cache` driver for a cache-backed\n * consumer that didn't receive an explicit one. Returns the global\n * `defaultStore` if set, otherwise `undefined`. The semantic-cache\n * middleware treats `undefined` as fatal and throws. Snapshot\n * persistence no longer consults this — it resolves through\n * {@link resolveDefaultSnapshotStore}.\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n\n/**\n * Resolve the global default {@link CheckpointStore} for an\n * orchestrator that didn't receive an explicit `checkpointStore`.\n * Returns `undefined` when none is configured — the orchestrator\n * factory decides whether that's fatal.\n */\nexport function resolveDefaultCheckpointStore(): CheckpointStore | undefined {\n  return aiConfig.defaultCheckpointStore;\n}\n\n/**\n * Resolve the global default {@link SnapshotStore} for an orchestrator\n * that didn't receive an explicit `snapshotStore`. Returns `undefined`\n * when none is configured — the orchestrator factory decides whether\n * that's fatal (it is, when `iterate: true`).\n */\nexport function resolveDefaultSnapshotStore(): SnapshotStore | undefined {\n  return aiConfig.defaultSnapshotStore;\n}\n"],"mappings":";AAgFA,MAAM,WAAqB,CAAC;;;;;;;;;;;;;;;;AAiB5B,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;AAOA,SAAgB,cAAwB;CACtC,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;;;;AAUA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,gCAA6D;CAC3E,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,8BAAyD;CACvE,OAAO,SAAS;AAClB"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { CheckpointStore } from \"./contracts/orchestrator/checkpoint-store.contract\";\nimport type { SnapshotStore } from \"./contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n *\n * **Augmentable.** Declared as an `interface` (not a `type` alias) so\n * observability/tooling packages can attach their own opaque config slot\n * via declaration merging WITHOUT core importing them — keeping core\n * dependency-free. For example `@warlock.js/ai-panoptic` adds a\n * `panoptic?` field:\n *\n * ```ts\n * declare module \"@warlock.js/ai\" {\n *   interface AIConfig {\n *     panoptic?: PanopticConfig;\n *   }\n * }\n * ```\n *\n * `setAIConfig` stores the whole object via `Object.assign`, so any\n * augmented field is preserved even though core never reads it.\n */\nexport interface AIConfig {\n  /**\n   * Default `@warlock.js/cache` driver for cache-backed consumers that\n   * didn't supply their own `store` — currently the `semanticCache`\n   * middleware's vector store. Declaring it once here removes the\n   * repetition across middleware declarations.\n   *\n   * NOT the snapshot-persistence fallback anymore. Supervisor /\n   * workflow / orchestrator resume snapshots resolve through\n   * {@link AIConfig.defaultSnapshotStore} (a {@link SnapshotStore}),\n   * never this driver.\n   *\n   * Per-declaration overrides (`semanticCache({ store })`) win when\n   * supplied. Set this once at app boot, *after* you've constructed\n   * your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n\n  /**\n   * Default {@link CheckpointStore} for every orchestrator that didn't\n   * supply its own `checkpointStore` (orchestrator.md §15.2). Holds\n   * durable session state — `state`, `turn_index`, drift `signature`,\n   * compaction locks. Per-orchestrator `checkpointStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultCheckpointStore: ai.checkpoint.memory() });\n   */\n  defaultCheckpointStore?: CheckpointStore;\n\n  /**\n   * Default {@link SnapshotStore} for every orchestrator that didn't\n   * supply its own `snapshotStore` (orchestrator.md §15.2). Holds the\n   * internal supervisor run state used to resume an interrupted\n   * `iterate: true` turn. Per-orchestrator `snapshotStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });\n   */\n  defaultSnapshotStore?: SnapshotStore;\n};\n\nconst aiConfig: AIConfig = {};\n\n/** A listener notified after every `setAIConfig` merge. */\ntype ConfigListener = (config: AIConfig) => void;\n\nconst configListeners: ConfigListener[] = [];\n\n/**\n * Subscribe to config changes. The listener fires after every\n * {@link setAIConfig} merge with a fresh snapshot of the full config —\n * the seam observability/tooling packages use to react when their\n * augmented slot (e.g. `panoptic`) is set, WITHOUT core importing them.\n *\n * Mirrors the dependency-inversion of the `Observer` registry: core\n * exposes the structural hook; the tool subscribes on its side-effect\n * import. To also catch config that was applied *before* the subscription,\n * read {@link getAIConfig} once right after subscribing.\n *\n * @example\n * import { onConfigApplied, getAIConfig } from \"@warlock.js/ai\";\n * onConfigApplied((config) => applyPanopticConfig(config.panoptic));\n * applyPanopticConfig(getAIConfig().panoptic); // catch pre-set config\n */\nexport function onConfigApplied(listener: ConfigListener): void {\n  configListeners.push(listener);\n}\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  const snapshot = { ...aiConfig };\n\n  // Notify subscribers (e.g. panoptic) after the merge. Errors are\n  // swallowed so a misbehaving listener never breaks config application,\n  // mirroring the observer / onUsage swallow-on-throw discipline.\n  for (const listener of configListeners) {\n    try {\n      listener(snapshot);\n    } catch {\n      // intentionally ignored\n    }\n  }\n\n  return snapshot;\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective `@warlock.js/cache` driver for a cache-backed\n * consumer that didn't receive an explicit one. Returns the global\n * `defaultStore` if set, otherwise `undefined`. The semantic-cache\n * middleware treats `undefined` as fatal and throws. Snapshot\n * persistence no longer consults this — it resolves through\n * {@link resolveDefaultSnapshotStore}.\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n\n/**\n * Resolve the global default {@link CheckpointStore} for an\n * orchestrator that didn't receive an explicit `checkpointStore`.\n * Returns `undefined` when none is configured — the orchestrator\n * factory decides whether that's fatal.\n */\nexport function resolveDefaultCheckpointStore(): CheckpointStore | undefined {\n  return aiConfig.defaultCheckpointStore;\n}\n\n/**\n * Resolve the global default {@link SnapshotStore} for an orchestrator\n * that didn't receive an explicit `snapshotStore`. Returns `undefined`\n * when none is configured — the orchestrator factory decides whether\n * that's fatal (it is, when `iterate: true`).\n */\nexport function resolveDefaultSnapshotStore(): SnapshotStore | undefined {\n  return aiConfig.defaultSnapshotStore;\n}\n"],"mappings":";AAiGA,MAAM,WAAqB,CAAC;AAK5B,MAAM,kBAAoC,CAAC;;;;;;;;;;;;;;;;;AAkB3C,SAAgB,gBAAgB,UAAgC;CAC9D,gBAAgB,KAAK,QAAQ;AAC/B;;;;;;;;;;;;;;;;AAiBA,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,MAAM,WAAW,EAAE,GAAG,SAAS;CAK/B,KAAK,MAAM,YAAY,iBACrB,IAAI;EACF,SAAS,QAAQ;CACnB,QAAQ,CAER;CAGF,OAAO;AACT;;;;;;AAOA,SAAgB,cAAwB;CACtC,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;;;;AAUA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,gCAA6D;CAC3E,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,8BAAyD;CACvE,OAAO,SAAS;AAClB"}

package/esm/contracts/agent/agent-options.type.d.mts

@@ -1,3 +1,4 @@
+import { AttachmentPolicy } from "../attachment-policy.type.mjs";
 import { Attachment } from "../attachment.type.mjs";
 import { Message } from "../conversation-message.type.mjs";
 import { ToolContext } from "../tool.contract.mjs";
@@ -12,9 +13,9 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * Options passed to AgentContract.execute() to configure a single execution run.
  *
  * @example
- * const result = await agent.execute("Analyze this document", {
+ * const result = await agent.execute("Describe this image", {
  *   history: previousMessages,
- *   attachments: ["/path/to/doc.pdf"],
+ *   attachments: ["/path/to/screenshot.png"],
  *   placeholders: { language: "English" },
  *   output: z.object({ summary: z.string(), keyPoints: z.array(z.string()) }),
  *   on: {
@@ -24,8 +25,23 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * });
  */
 type AgentExecuteOptions<TOutput = unknown> = {
-  /** Prior conversation messages to prepend as context */history?: Message[]; /** Files or URLs to attach to the message */
-  attachments?: Attachment[]; /** Values to inject into {{mustache}} placeholders in prompts */
+  /**
+   * Caller-chosen stable run identifier. Auto-generated (`agent_<rand>`)
+   * when omitted. Load-bearing for durable resume: when `durable` is on,
+   * pass a stable `runId` here (or read the generated one off
+   * `result.report.runId`) so a later `agent.resume(runId)` can find the
+   * snapshot. Mirrors `SupervisorExecuteOptions.runId`.
+   */
+  runId?: string; /** Prior conversation messages to prepend as context */
+  history?: Message[]; /** Files or URLs to attach to the message */
+  attachments?: Attachment[];
+  /**
+   * Trust-boundary policy for {@link attachments} (S1) — overrides
+   * `AgentConfig.attachmentPolicy` for this call. Governs remote-text
+   * fetch (default-deny), the outbound `OutboundPolicy`, and the local-
+   * file `allowedRoots` sandbox. Omit to inherit the factory policy.
+   */
+  attachmentPolicy?: AttachmentPolicy; /** Values to inject into {{mustache}} placeholders in prompts */
   placeholders?: Placeholders;
   /**
    * Standard Schema for structured output extraction.
@@ -127,6 +143,18 @@ type AgentExecuteOptions<TOutput = unknown> = {
    */
   sessionId?: string;
 };
+/**
+ * Options accepted by `agent.resume(runId, options?)`.
+ *
+ * `force: true` bypasses the signature drift check — use only when you
+ * have verified the definition change is safe for the in-flight
+ * snapshot. `AgentDriftError` is otherwise thrown without executing
+ * anything. Everything else mirrors {@link AgentExecuteOptions} (e.g.
+ * re-supply a `signal` to keep the resumed run cancellable).
+ */
+type AgentResumeOptions<TOutput = unknown> = AgentExecuteOptions<TOutput> & {
+  /** Bypass the drift check and resume against the changed definition. */force?: boolean;
+};
 //#endregion
-export { AgentExecuteOptions };
+export { AgentExecuteOptions, AgentResumeOptions };
 //# sourceMappingURL=agent-options.type.d.mts.map

package/esm/contracts/agent/agent-options.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-options.type.ts"],"mappings":";;;;;;;;;;;;AAwBA;;;;;;;;;;;;;KAAY,mBAAA;EA2EL,wDAzEL,OAAA,GAAU,OAAA,IA+FW;EA7FrB,WAAA,GAAc,UAAA,IA6F+B;EA3F7C,YAAA,GAAe,YAAA;EAJf;;;;EASA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EALX;;;;;;;;;;;;;;;;;;;;;;;;EA8Bf,cAAA,GAAiB,MAAA;EA0ER;;;;;;;;;;;;;;;;;;;;EArDT,MAAA;8EAEE,WAAA;EAAA;EAGF,YAAA,GAAe,oBAAA;;;;;;;;;;;EAWf,MAAA,GAAS,WAAA;EAET,EAAA,GAAK,OAAA,eACS,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;EAatD,OAAA,GAAU,WAAA;;;;;;;;EAQV,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;EAarB,SAAA;AAAA"}
+{"version":3,"file":"agent-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-options.type.ts"],"mappings":";;;;;;;;;;;;;AAyBA;;;;;;;;;;;;;KAAY,mBAAA;EA2F4C;;;;;;;EAnFtD,KAAA,WAEA;EAAA,OAAA,GAAU,OAAA,IAEV;EAAA,WAAA,GAAc,UAAA;EAOd;;;;;;EAAA,gBAAA,GAAmB,gBAAA,EAgCnB;EA9BA,YAAA,GAAe,YAAA;EAmDf;;;;EA9CA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EA8DjB;;;;;;;;;;;;;;AAqCA;AAYX;;;;;;;;;EAtFE,cAAA,GAAiB,MAAA;;;;;;;;;;;;;;;;;;;;;EAqBjB,MAAA;8EAEE,WAAA;EAAA;EAGF,YAAA,GAAe,oBAAA;;;;;;;;;;;EAWf,MAAA,GAAS,WAAA;EAET,EAAA,GAAK,OAAA,eACS,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;EAatD,OAAA,GAAU,WAAA;;;;;;;;EAQV,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;EAarB,SAAA;AAAA;;;;;;;;;;KAYU,kBAAA,sBAAwC,mBAAmB,CAAC,OAAA;0EAEtE,KAAA;AAAA"}

package/esm/contracts/agent/agent-snapshot.type.d.mts

@@ -0,0 +1,90 @@
+import { Message } from "../conversation-message.type.mjs";
+import { Usage } from "../result/usage.type.mjs";
+import { ToolCall } from "../result/tool-call.type.mjs";
+import { LLMTrip } from "../result/llm-trip.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/agent/agent-snapshot.type.d.ts
+/**
+ * Lifecycle status of a durable agent run, recorded on the persisted
+ * snapshot so `resume()` can decide whether a run is still in flight.
+ *
+ * - `"running"` — the trip loop is active; a resume is legitimate if
+ *   the process crashed between trip boundaries.
+ * - `"completed"` — the agent terminated successfully; resume is a
+ *   no-op and re-returns the final result rebuilt from the snapshot.
+ * - `"cancelled"` — aborted via `AbortSignal`; resume is allowed (the
+ *   caller decides whether to retry).
+ * - `"failed"` — terminated with an error; resume after the fix.
+ */
+type AgentSnapshotStatus = "running" | "completed" | "cancelled" | "failed";
+/**
+ * Persisted shape written to the configured {@link
+ * import("../orchestrator/snapshot-store.contract").SnapshotStore} after
+ * every trip settles. Exists so `agent.resume(runId)` can re-hydrate the
+ * assembled conversation + completed trips + tool calls + running usage
+ * and continue the trip loop from the next `tripIndex`.
+ *
+ * **Checkpoint granularity is per-trip.** The snapshot is written at the
+ * end of `runTrip`, after every tool the trip requested has been
+ * dispatched and its result message appended — the only point in the
+ * loop where `messages`, `trips`, `toolCalls`, and `usage` are mutually
+ * consistent. A crash mid-trip loses only that in-flight trip (never
+ * checkpointed), which the resumed run re-issues cleanly.
+ *
+ * `signature` is a structural fingerprint covering model + provider +
+ * sorted tool names + maxTrips + output presence + version (see
+ * {@link import("../../agent/signature").computeAgentSignature}).
+ * `resume()` compares it against the current agent's signature; a
+ * mismatch throws `AgentDriftError` (bypassable with `{ force: true }`).
+ *
+ * Every field is JSON-serializable — `Message`, `LLMTrip`, `ToolCall`,
+ * and `Usage` are the same plain-data shapes already persisted on
+ * reports, so the snapshot round-trips through any `SnapshotStore`
+ * backend (`memory`, `pg`, `redis`) verbatim.
+ *
+ * @example
+ * const snapshot: AgentSnapshot | undefined = await store.load(runId);
+ * if (snapshot?.status === "running") {
+ *   await agent.resume(runId);
+ * }
+ */
+type AgentSnapshot = {
+  /** The store key — stable across the whole run. */runId: string; /** Resolved agent name, for the resume error message + attribution. */
+  agentName: string; /** Structural drift fingerprint (see `computeAgentSignature`). */
+  signature: string; /** `AgentConfig.version` — metadata only, never compared. */
+  version?: string; /** The original `execute(input)` value — needed to rebuild context. */
+  input: string;
+  /**
+   * The resolved system-prompt text captured once on the first run, so
+   * a resume skips `buildInitialMessages` (the messages array already
+   * holds the system turn). Absent when the agent had no prompt.
+   */
+  systemPrompt?: string;
+  /**
+   * The wire-level JSON Schema sent to the model for structured output,
+   * captured so resume re-issues continuation trips with the identical
+   * response contract. Absent when the agent produced untyped output.
+   */
+  responseSchema?: Record<string, unknown>; /** Registry name of the resolved named prompt, when one was used. */
+  promptName?: string; /** Registry version label paired with {@link AgentSnapshot.promptName}. */
+  promptVersion?: string;
+  /**
+   * The live conversation array — assistant turns (with `toolCalls`)
+   * plus tool-result turns — assembled across the persisted trips.
+   * Re-hydrated verbatim so the next trip sees the full history.
+   */
+  messages: Message[];
+  /**
+   * Every settled trip so far. `trips.length` is the next `tripIndex`
+   * the resumed loop starts at, so completed trips never re-run.
+   */
+  trips: LLMTrip[]; /** Every settled tool dispatch (flat, each carrying its `tripIndex`). */
+  toolCalls: ToolCall[]; /** Running usage total across the persisted trips — never double-counted. */
+  usage: Usage;
+  status: AgentSnapshotStatus;
+  startedAt: string;
+  savedAt: string;
+};
+//#endregion
+export { AgentSnapshot, AgentSnapshotStatus };
+//# sourceMappingURL=agent-snapshot.type.d.mts.map

package/esm/contracts/agent/agent-snapshot.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-snapshot.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-snapshot.type.ts"],"mappings":";;;;;;;;AAiBA;;;;AAA+B;AAqC/B;;;;;KArCY,mBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFH;;;KA5CG,aAAA;qDAEV,KAAA;EAEA,SAAA;EAEA,SAAA;EAEA,OAAA;EAEA,KAAA;;;;;;EAMA,YAAA;;;;;;EAMA,cAAA,GAAiB,MAAA;EAEjB,UAAA;EAEA,aAAA;;;;;;EAMA,QAAA,EAAU,OAAA;;;;;EAKV,KAAA,EAAO,OAAA;EAEP,SAAA,EAAW,QAAA;EAEX,KAAA,EAAO,KAAA;EACP,MAAA,EAAQ,mBAAA;EACR,SAAA;EACA,OAAA;AAAA"}

package/esm/contracts/agent/agent.contract.d.mts

@@ -3,7 +3,7 @@ import { ExecutableContract } from "../executable.contract.mjs";
 import { StreamContract } from "../stream/stream.contract.mjs";
 import { EvalOptions, EvalReport } from "./eval.type.mjs";
 import { AgentEventMap } from "../events/event-map.type.mjs";
-import { AgentExecuteOptions } from "./agent-options.type.mjs";
+import { AgentExecuteOptions, AgentResumeOptions } from "./agent-options.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/agent/agent.contract.d.ts
 /**
@@ -71,11 +71,39 @@ interface AgentContract<TOutput = unknown> extends ExecutableContract<string, Ag
    * `AgentConfig.description` at factory time.
    */
   readonly description?: string;
+  /**
+   * Structural drift fingerprint of the agent definition — model +
+   * provider + sorted tool names + maxTrips + output presence + version.
+   * Stamped on every durable snapshot and compared on `resume()`; a
+   * mismatch throws `AgentDriftError`. Always populated (computed at
+   * factory time), independent of whether `durable` is configured.
+   */
+  readonly signature: string;
   /**
    * Stream execution events in real time.
    * Yields typed StreamEvent values and resolves result when done.
    */
   stream(input: string, options?: AgentExecuteOptions<TOutput>): StreamContract<AgentResult<TOutput>>;
+  /**
+   * Resume a durable run after a crash. Loads the snapshot persisted
+   * under `runId` (requires `durable` on the config, or a global
+   * `defaultSnapshotStore`), re-hydrates the completed trips + tool
+   * calls + usage, and continues the trip loop from the next trip —
+   * never re-issuing a completed trip's model call or re-invoking its
+   * tools. A resume of an already-settled run re-returns the stored
+   * result without running anything.
+   *
+   * Refuses to continue when the current definition has structurally
+   * drifted from the snapshot (`AgentDriftError`), unless
+   * `{ force: true }` is passed. Throws `AgentExecutionError` when no
+   * store is configured or no snapshot exists for `runId`.
+   *
+   * @example
+   * const result = await writer.execute("research X", { runId: "run-42" });
+   * // ...process crashes mid-run...
+   * const recovered = await writer.resume("run-42");
+   */
+  resume(runId: string, options?: AgentResumeOptions<TOutput>): Promise<AgentResult<TOutput>>;
   /**
    * Subscribe a handler to a single event name for the lifetime of
    * this agent instance. Returns an unsubscribe function; calling it

package/esm/contracts/agent/agent.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent.contract.ts"],"mappings":";;;;;;;;;;AAWA;;KAAY,iBAAA,iBAAkC,aAAA,KAC5C,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AAyC3B;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA,4BAAyC,kBAAA,SAExD,mBAAA,CAAoB,OAAA,GACpB,WAAA,CAAY,OAAA;EAH8D;;;;;;;;EAAA,SAajE,IAAA;EAMA;;;;;EAAA,SAAA,WAAA;EAaP;;;;;EAAA,SAPO,WAAA;EAeU;;;;EAVnB,MAAA,CACE,KAAA,UACA,OAAA,GAAU,mBAAA,CAAoB,OAAA,IAC7B,cAAA,CAAe,WAAA,CAAY,OAAA;EAS5B;;;;;EAFF,EAAA,iBAAmB,aAAA,EACjB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;EASlB;;;;EAFX,GAAA,iBAAoB,aAAA,EAClB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;EA4ChB;;;;;;;;AAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA5E,IAAA,SAAa,OAAA,EAAS,OAAA,EAAS,WAAA,CAAY,KAAA,IAAS,OAAA,CAAQ,UAAA,CAAW,KAAA;AAAA"}
+{"version":3,"file":"agent.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent.contract.ts"],"mappings":";;;;;;;;;;AAWA;;KAAY,iBAAA,iBAAkC,aAAA,KAC5C,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AAyC3B;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA,4BAAyC,kBAAA,SAExD,mBAAA,CAAoB,OAAA,GACpB,WAAA,CAAY,OAAA;EA4HmB;;;;;;;;EAAA,SAlHtB,IAAA;EAXT;;;;;EAAA,SAiBS,WAAA;EAMA;;;;;EAAA,SAAA,WAAA;EAeP;;;;;;;EAAA,SAPO,SAAA;EA+BP;;;;EA1BF,MAAA,CACE,KAAA,UACA,OAAA,GAAU,mBAAA,CAAoB,OAAA,IAC7B,cAAA,CAAe,WAAA,CAAY,OAAA;EA+B3B;;;;;;;;;;;;;;;;;;;EAVH,MAAA,CACE,KAAA,UACA,OAAA,GAAU,kBAAA,CAAmB,OAAA,IAC5B,OAAA,CAAQ,WAAA,CAAY,OAAA;EA8DD;;;;;EAvDtB,EAAA,iBAAmB,aAAA,EACjB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;;;;;EAO7B,GAAA,iBAAoB,aAAA,EAClB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4C7B,IAAA,SAAa,OAAA,EAAS,OAAA,EAAS,WAAA,CAAY,KAAA,IAAS,OAAA,CAAQ,UAAA,CAAW,KAAA;AAAA"}

package/esm/contracts/agent/eval.type.d.mts

@@ -1,4 +1,5 @@
 import { AgentResult } from "../result/agent-result.type.mjs";
+import { DatasetContract } from "../../eval/dataset.type.mjs";
 import { AgentContract } from "./agent.contract.mjs";
 import { AgentExecuteOptions } from "./agent-options.type.mjs";
 
@@ -92,7 +93,12 @@ type EvalJudge = {
  * resolvable per case or the runner throws at author time.
  */
 type EvalOptions<TOutput = unknown> = {
-  /** The evaluation cases to run. */cases: EvalCase<TOutput>[]; /** Default scorers applied to every case without its own `scorers`. */
+  /**
+   * The evaluation cases to run. Either a raw `EvalCase[]` or a
+   * {@link DatasetContract} (from `ai.dataset(...)`) — the runner reads
+   * `.cases` off a dataset.
+   */
+  cases: EvalCase<TOutput>[] | DatasetContract<TOutput>; /** Default scorers applied to every case without its own `scorers`. */
   scorers?: EvalScorer<TOutput>[]; /** LLM-as-judge fallback for cases with no scorers. */
   judge?: EvalJudge;
   /**
@@ -108,6 +114,36 @@ type EvalOptions<TOutput = unknown> = {
    */
   onFailure?: (caseResult: EvalCaseResult<TOutput>) => void | Promise<void>; /** Execute-options applied to every case (merged under per-case `options`). */
   executeOptions?: AgentExecuteOptions<TOutput>;
+  /**
+   * A prior {@link EvalReport} to diff against. When set, the new report
+   * carries a `regression` block flagging cases whose score dropped more
+   * than `tolerance` below the baseline.
+   */
+  baseline?: EvalReport<TOutput>;
+  /**
+   * Maximum allowed per-case score drop vs baseline before it counts as a
+   * regression. Only consulted when `baseline` is set. Defaults to `0`
+   * (any drop is a regression).
+   */
+  tolerance?: number;
+};
+/**
+ * Regression verdict attached to an {@link EvalReport} when `agent.eval`
+ * is called with a `baseline`. Cases are joined by `name`.
+ */
+type EvalRegression = {
+  /**
+   * Cases whose score fell more than `tolerance` below the baseline,
+   * carrying the before/after scores.
+   */
+  regressed: Array<{
+    name: string;
+    before: number;
+    after: number;
+  }>; /** Case names present in the baseline but absent in the new report. */
+  removed: string[]; /** Case names present in the new report but absent in the baseline. */
+  added: string[]; /** `true` when `regressed` is empty — no case regressed beyond tolerance. */
+  passed: boolean;
 };
 /**
  * Per-case outcome in an {@link EvalReport}. Bundles the case, the
@@ -137,7 +173,12 @@ type EvalReport<TOutput = unknown> = {
   passed: boolean; /** Per-case results in suite order. */
   cases: EvalCaseResult<TOutput>[]; /** Total wall-clock duration of the whole suite in milliseconds. */
   duration: number;
+  /**
+   * Regression diff vs a baseline. Present only when `agent.eval` was
+   * called with a `baseline`.
+   */
+  regression?: EvalRegression;
 };
 //#endregion
-export { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalReport, EvalScore, EvalScorer, EvalScorerContext };
+export { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalRegression, EvalReport, EvalScore, EvalScorer, EvalScorerContext };
 //# sourceMappingURL=eval.type.d.mts.map