@warlock.js/ai 4.4.0 → 4.5.0

package/esm/ai.d.mts

@@ -2,16 +2,23 @@ import { tool } from "./tool/tool.mjs";
 import { agent } from "./agent/agent.mjs";
 import { budget, readBudgetFallbackSignal } from "./middleware/builtins/budget.mjs";
 import { spawnSubAgent } from "./agent/spawn-sub-agent.mjs";
-import { SystemPromptFactory } from "./system-prompt/system-prompt.mjs";
-import { judge } from "./eval/judge-scorer.mjs";
-import { contains, exact, predicate } from "./eval/scorers.mjs";
 import { batch } from "./batch/batch.mjs";
+import { streamObject } from "./object-stream/stream-object.mjs";
+import { serve } from "./serve/serve.mjs";
 import { memory } from "./checkpoint/memory.mjs";
 import { pg } from "./checkpoint/pg.mjs";
 import { redis } from "./checkpoint/redis.mjs";
 import { setAIConfig } from "./config.mjs";
-import { memory as memory$1 } from "./memory/memory.mjs";
-import { guardrail } from "./middleware/builtins/guardrail.mjs";
+import { dataset } from "./eval/dataset.mjs";
+import { evalScorers } from "./eval/index.mjs";
+import { humanApproval } from "./human/human-approval.mjs";
+import { resume } from "./human/resume.mjs";
+import { memory as memory$1 } from "./human/stores/memory.mjs";
+import { pg as pg$1 } from "./human/stores/pg.mjs";
+import { redis as redis$1 } from "./human/stores/redis.mjs";
+import { guardrail } from "./guard/guardrail.mjs";
+import { memory as memory$2 } from "./memory/memory.mjs";
+import { guardrail as guardrail$1 } from "./middleware/builtins/guardrail.mjs";
 import { semanticCache } from "./middleware/builtins/semantic-cache.mjs";
 import { composeMiddleware } from "./middleware/helpers/compose.mjs";
 import { forTool } from "./middleware/helpers/for-tool.mjs";
@@ -19,18 +26,117 @@ import { mockRouter } from "./mock/mock-router.mjs";
 import { fallbackModel } from "./model/fallback-model.mjs";
 import { orchestrator } from "./orchestrator/orchestrator.mjs";
 import { planner } from "./planner/planner.mjs";
-import { memory as memory$2 } from "./snapshot/memory.mjs";
-import { pg as pg$1 } from "./snapshot/pg.mjs";
-import { redis as redis$1 } from "./snapshot/redis.mjs";
+import { defaultPromptsManager } from "./prompts/prompts-manager.mjs";
+import { rag } from "./rag/rag.mjs";
+import { keywordReranker } from "./rag/rerank/keyword-reranker.mjs";
+import { llmReranker } from "./rag/rerank/llm-reranker.mjs";
+import { skills } from "./skills/skills.mjs";
+import { systemPrompt } from "./system-prompt/system-prompt.mjs";
+import { prompt } from "./prompt/prompt.mjs";
+import { vcr } from "./vcr/vcr.mjs";
+import { memory as memory$3 } from "./snapshot/memory.mjs";
+import { pg as pg$2 } from "./snapshot/pg.mjs";
+import { redis as redis$2 } from "./snapshot/redis.mjs";
 import { fanOut } from "./supervisor/fan-out.mjs";
 import { router } from "./supervisor/router-factory.mjs";
 import { supervisor } from "./supervisor/supervisor.mjs";
+import { team } from "./team/team.mjs";
 import { instruction } from "./system-prompt/instruction.mjs";
 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
