@warlock.js/ai 4.2.11 → 4.4.0

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

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

package/esm/ai.d.mts

@@ -1,15 +1,32 @@
 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 { memory } from "./checkpoint/memory.mjs";
+import { pg } from "./checkpoint/pg.mjs";
+import { redis } from "./checkpoint/redis.mjs";
 import { setAIConfig } from "./config.mjs";
-import { budget } from "./middleware/builtins/budget.mjs";
+import { memory as memory$1 } from "./memory/memory.mjs";
 import { guardrail } 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";
+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 { fanOut } from "./supervisor/fan-out.mjs";
+import { router } from "./supervisor/router-factory.mjs";
 import { supervisor } from "./supervisor/supervisor.mjs";
 import { instruction } from "./system-prompt/instruction.mjs";
 import { persona } from "./system-prompt/persona.mjs";
-import { systemPrompt } from "./system-prompt/system-prompt.mjs";
 import { step } from "./workflow/step.mjs";
 import { workflow } from "./workflow/workflow.mjs";
 
@@ -23,6 +40,18 @@ import { workflow } from "./workflow/workflow.mjs";
  * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.
  * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).
  * - `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.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.
+ * - `ai.fanOut(unit, count)` — spread one agent/workflow into N intent entries for voting / self-consistency.
+ * - `ai.batch(executable, items, opts?)` — run any executable over a dataset with bounded concurrency + per-item retry.
+ * - `ai.fallbackModel(models, opts?)` — wrap an ordered model list that fails over to the next on transient provider errors.
+ * - `ai.eval.{exact,contains,predicate,judge}(...)` — built-in scorer factories for `agent.eval(...)`.
+ * - `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.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.
  *
  * @example
@@ -45,18 +74,44 @@ declare const ai: {
   config: typeof setAIConfig;
   tool: typeof tool;
   agent: typeof agent;
-  systemPrompt: typeof systemPrompt;
+  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;
   };
 };
 //#endregion

package/esm/ai.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyCA;;;;;;;;;;;;;;;;;;;;;;;cAAa,EAAA"}
+{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;;;;;cAAa,EAAA"}

package/esm/ai.mjs

@@ -1,12 +1,34 @@
-import { budget } from "./middleware/builtins/budget.mjs";
+import { budget, readBudgetFallbackSignal } from "./middleware/builtins/budget.mjs";
 import { guardrail } from "./middleware/builtins/guardrail.mjs";
 import { setAIConfig } from "./config.mjs";
 import { semanticCache } from "./middleware/builtins/semantic-cache.mjs";
 import { composeMiddleware } from "./middleware/helpers/compose.mjs";
 import { forTool } from "./middleware/helpers/for-tool.mjs";
-import { agent } from "./agent/agent.mjs";
 import { tool } from "./tool/tool.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 { pg } from "./checkpoint/pg.mjs";
+import { redis } from "./checkpoint/redis.mjs";
+import { evalScorers } from "./eval/index.mjs";
+import { memory as memory$1 } from "./memory/memory.mjs";
+import { mockRouter } from "./mock/mock-router.mjs";
+import "./mock/index.mjs";
+import { fallbackModel } from "./model/fallback-model.mjs";
+import "./model/index.mjs";
 import { supervisor } from "./supervisor/supervisor.mjs";
+import { orchestrator } from "./orchestrator/orchestrator.mjs";
+import "./orchestrator/index.mjs";
+import { planner } from "./planner/planner.mjs";
+import "./planner/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";
@@ -23,6 +45,18 @@ import { workflow } from "./workflow/workflow.mjs";
 * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.
 * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).
 * - `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.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.
+* - `ai.fanOut(unit, count)` — spread one agent/workflow into N intent entries for voting / self-consistency.
+* - `ai.batch(executable, items, opts?)` — run any executable over a dataset with bounded concurrency + per-item retry.
+* - `ai.fallbackModel(models, opts?)` — wrap an ordered model list that fails over to the next on transient provider errors.
+* - `ai.eval.{exact,contains,predicate,judge}(...)` — built-in scorer factories for `agent.eval(...)`.
+* - `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.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.
 *
 * @example
@@ -51,12 +85,33 @@ const ai = {
 	workflow,
 	step,
 	supervisor,
+	orchestrator,
+	memory: memory$1,
+	planner,
+	spawnSubAgent,
+	router,
+	fanOut,
+	batch,
+	fallbackModel,
+	eval: evalScorers,
+	mockRouter,
 	middleware: {
 		budget,
 		guardrail,
 		semanticCache,
 		compose: composeMiddleware,
-		forTool
+		forTool,
+		readBudgetFallbackSignal
+	},
+	checkpoint: {
+		memory,
+		pg,
+		redis
+	},
+	snapshot: {
+		memory: memory$2,
+		pg: pg$1,
+		redis: redis$1
 	}
 };
 

package/esm/ai.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ai.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"sourcesContent":["import { agent } from \"./agent/agent\";\nimport { setAIConfig } from \"./config\";\nimport { budget } from \"./middleware/builtins/budget\";\nimport { guardrail } from \"./middleware/builtins/guardrail\";\nimport { semanticCache } from \"./middleware/builtins/semantic-cache\";\nimport { composeMiddleware, forTool } from \"./middleware/helpers\";\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.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  middleware: {\n    budget,\n    guardrail,\n    semanticCache,\n    compose: composeMiddleware,\n    forTool,\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,YAAY;EACV;EACA;EACA;EACA,SAAS;EACT;CACF;AACF"}
+{"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"}

package/esm/batch/batch.d.mts

@@ -0,0 +1,43 @@
+import { BaseResult } from "../contracts/result/base-result.type.mjs";
+import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
+import { ExecutableContract } from "../contracts/executable.contract.mjs";
+import { BatchOptions, BatchResult } from "./batch.type.mjs";
+
+//#region ../@warlock.js/ai/src/batch/batch.d.ts
+/**
+ * Run an executable AI primitive (agent, workflow, supervisor, tool,
+ * or anything satisfying {@link ExecutableContract}) over a dataset
+ * with bounded concurrency and per-item retry, returning per-item
+ * outcomes plus rolled-up usage and a walkable report tree.
+ *
+ * **Role.** The fan-out primitive of `@warlock.js/ai`. Where an agent
+ * runs once, `batch` runs the SAME executable N times — once per item
+ * — and aggregates the results into the unified {@link ExecuteResult}
+ * envelope, so a batch slots into cost dashboards and trace tooling
+ * exactly like a single run does.
+ *
+ * **Isolation.** Items are independent: one item's failure (after its
+ * retries are exhausted) never cancels a sibling, and the batch as a
+ * whole never rejects — failures live on each {@link BatchItemResult}.
+ * Reach for `result.report.failed` / `item.status` to inspect them.
+ *
+ * **Usage rollup.** `result.usage` and `result.report.usage` sum every
+ * item's usage, satisfying the universal rollup invariant ("own cost
+ * + sum of children"; a batch has zero own cost). Each item's own
+ * report is attached under `report.children[]`, in original item
+ * order, so a trace walker sees every run.
+ *
+ * @example
+ * const result = await batch(summarizer, articles, {
+ *   concurrency: 4,
+ *   retry: { attempts: 3, backoff: "exponential" },
+ *   onItem: (item) => log.info("batch", "item", "settled", { index: item.index }),
+ * });
+ *
+ * console.log(`${result.report.succeeded}/${result.report.total} ok`);
+ * console.log(`${result.usage.total} tokens total`);
+ */
+declare function batch<TInput, TOptions, TResult extends BaseResult = ExecuteResult>(executable: ExecutableContract<TInput, TOptions, TResult>, items: readonly TInput[], options?: BatchOptions<TResult>): Promise<BatchResult<TResult>>;
+//#endregion
+export { batch };
+//# sourceMappingURL=batch.d.mts.map

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

@@ -0,0 +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"}

package/esm/batch/batch.mjs