+/**
+ * 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
+ * `declare module "@warlock.js/ai" { interface Ai { … } }` — e.g. `ai.workspace`,
+ * `ai.tools`, `ai.mcp`, `ai.human`. The runtime object below is asserted to this
+ * type; a satellite assigns its member on import.
+ */
+interface Ai {
+  config: typeof setAIConfig;
+  tool: typeof tool;
+  agent: typeof agent;
+  systemPrompt: typeof systemPrompt;
+  persona: typeof persona;
+  instruction: typeof instruction;
+  workflow: typeof workflow;
+  step: typeof step;
+  supervisor: typeof supervisor;
+  team: typeof team;
+  orchestrator: typeof orchestrator;
+  memory: typeof memory$2;
+  skills: typeof skills;
+  planner: typeof planner;
+  rag: typeof rag & {
+    keywordReranker: typeof keywordReranker;
+    llmReranker: typeof llmReranker;
+  };
+  spawnSubAgent: typeof spawnSubAgent;
+  router: typeof router;
+  fanOut: typeof fanOut;
+  batch: typeof batch;
+  /** Structured-output streaming — partial-object snapshots + a strict final parse (A1). */
+  streamObject: typeof streamObject;
+  /** Serve an executable as an SSE HTTP endpoint — production serving primitive (A3). */
+  serve: typeof serve;
+  fallbackModel: typeof fallbackModel;
+  eval: typeof evalScorers;
+  dataset: typeof dataset;
+  prompt: typeof prompt;
+  /**
+   * Process-wide registry of named, versioned `systemPrompt(...)` builders,
+   * keyed by `name@version`. A `systemPrompt(input, { name })` (or any
+   * `.meta({ name })` rename) auto-registers here; `ai.prompts.get(name)` /
+   * `.resolve(name)` reads them back, and `systemPrompt().merge(name)` folds a
+   * registered prompt into a new one.
+   */
+  prompts: ReturnType<typeof defaultPromptsManager>;
+  vcr: typeof vcr;
+  mockRouter: typeof mockRouter;
+  middleware: {
+    budget: typeof budget;
+    guardrail: typeof guardrail$1;
+    semanticCache: typeof semanticCache;
+    compose: typeof composeMiddleware;
+    forTool: typeof forTool;
+    readBudgetFallbackSignal: typeof readBudgetFallbackSignal;
+  };
+  checkpoint: {
+    memory: typeof memory;
+    pg: typeof pg;
+    redis: typeof redis;
+  };
+  snapshot: {
+    memory: typeof memory$3;
+    pg: typeof pg$2;
+    redis: typeof redis$2;
+  };
+  /**
+   * Human-in-the-loop tool approval (interrupt / resume).
+   *
+   * - `human.approval(options)` — the `tool.before` approval-gate middleware.
+   * - `human.resume(id, decision, options)` — out-of-process durable resume.
+   * - `human.interrupt.{memory,pg,redis}()` — durable {@link InterruptStore}
+   *   factories (memory ships real; pg/redis are lazy optional peers).
+   */
+  human: {
+    approval: typeof humanApproval;
+    resume: typeof resume;
+    interrupt: {
+      memory: typeof memory$1;
+      pg: typeof pg$1;
+      redis: typeof redis$1;
+    };
+  };
+  /**
+   * Content-intelligence guardrail. `ai.guardrail(options)` builds a composed
+   * input / output / tool middleware; `ai.guardrail.{pii,topic,injection,moderation}`
+   * are the built-in detector factories.
+   */
+  guardrail: typeof guardrail;
+}
 /**
  * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.
  *
@@ -42,6 +148,7 @@ import { workflow } from "./workflow/workflow.mjs";
  * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).
  * - `ai.orchestrator(...)` — session-state manager wrapped around a supervisor (durable session, drift detection, resume, commands).
  * - `ai.memory(...)` — build an agent-memory store with WORKING (in-run scratch) and SEMANTIC (cache-driver `.similar()` recall) tiers.
+ * - `ai.skills(...)` — build a runtime skills library (always-injected metadata catalog + on-demand loadSkill tool).
  * - `ai.planner(...)` — build an executable that generates an ordered plan over registered capabilities, then runs it step-by-step.
  * - `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).
  * - `ai.router(...)` — build a supervisor-compatible routing agent from named intents.
@@ -52,6 +159,8 @@ import { workflow } from "./workflow/workflow.mjs";
  * - `ai.mockRouter(decisions, opts?)` — deterministic supervisor `route` callback for tests.
  * - `ai.checkpoint.{memory,pg,redis}()` — durable orchestrator session checkpoint stores.
  * - `ai.snapshot.{memory,pg,redis}()` — supervisor-run snapshot stores for `iterate: true` resume.
+ * - `ai.human.approval(...)` / `ai.human.resume(...)` / `ai.human.interrupt.{memory,pg,redis}()` — human-in-the-loop tool approval (interrupt / resume).
+ * - `ai.guardrail(options)` + `ai.guardrail.{pii,topic,injection,moderation}(...)` — content-intelligence guardrails (moderation / PII / injection / topic).
  * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.
  *
  * @example
@@ -70,50 +179,7 @@ import { workflow } from "./workflow/workflow.mjs";
  *   placeholders: { language: "Arabic" },
  * });
  */
-declare const ai: {
-  config: typeof setAIConfig;
-  tool: typeof tool;
-  agent: typeof agent;
-  systemPrompt: SystemPromptFactory;
-  persona: typeof persona;
-  instruction: typeof instruction;
-  workflow: typeof workflow;
-  step: typeof step;
-  supervisor: typeof supervisor;
-  orchestrator: typeof orchestrator;
-  memory: typeof memory$1;
-  planner: typeof planner;
-  spawnSubAgent: typeof spawnSubAgent;
-  router: typeof router;
-  fanOut: typeof fanOut;
-  batch: typeof batch;
-  fallbackModel: typeof fallbackModel;
-  eval: {
-    exact: typeof exact;
-    contains: typeof contains;
-    predicate: typeof predicate;
-    judge: typeof judge;
-  };
-  mockRouter: typeof mockRouter;
-  middleware: {
-    budget: typeof budget;
-    guardrail: typeof guardrail;
-    semanticCache: typeof semanticCache;
-    compose: typeof composeMiddleware;
-    forTool: typeof forTool;
-    readBudgetFallbackSignal: typeof readBudgetFallbackSignal;
-  };
-  checkpoint: {
-    memory: typeof memory;
-    pg: typeof pg;
-    redis: typeof redis;
-  };
-  snapshot: {
-    memory: typeof memory$2;
-    pg: typeof pg$1;
-    redis: typeof redis$1;
-  };
-};
+declare const ai: Ai;
 //#endregion
-export { ai };
+export { Ai, ai };
 //# sourceMappingURL=ai.d.mts.map

package/esm/ai.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;;;;;cAAa,EAAA"}
+{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAuDiB,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;EAAA;EAEtB,aAAA,SAAsB,aAAA;EACtB,MAAA,SAAe,MAAA;EACf,MAAA,SAAe,MAAA;EACf,KAAA,SAAc,KAAA;EAnBA;EAqBd,YAAA,SAAqB,YAAA;EAnBL;EAqBhB,KAAA,SAAc,KAAA;EACd,aAAA,SAAsB,aAAA;EACtB,IAAA,SAAa,WAAA;EACb,OAAA,SAAgB,OAAA;EAChB,MAAA,SAAe,MAAA;EAnBM;;;;;;;EA2BrB,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;EANH;;;;;;;;EAgBb,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;EAtElB;;;;;EA8EA,SAAA,SAAkB,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6CP,EAAA,EAmDR,EAAE"}

package/esm/ai.mjs

@@ -5,15 +5,23 @@ import { semanticCache } from "./middleware/builtins/semantic-cache.mjs";
 import { composeMiddleware } from "./middleware/helpers/compose.mjs";
 import { forTool } from "./middleware/helpers/for-tool.mjs";
 import { tool } from "./tool/tool.mjs";
+import { skills } from "./skills/skills.mjs";
+import { memory } from "./memory/memory.mjs";
+import "./skills/index.mjs";
 import { agent } from "./agent/agent.mjs";
 import { spawnSubAgent } from "./agent/spawn-sub-agent.mjs";
 import { batch } from "./batch/batch.mjs";
 import "./batch/index.mjs";
-import { memory } from "./checkpoint/memory.mjs";
+import { streamObject } from "./object-stream/stream-object.mjs";
+import "./object-stream/index.mjs";
+import { serve } from "./serve/serve.mjs";
+import { memory as memory$1 } from "./checkpoint/memory.mjs";
 import { pg } from "./checkpoint/pg.mjs";
 import { redis } from "./checkpoint/redis.mjs";
+import { dataset } from "./eval/dataset.mjs";
 import { evalScorers } from "./eval/index.mjs";
-import { memory as memory$1 } from "./memory/memory.mjs";
+import { human } from "./human/register.mjs";
+import { guardrail as guardrail$1 } from "./guard/guardrail.mjs";
 import { mockRouter } from "./mock/mock-router.mjs";
 import "./mock/index.mjs";
 import { fallbackModel } from "./model/fallback-model.mjs";
@@ -23,15 +31,25 @@ import { orchestrator } from "./orchestrator/orchestrator.mjs";
 import "./orchestrator/index.mjs";
 import { planner } from "./planner/planner.mjs";
 import "./planner/index.mjs";
+import { instruction } from "./system-prompt/instruction.mjs";
+import { persona } from "./system-prompt/persona.mjs";
+import { systemPrompt } from "./system-prompt/system-prompt.mjs";
+import { defaultPromptsManager } from "./prompts/prompts-manager.mjs";
+import { rag } from "./rag/rag.mjs";
+import { keywordReranker } from "./rag/rerank/keyword-reranker.mjs";
+import { llmReranker } from "./rag/rerank/llm-reranker.mjs";
+import "./rag/index.mjs";
+import { prompt } from "./prompt/prompt.mjs";
+import "./prompt/index.mjs";
+import { vcr } from "./vcr/vcr.mjs";
+import "./vcr/index.mjs";
 import { memory as memory$2 } from "./snapshot/memory.mjs";
 import { pg as pg$1 } from "./snapshot/pg.mjs";
 import { redis as redis$1 } from "./snapshot/redis.mjs";
 import { fanOut } from "./supervisor/fan-out.mjs";
 import { router } from "./supervisor/router-factory.mjs";
 import "./supervisor/index.mjs";
-import { instruction } from "./system-prompt/instruction.mjs";
-import { persona } from "./system-prompt/persona.mjs";
-import { systemPrompt } from "./system-prompt/system-prompt.mjs";
+import { team } from "./team/team.mjs";
 import { step } from "./workflow/step.mjs";
 import { workflow } from "./workflow/workflow.mjs";
 
@@ -47,6 +65,7 @@ import { workflow } from "./workflow/workflow.mjs";
 * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).
 * - `ai.orchestrator(...)` — session-state manager wrapped around a supervisor (durable session, drift detection, resume, commands).
 * - `ai.memory(...)` — build an agent-memory store with WORKING (in-run scratch) and SEMANTIC (cache-driver `.similar()` recall) tiers.