@@ -0,0 +1,179 @@
+import { accumulateCost } from "../utils/compute-cost.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
+import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import { runBatchItem } from "./run-batch-item.mjs";
+import { runWithConcurrency } from "./run-with-concurrency.mjs";
+
+//#region ../@warlock.js/ai/src/batch/batch.ts
+/**
+* Run an executable AI primitive (agent, workflow, supervisor, tool,
+* or anything satisfying {@link ExecutableContract}) over a dataset
+* with bounded concurrency and per-item retry, returning per-item
+* outcomes plus rolled-up usage and a walkable report tree.
+*
+* **Role.** The fan-out primitive of `@warlock.js/ai`. Where an agent
+* runs once, `batch` runs the SAME executable N times — once per item
+* — and aggregates the results into the unified {@link ExecuteResult}
+* envelope, so a batch slots into cost dashboards and trace tooling
+* exactly like a single run does.
+*
+* **Isolation.** Items are independent: one item's failure (after its
+* retries are exhausted) never cancels a sibling, and the batch as a
+* whole never rejects — failures live on each {@link BatchItemResult}.
+* Reach for `result.report.failed` / `item.status` to inspect them.
+*
+* **Usage rollup.** `result.usage` and `result.report.usage` sum every
+* item's usage, satisfying the universal rollup invariant ("own cost
+* + sum of children"; a batch has zero own cost). Each item's own
+* report is attached under `report.children[]`, in original item
+* order, so a trace walker sees every run.
+*
+* @example
+* const result = await batch(summarizer, articles, {
+*   concurrency: 4,
+*   retry: { attempts: 3, backoff: "exponential" },
+*   onItem: (item) => log.info("batch", "item", "settled", { index: item.index }),
+* });
+*
+* console.log(`${result.report.succeeded}/${result.report.total} ok`);
+* console.log(`${result.usage.total} tokens total`);
+*/
+async function batch(executable, items, options = {}) {
+	return new BatchRun(executable, items, options).run();
+}
+/**
+* Per-call orchestration state for one {@link batch} invocation.
+* Instantiated fresh inside the factory so the mutable accumulators
+* (`results`, `usage`) are never shared across batches. Unexported —
+* callers only ever see the plain {@link BatchResult}.
+*/
+var BatchRun = class {
+	constructor(executable, items, options) {
+		this.executable = executable;
+		this.items = items;
+		this.options = options;
+		this.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.startPerf = performance.now();
+		this.runId = generateRunId("batch");
+		this.results = new Array(items.length);
+	}
+	/**
+	* Dispatch every item through the concurrency pool, then assemble
+	* the rolled-up {@link BatchResult}. Runs once per `batch()` call.
+	*/
+	async run() {
+		const concurrency = this.options.concurrency ?? this.items.length;
+		await runWithConcurrency(this.items.length, concurrency, (index) => this.processItem(index));
+		return this.buildResult();
+	}
+	/**
+	* 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.
+	*/
+	async processItem(index) {
+		const item = await runBatchItem({
+			index,
+			input: this.items[index],
+			executable: this.executable,
+			retry: this.options.retry,
+			signal: this.options.signal
+		});
+		this.results[index] = item;
+		if (this.options.onItem) try {
+			await this.options.onItem(item);
+		} catch {}
+	}
+	/**
+	* Fold the per-item outcomes into rolled-up usage, the child report
+	* list, and the final {@link BatchResult}, then stamp lineage across
+	* the whole subtree so every child shares this batch's root run id.
+	*/
+	buildResult() {
+		const usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		const children = [];
+		const data = new Array(this.items.length).fill(void 0);
+		let succeeded = 0;
+		let failed = 0;
+		let cancelled = 0;
+		for (const item of this.results) {
+			if (item.status === "completed") succeeded += 1;
+			else if (item.status === "failed") failed += 1;
+			else cancelled += 1;
+			const itemResult = item.result;
+			if (itemResult) {
+				this.mergeUsage(usage, itemResult.usage);
+				if ("report" in itemResult && itemResult.report) children.push(itemResult.report);
+				if (item.status === "completed" && "data" in itemResult) data[item.index] = itemResult.data;
+			}
+		}
+		const report = this.buildReport(usage, children, {
+			succeeded,
+			failed,
+			cancelled
+		});
+		stampReportLineage(report, {
+			rootRunId: this.runId,
+			sessionId: this.options.sessionId
+		});
+		return {
+			type: "batch",
+			data,
+			usage,
+			report,
+			items: this.results
+		};
+	}
+	/**
+	* Add a child's usage into the running batch total. Scalar token
+	* channels sum directly; the optional cost breakdown merges via
+	* {@link accumulateCost} so a single unpriced child can't erase the
+	* cost of priced siblings. Optional token sub-channels
+	* (`cachedTokens`, etc.) accumulate only when some child reports
+	* them, preserving the "never reported anywhere" signal.
+	*/
+	mergeUsage(target, child) {
+		target.input += child.input;
+		target.output += child.output;
+		target.total += child.total;
+		if (child.cachedTokens !== void 0) target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;
+		if (child.reasoningTokens !== void 0) target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;
+		if (child.cacheWriteTokens !== void 0) target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;
+		const mergedCost = accumulateCost(target.cost, child.cost);
+		if (mergedCost !== void 0) target.cost = mergedCost;
+	}
+	/**
+	* Build the batch's own {@link BatchReport} node. `parentRunId` /
+	* `rootRunId` are placeholders here — {@link stampReportLineage}
+	* rewrites them across the whole subtree right after.
+	*/
+	buildReport(usage, children, counts) {
+		const status = counts.failed > 0 || counts.cancelled > 0 ? "failed" : "completed";
+		return {
+			runId: this.runId,
+			rootRunId: this.runId,
+			name: this.options.name ?? "batch",
+			type: "batch",
+			status,
+			startedAt: this.startedAt,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			duration: performance.now() - this.startPerf,
+			usage,
+			children,
+			total: this.items.length,
+			succeeded: counts.succeeded,
+			failed: counts.failed,
+			cancelled: counts.cancelled,
+			reportSchemaVersion: 1
+		};
+	}
+};
+
+//#endregion
+export { batch };
+//# sourceMappingURL=batch.mjs.map

package/esm/batch/batch.mjs.map

@@ -0,0 +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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"}

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

@@ -0,0 +1,144 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { BaseResult } from "../contracts/result/base-result.type.mjs";
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
+import { RetryConfig } from "../contracts/workflow/retry-config.type.mjs";
+
+//#region ../@warlock.js/ai/src/batch/batch.type.d.ts
+/**
+ * Terminal status of a single batch item. Mirrors the relevant subset
+ * of {@link import("../contracts/result/base-report.type").ReportStatus}
+ * — an item either ran to completion, failed (after exhausting its
+ * retries), or was cancelled before it started because the batch was
+ * aborted.
+ */
+type BatchItemStatus = "completed" | "failed" | "cancelled";
+/**
+ * Outcome of running the executable over one input item.
+ *
+ * `result` is the underlying primitive's own {@link ExecuteResult}
+ * (an `AgentResult`, `WorkflowResult`, etc.) when the item ran — it
+ * carries the item's own `usage` and `report`. `result` is `undefined`
+ * only when the item was `"cancelled"` before it ever executed.
+ *
+ * `error` is the typed failure cause when `status` is `"failed"` or
+ * `"cancelled"`, and `undefined` on success. It mirrors
+ * `result?.error` for failed items so callers can branch on the item
+ * envelope without reaching into the inner result.
+ *
+ * @example
+ * const batchResult = await ai.batch(summarizer, articles);
+ *
+ * for (const item of batchResult.items) {
+ *   if (item.status === "completed") {
+ *     console.log(item.index, item.result?.data);
+ *   } else {
+ *     console.warn(item.index, item.error?.code);
+ *   }
+ * }
+ */
+type BatchItemResult<TResult extends BaseResult = ExecuteResult> = {
+  /** 0-based position of this item in the original `items` array. */index: number; /** Terminal status of this item. */
+  status: BatchItemStatus;
+  /**
+   * Underlying primitive result when the item ran (success OR failure).
+   * `undefined` only for items cancelled before execution started.
+   */
+  result?: TResult; /** Typed failure cause; `undefined` on success. */
+  error?: AIError; /** Number of attempts spent on this item (1 when no retry happened). */
+  attempts: number;
+};
+/**
+ * Batch-specific execution report — a {@link BaseReport} whose
+ * `children[]` are the per-item reports, in original item order. The
+ * root `usage` is the rolled-up sum of every child's usage, matching
+ * the universal rollup invariant ("own cost + sum of children"; a
+ * batch has zero own cost — it's pure orchestration).
+ */
+type BatchReport = BaseReport & {
+  type: "batch"; /** Total number of items dispatched. */
+  total: number; /** Count of items that completed successfully. */
+  succeeded: number; /** Count of items that failed after exhausting retries. */
+  failed: number; /** Count of items cancelled before they ran (batch aborted). */
+  cancelled: number;
+};
+/**
+ * Result returned by `ai.batch(...)`. Satisfies the unified
+ * {@link ExecuteResult} envelope — `usage` and `report` are the
+ * rolled-up totals across every item — and adds the per-item
+ * breakdown under `items`.
+ *
+ * `data` holds the ordered array of successful items' `result.data`
+ * with `undefined` in the slots of failed/cancelled items, so callers
+ * that don't care about per-item status can read `data` positionally.
+ * `error` is left `undefined` — a batch never fails as a whole; an
+ * individual item's failure lives on its `BatchItemResult`.
+ *
+ * @example
+ * const { items, usage, report } = await ai.batch(agent, prompts, {
+ *   concurrency: 4,
+ *   retry: { attempts: 3, backoff: "exponential" },
+ * });
+ *
+ * console.log(`${report.succeeded}/${report.total} ok, ${usage.total} tokens`);
+ */
+type BatchResult<TResult extends BaseResult = ExecuteResult> = Omit<ExecuteResult, "data" | "report"> & {
+  type: "batch";
+  /**
+   * Positional outputs: each successful item's `result.data` in
+   * original order, with `undefined` in the slots of failed or
+   * cancelled items.
+   */
+  data: (unknown | undefined)[]; /** Per-item outcomes in original item order. */
+  items: BatchItemResult<TResult>[]; /** Batch-specific report (extends `report` with item counts). */
+  report: BatchReport;
+};
+/**
+ * Callback fired once per item as soon as it settles (success or
+ * failure), regardless of dispatch order. Useful for streaming
+ * progress to a UI or a log without waiting for the whole batch.
+ *
+ * Fired AFTER an item's retries are exhausted — `item.attempts`
+ * reflects the final count. A throw from this hook is swallowed (it
+ * must never break the batch); log inside it if you need failures.
+ */
+type BatchItemHandler<TResult extends BaseResult = ExecuteResult> = (item: BatchItemResult<TResult>) => void | Promise<void>;
+/**
+ * Options for {@link import("./batch").batch}.
+ *
+ * Every field is optional with a safe default — `ai.batch(exec, items)`
+ * runs the whole dataset with unbounded concurrency and no retry.
+ */
+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).
+   */
+  concurrency?: number;
+  /**
+   * Per-item retry policy, reusing the workflow {@link RetryConfig}
+   * semantics (attempts, backoff, `retryOn`, `onRetry`). Applied
+   * independently to each item — one item's retries never block
+   * another's. Omit (or `attempts: 1`) for no retry.
+   */
+  retry?: RetryConfig; /** Fired once per item the moment it settles. See {@link BatchItemHandler}. */
+  onItem?: BatchItemHandler<TResult>;
+  /**
+   * Cancellation handle. When aborted, in-flight items receive the
+   * same signal (so a primitive honoring `signal` stops promptly) and
+   * not-yet-started items are reported as `"cancelled"` without
+   * running.
+   */
+  signal?: AbortSignal;
+  /**
+   * Caller-supplied session identifier propagated onto the batch
+   * report and every child item report (lineage), so flat trace
+   * queries group the whole batch under one session.
+   */
+  sessionId?: string; /** Optional name for the batch report node. Defaults to `"batch"`. */
+  name?: string;
+};
+//#endregion
+export { BatchItemHandler, BatchItemResult, BatchItemStatus, BatchOptions, BatchReport, BatchResult };
+//# sourceMappingURL=batch.type.d.mts.map

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

@@ -0,0 +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"}

package/esm/batch/index.mjs

@@ -0,0 +1,3 @@
+import { batch } from "./batch.mjs";
+
+export {  };