+* - `ai.skills(...)` — build a runtime skills library (always-injected metadata catalog + on-demand loadSkill tool).
 * - `ai.planner(...)` — build an executable that generates an ordered plan over registered capabilities, then runs it step-by-step.
 * - `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).
 * - `ai.router(...)` — build a supervisor-compatible routing agent from named intents.
@@ -57,6 +76,8 @@ import { workflow } from "./workflow/workflow.mjs";
 * - `ai.mockRouter(decisions, opts?)` — deterministic supervisor `route` callback for tests.
 * - `ai.checkpoint.{memory,pg,redis}()` — durable orchestrator session checkpoint stores.
 * - `ai.snapshot.{memory,pg,redis}()` — supervisor-run snapshot stores for `iterate: true` resume.
+* - `ai.human.approval(...)` / `ai.human.resume(...)` / `ai.human.interrupt.{memory,pg,redis}()` — human-in-the-loop tool approval (interrupt / resume).
+* - `ai.guardrail(options)` + `ai.guardrail.{pii,topic,injection,moderation}(...)` — content-intelligence guardrails (moderation / PII / injection / topic).
 * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.
 *
 * @example
@@ -85,15 +106,27 @@ const ai = {
 	workflow,
 	step,
 	supervisor,
+	team,
 	orchestrator,
-	memory: memory$1,
+	memory,
+	skills,
 	planner,
+	rag: Object.assign(rag, {
+		keywordReranker,
+		llmReranker
+	}),
 	spawnSubAgent,
 	router,
 	fanOut,
 	batch,
+	streamObject,
+	serve,
 	fallbackModel,
 	eval: evalScorers,
+	dataset,
+	prompt,
+	prompts: defaultPromptsManager(),
+	vcr,
 	mockRouter,
 	middleware: {
 		budget,
@@ -104,7 +137,7 @@ const ai = {
 		readBudgetFallbackSignal
 	},
 	checkpoint: {
-		memory,
+		memory: memory$1,
 		pg,
 		redis
 	},
@@ -112,7 +145,9 @@ const ai = {
 		memory: memory$2,
 		pg: pg$1,
 		redis: redis$1
-	}
+	},
+	human,
+	guardrail: guardrail$1
 };
 
 //#endregion

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 { 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 { rag } from \"./rag\";\nimport { keywordReranker } from \"./rag/rerank/keyword-reranker\";\nimport { llmReranker } from \"./rag/rerank/llm-reranker\";\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  };\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  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, { keywordReranker, llmReranker }),\n  spawnSubAgent,\n  router,\n  fanOut,\n  batch,\n  streamObject,\n  serve,\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqLA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,KAAK,OAAO,OAAO,KAAK;EAAE;EAAiB;CAAY,CAAC;CACxD;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