@warlock.js/ai 4.2.10 → 4.3.0

package/esm/supervisor/fan-out.d.mts

@@ -0,0 +1,65 @@
+import { AgentContract } from "../contracts/agent/agent.contract.mjs";
+import { WorkflowInstance } from "../contracts/workflow/workflow.contract.mjs";
+import { IntentEntry } from "../contracts/supervisor/intent-entry.type.mjs";
+
+//#region ../@warlock.js/ai/src/supervisor/fan-out.d.ts
+/**
+ * A dispatchable unit that can be fanned out — an agent or a workflow.
+ * The same union the supervisor's `intents` map accepts for its
+ * agent/workflow object entries.
+ */
+type FanOutUnit = AgentContract<unknown> | WorkflowInstance<unknown, unknown>;
+/**
+ * Options for {@link fanOut}.
+ */
+type FanOutOptions = {
+  /**
+   * Base name for the generated intent keys. Defaults to the unit's own
+   * `name`. The keys are `<keyPrefix>1`, `<keyPrefix>2`, … `<keyPrefix>n`.
+   */
+  keyPrefix?: string;
+  /**
+   * Description applied to every generated entry. Defaults to the
+   * unit's own `description`. A description is required when the
+   * supervisor uses a `router` (the LLM needs a signal per intent); the
+   * factory enforces that downstream, so supply one here when the
+   * underlying unit has none.
+   */
+  description?: string;
+};
+/**
+ * Spread one agent/workflow into `n` distinctly-keyed intent entries
+ * for voting / self-consistency under a supervisor.
+ *
+ * A supervisor dispatches a fan-out array (`["writer1", "writer2",
+ * "writer3"]`) in parallel; each branch runs the SAME unit independently
+ * so a downstream evaluate/aggregate intent can pick the majority answer
+ * or the best of `n` samples. Because every branch needs its own intent
+ * KEY, this helper clones the unit across distinct keys rather than
+ * cloning the unit itself — the underlying agent/workflow is referenced
+ * by all entries, but each entry is a separate dispatch slot.
+ *
+ * Returns a `Record<string, IntentEntry>` you spread directly into the
+ * supervisor's `intents` map. The keys are `<keyPrefix>1..<keyPrefix>n`.
+ *
+ * @example
+ * const writer = ai.agent({ name: "writer", description: "Drafts an answer.", model });
+ *
+ * const support = ai.supervisor({
+ *   name: "self-consistency",
+ *   intents: {
+ *     ...ai.fanOut(writer, 3),          // writer1, writer2, writer3
+ *     vote: { run: pickMajority, description: "Choose the majority answer." },
+ *   },
+ *   route: (ctx) =>
+ *     ctx.iteration === 0 ? ["writer1", "writer2", "writer3"] : "vote",
+ * });
+ *
+ * @param unit  The agent or workflow to fan out.
+ * @param count Number of parallel copies. Must be an integer >= 1.
+ * @param options Optional key-prefix / description overrides.
+ */
+declare function fanOut(unit: FanOutUnit, count: number, options?: FanOutOptions): Record<string, IntentEntry>;
+//#endregion
+export { FanOutOptions, FanOutUnit, fanOut };
+//# sourceMappingURL=fan-out.d.mts.map

package/esm/supervisor/fan-out.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/fan-out.ts"],"mappings":";;;;;;;AASA;;;KAAY,UAAA,GAAa,aAAA,YAAyB,gBAAgB;AAAA;AAKlE;;AALkE,KAKtD,aAAA;EAKV;AAQW;AAmCb;;EA3CE,SAAA;EA4CM;;;;;;;EApCN,WAAW;AAAA;;;;;;AAuCgB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAJb,MAAA,CACd,IAAA,EAAM,UAAA,EACN,KAAA,UACA,OAAA,GAAS,aAAA,GACR,MAAA,SAAe,WAAA"}

package/esm/supervisor/fan-out.mjs

@@ -0,0 +1,65 @@
+//#region ../@warlock.js/ai/src/supervisor/fan-out.ts
+/**
+* Spread one agent/workflow into `n` distinctly-keyed intent entries
+* for voting / self-consistency under a supervisor.
+*
+* A supervisor dispatches a fan-out array (`["writer1", "writer2",
+* "writer3"]`) in parallel; each branch runs the SAME unit independently
+* so a downstream evaluate/aggregate intent can pick the majority answer
+* or the best of `n` samples. Because every branch needs its own intent
+* KEY, this helper clones the unit across distinct keys rather than
+* cloning the unit itself — the underlying agent/workflow is referenced
+* by all entries, but each entry is a separate dispatch slot.
+*
+* Returns a `Record<string, IntentEntry>` you spread directly into the
+* supervisor's `intents` map. The keys are `<keyPrefix>1..<keyPrefix>n`.
+*
+* @example
+* const writer = ai.agent({ name: "writer", description: "Drafts an answer.", model });
+*
+* const support = ai.supervisor({
+*   name: "self-consistency",
+*   intents: {
+*     ...ai.fanOut(writer, 3),          // writer1, writer2, writer3
+*     vote: { run: pickMajority, description: "Choose the majority answer." },
+*   },
+*   route: (ctx) =>
+*     ctx.iteration === 0 ? ["writer1", "writer2", "writer3"] : "vote",
+* });
+*
+* @param unit  The agent or workflow to fan out.
+* @param count Number of parallel copies. Must be an integer >= 1.
+* @param options Optional key-prefix / description overrides.
+*/
+function fanOut(unit, count, options = {}) {
+	if (!unit || typeof unit.execute !== "function") throw new TypeError("ai.fanOut: first argument must be an agent or workflow");
+	if (!Number.isInteger(count) || count < 1) throw new TypeError(`ai.fanOut: \`count\` must be an integer >= 1 (received ${String(count)})`);
+	const keyPrefix = resolveKeyPrefix(unit, options.keyPrefix);
+	const description = options.description ?? readDescription(unit);
+	const entries = {};
+	for (let index = 1; index <= count; index++) {
+		const entry = { agent: unit };
+		if (description) entry.description = description;
+		entries[`${keyPrefix}${index}`] = entry;
+	}
+	return entries;
+}
+/**
+* Resolve the base key prefix: explicit override wins, then the unit's
+* own name. A unit with no usable name forces an explicit `keyPrefix`
+* so the generated keys stay meaningful and collision-free.
+*/
+function resolveKeyPrefix(unit, override) {
+	if (override && override.trim().length > 0) return override.trim();
+	const name = unit.name;
+	if (typeof name === "string" && name.trim().length > 0) return name.trim();
+	throw new TypeError("ai.fanOut: the unit has no usable `name` — pass `options.keyPrefix` to name the generated intent keys");
+}
+function readDescription(unit) {
+	const description = unit.description;
+	return typeof description === "string" && description.trim().length > 0 ? description : void 0;
+}
+
+//#endregion
+export { fanOut };
+//# sourceMappingURL=fan-out.mjs.map

package/esm/supervisor/fan-out.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/fan-out.ts"],"sourcesContent":["import type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { IntentEntry } from \"../contracts/supervisor/intent-entry.type\";\nimport type { WorkflowInstance } from \"../contracts/workflow/workflow.contract\";\n\n/**\n * A dispatchable unit that can be fanned out — an agent or a workflow.\n * The same union the supervisor's `intents` map accepts for its\n * agent/workflow object entries.\n */\nexport type FanOutUnit = AgentContract<unknown> | WorkflowInstance<unknown, unknown>;\n\n/**\n * Options for {@link fanOut}.\n */\nexport type FanOutOptions = {\n  /**\n   * Base name for the generated intent keys. Defaults to the unit's own\n   * `name`. The keys are `<keyPrefix>1`, `<keyPrefix>2`, … `<keyPrefix>n`.\n   */\n  keyPrefix?: string;\n  /**\n   * Description applied to every generated entry. Defaults to the\n   * unit's own `description`. A description is required when the\n   * supervisor uses a `router` (the LLM needs a signal per intent); the\n   * factory enforces that downstream, so supply one here when the\n   * underlying unit has none.\n   */\n  description?: string;\n};\n\n/**\n * Spread one agent/workflow into `n` distinctly-keyed intent entries\n * for voting / self-consistency under a supervisor.\n *\n * A supervisor dispatches a fan-out array (`[\"writer1\", \"writer2\",\n * \"writer3\"]`) in parallel; each branch runs the SAME unit independently\n * so a downstream evaluate/aggregate intent can pick the majority answer\n * or the best of `n` samples. Because every branch needs its own intent\n * KEY, this helper clones the unit across distinct keys rather than\n * cloning the unit itself — the underlying agent/workflow is referenced\n * by all entries, but each entry is a separate dispatch slot.\n *\n * Returns a `Record<string, IntentEntry>` you spread directly into the\n * supervisor's `intents` map. The keys are `<keyPrefix>1..<keyPrefix>n`.\n *\n * @example\n * const writer = ai.agent({ name: \"writer\", description: \"Drafts an answer.\", model });\n *\n * const support = ai.supervisor({\n *   name: \"self-consistency\",\n *   intents: {\n *     ...ai.fanOut(writer, 3),          // writer1, writer2, writer3\n *     vote: { run: pickMajority, description: \"Choose the majority answer.\" },\n *   },\n *   route: (ctx) =>\n *     ctx.iteration === 0 ? [\"writer1\", \"writer2\", \"writer3\"] : \"vote\",\n * });\n *\n * @param unit  The agent or workflow to fan out.\n * @param count Number of parallel copies. Must be an integer >= 1.\n * @param options Optional key-prefix / description overrides.\n */\nexport function fanOut(\n  unit: FanOutUnit,\n  count: number,\n  options: FanOutOptions = {},\n): Record<string, IntentEntry> {\n  if (!unit || typeof (unit as { execute?: unknown }).execute !== \"function\") {\n    throw new TypeError(\"ai.fanOut: first argument must be an agent or workflow\");\n  }\n\n  if (!Number.isInteger(count) || count < 1) {\n    throw new TypeError(`ai.fanOut: \\`count\\` must be an integer >= 1 (received ${String(count)})`);\n  }\n\n  const keyPrefix = resolveKeyPrefix(unit, options.keyPrefix);\n  const description = options.description ?? readDescription(unit);\n\n  const entries: Record<string, IntentEntry> = {};\n\n  for (let index = 1; index <= count; index++) {\n    const entry: IntentEntry = { agent: unit };\n\n    if (description) {\n      entry.description = description;\n    }\n\n    entries[`${keyPrefix}${index}`] = entry;\n  }\n\n  return entries;\n}\n\n/**\n * Resolve the base key prefix: explicit override wins, then the unit's\n * own name. A unit with no usable name forces an explicit `keyPrefix`\n * so the generated keys stay meaningful and collision-free.\n */\nfunction resolveKeyPrefix(unit: FanOutUnit, override: string | undefined): string {\n  if (override && override.trim().length > 0) {\n    return override.trim();\n  }\n\n  const name = (unit as { name?: unknown }).name;\n\n  if (typeof name === \"string\" && name.trim().length > 0) {\n    return name.trim();\n  }\n\n  throw new TypeError(\n    \"ai.fanOut: the unit has no usable `name` — pass `options.keyPrefix` to name the generated intent keys\",\n  );\n}\n\nfunction readDescription(unit: FanOutUnit): string | undefined {\n  const description = (unit as { description?: unknown }).description;\n\n  return typeof description === \"string\" && description.trim().length > 0 ? description : undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAAgB,OACd,MACA,OACA,UAAyB,CAAC,GACG;CAC7B,IAAI,CAAC,QAAQ,OAAQ,KAA+B,YAAY,YAC9D,MAAM,IAAI,UAAU,wDAAwD;CAG9E,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,GACtC,MAAM,IAAI,UAAU,0DAA0D,OAAO,KAAK,EAAE,EAAE;CAGhG,MAAM,YAAY,iBAAiB,MAAM,QAAQ,SAAS;CAC1D,MAAM,cAAc,QAAQ,eAAe,gBAAgB,IAAI;CAE/D,MAAM,UAAuC,CAAC;CAE9C,KAAK,IAAI,QAAQ,GAAG,SAAS,OAAO,SAAS;EAC3C,MAAM,QAAqB,EAAE,OAAO,KAAK;EAEzC,IAAI,aACF,MAAM,cAAc;EAGtB,QAAQ,GAAG,YAAY,WAAW;CACpC;CAEA,OAAO;AACT;;;;;;AAOA,SAAS,iBAAiB,MAAkB,UAAsC;CAChF,IAAI,YAAY,SAAS,KAAK,CAAC,CAAC,SAAS,GACvC,OAAO,SAAS,KAAK;CAGvB,MAAM,OAAQ,KAA4B;CAE1C,IAAI,OAAO,SAAS,YAAY,KAAK,KAAK,CAAC,CAAC,SAAS,GACnD,OAAO,KAAK,KAAK;CAGnB,MAAM,IAAI,UACR,uGACF;AACF;AAEA,SAAS,gBAAgB,MAAsC;CAC7D,MAAM,cAAe,KAAmC;CAExD,OAAO,OAAO,gBAAgB,YAAY,YAAY,KAAK,CAAC,CAAC,SAAS,IAAI,cAAc;AAC1F"}

package/esm/supervisor/index.d.mts

@@ -1,11 +1,13 @@
 import { SupervisorStreamEvent } from "../contracts/supervisor/supervisor-stream-event.type.mjs";
-import { supervisor } from "./supervisor.mjs";
+import { ResolvedIntentEntry, resolveIntentEntries } from "./entries.mjs";
 import { asTool } from "./as-tool.mjs";
 import { createCancelledError } from "./cancellation.mjs";
 import { SupervisorEmitter } from "./emitter.mjs";
-import { ResolvedIntentEntry, resolveIntentEntries } from "./entries.mjs";
 import { SupervisorStreamController, createSupervisorStream } from "./supervisor-stream.mjs";
 import { SupervisorExecution } from "./execution.mjs";
+import { FanOutOptions, FanOutUnit, fanOut } from "./fan-out.mjs";
+import { RouterConfig, RouterIntents, RouterOutput, router } from "./router-factory.mjs";
 import { buildRouterContextMessage } from "./router-prompt.mjs";
 import { computeSignature } from "./signature.mjs";
-import { loadSnapshotForResume, persistSupervisorSnapshot, snapshotKey } from "./snapshot.mjs";
+import { loadSnapshotForResume, persistSupervisorSnapshot } from "./snapshot.mjs";
+import { supervisor } from "./supervisor.mjs";

package/esm/supervisor/index.mjs

@@ -3,10 +3,12 @@ import { SupervisorEmitter } from "./emitter.mjs";
 import { resolveIntentEntries } from "./entries.mjs";
 import { createCancelledError } from "./cancellation.mjs";
 import { buildRouterContextMessage } from "./router-prompt.mjs";
-import { loadSnapshotForResume, persistSupervisorSnapshot, snapshotKey } from "./snapshot.mjs";
+import { loadSnapshotForResume, persistSupervisorSnapshot } from "./snapshot.mjs";
 import { SupervisorExecution } from "./execution.mjs";
 import { computeSignature } from "./signature.mjs";
 import { createSupervisorStream } from "./supervisor-stream.mjs";
 import { supervisor } from "./supervisor.mjs";
+import { fanOut } from "./fan-out.mjs";
+import { router } from "./router-factory.mjs";
 
 export {  };

package/esm/supervisor/router-factory.d.mts

@@ -0,0 +1,110 @@
+import { AgentContract } from "../contracts/agent/agent.contract.mjs";
+import { ModelCallOptions, ModelContract } from "../contracts/model.contract.mjs";
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+import { SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
+import { SupervisorIntentValue } from "../contracts/supervisor/intent-entry.type.mjs";
+import { Next } from "../contracts/supervisor/next.type.mjs";
+import { AgentEventHandlers } from "../agent/agent-config.type.mjs";
+
+//#region ../@warlock.js/ai/src/supervisor/router-factory.d.ts
+/**
+ * Output shape every router agent produced by {@link router} emits —
+ * the canonical `{ next, reasoning }` contract the supervisor's
+ * dispatch loop reads. Exposed so callers can type a router result
+ * they handle directly.
+ */
+type RouterOutput = {
+  /** Chosen intent name, a fan-out array, or the `END` sentinel. */next: Next; /** One-sentence justification for the routing choice. */
+  reasoning: string;
+};
+/**
+ * Description source for one intent the router can pick from. Accepts
+ * the same value-shapes the supervisor's `intents` map does (bare
+ * agent / workflow / callback / object entry) so a caller can pass the
+ * very same `intents` object to both `router()` and `ai.supervisor()`.
+ *
+ * The router only needs each intent's NAME (the map key) and a
+ * human-readable DESCRIPTION — it never dispatches anything itself, so
+ * the underlying unit is read for its `description` only.
+ */
+type RouterIntents = Record<string, SupervisorIntentValue>;
+/**
+ * Config for {@link router}. Mirrors the relevant slice of `AgentConfig`
+ * — the router IS an agent — plus the `intents` map it routes over.
+ *
+ * Everything except `model` and `intents` is optional; the helper
+ * generates the output schema and the routing system prompt for you.
+ */
+type RouterConfig = {
+  /**
+   * Stable identifier for the router agent. Defaults to
+   * `"<supervisor-ish>-router"` is NOT assumed — when omitted the helper
+   * uses `"router"` so the agent carries a meaningful (non-anonymous)
+   * name, which `ai.supervisor({ router })` is happy to accept.
+   */
+  name?: string; /** The routing LLM. Required — a router with no model can't decide. */
+  model: ModelContract;
+  /**
+   * The intents the router chooses among. Same object you pass to
+   * `ai.supervisor({ intents })`. Their descriptions are rendered into
+   * the generated routing system prompt so the LLM knows what each
+   * option does.
+   */
+  intents: RouterIntents;
+  /**
+   * Extra guidance prepended to the framework-generated routing system
+   * prompt. Use it for domain framing ("You coordinate a support
+   * team."); the mechanical "here are your options, emit `next`"
+   * scaffolding is appended automatically.
+   */
+  systemPrompt?: SystemPromptContract | string; /** Placeholder values merged into the router's system prompt template. */
+  placeholders?: Placeholders; /** Base model call options forwarded to the underlying agent. */
+  modelOptions?: ModelCallOptions;
+  /**
+   * Hard cap on LLM trips for the router agent. A router is a
+   * single-shot decision maker, so this defaults to `1` — override
+   * only if the router itself calls tools mid-decision.
+   */
+  maxTrips?: number; /** Factory-level event handlers forwarded to the underlying agent. */
+  on?: AgentEventHandlers;
+};
+/**
+ * Build a routing agent for `ai.supervisor({ router })` without
+ * hand-writing the output schema or the "pick one of these intents"
+ * system prompt.
+ *
+ * **What it does for you.**
+ * - Generates the canonical `{ next, reasoning }` output schema
+ *   (baked onto the agent so it's a valid router standalone, and
+ *   identical to what the supervisor injects per-turn) — the model is
+ *   steered to emit a single intent name or the `END` sentinel.
+ * - Auto-builds a system prompt that lists every intent + its
+ *   description + the reserved `END` value + terse routing rules, with
+ *   any caller-supplied `systemPrompt` framing kept on top.
+ *
+ * The result is a plain {@link AgentContract}; pass it straight to
+ * `ai.supervisor({ router: ... })`. Because the supervisor also injects
+ * the same schema per-turn and prepends its own per-turn context
+ * message, the baked schema/prompt are belt-and-suspenders — they make
+ * the agent a correct router even when invoked directly.
+ *
+ * @example
+ * const intents = { triage, orderLookup, billingLookup, resolver };
+ *
+ * const supportRouter = ai.router({
+ *   model,
+ *   intents,
+ *   systemPrompt: "You coordinate a customer-support team.",
+ * });
+ *
+ * const support = ai.supervisor({
+ *   name: "customer-support",
+ *   router: supportRouter,
+ *   intents,
+ *   maxIterations: 6,
+ * });
+ */
+declare function router(config: RouterConfig): AgentContract<RouterOutput>;
+//#endregion
+export { RouterConfig, RouterIntents, RouterOutput, router };
+//# sourceMappingURL=router-factory.d.mts.map

package/esm/supervisor/router-factory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-factory.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/router-factory.ts"],"mappings":";;;;;;;;;;;AAiBA;;;;KAAY,YAAA;EAEJ,kEAAN,IAAA,EAAM,IAAI,EAED;EAAT,SAAA;AAAA;;;;AAa8D;AAShE;;;;;;KATY,aAAA,GAAgB,MAAM,SAAS,qBAAA;;;;;;;;KAS/B,YAAA;EAgBD;;;;;;EATT,IAAA,WA0BA;EAxBA,KAAA,EAAO,aAAA;EA0BF;;AAAkB;AAuCzB;;;EA1DE,OAAA,EAAS,aAAA;EA0DiD;;;;;;EAnD1D,YAAA,GAAe,oBAAA,WAmD2C;EAjD1D,YAAA,GAAe,YAAA,EAiDuD;EA/CtE,YAAA,GAAe,gBAAA;;;;;;EAMf,QAAA;EAEA,EAAA,GAAK,kBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuCS,MAAA,CAAO,MAAA,EAAQ,YAAA,GAAe,aAAA,CAAc,YAAA"}

package/esm/supervisor/router-factory.mjs

@@ -0,0 +1,141 @@
+import { agent } from "../agent/agent.mjs";
+import { END } from "../contracts/end.type.mjs";
+
+//#region ../@warlock.js/ai/src/supervisor/router-factory.ts
+/**
+* Build a routing agent for `ai.supervisor({ router })` without
+* hand-writing the output schema or the "pick one of these intents"
+* system prompt.
+*
+* **What it does for you.**
+* - Generates the canonical `{ next, reasoning }` output schema
+*   (baked onto the agent so it's a valid router standalone, and
+*   identical to what the supervisor injects per-turn) — the model is
+*   steered to emit a single intent name or the `END` sentinel.
+* - Auto-builds a system prompt that lists every intent + its
+*   description + the reserved `END` value + terse routing rules, with
+*   any caller-supplied `systemPrompt` framing kept on top.
+*
+* The result is a plain {@link AgentContract}; pass it straight to
+* `ai.supervisor({ router: ... })`. Because the supervisor also injects
+* the same schema per-turn and prepends its own per-turn context
+* message, the baked schema/prompt are belt-and-suspenders — they make
+* the agent a correct router even when invoked directly.
+*
+* @example
+* const intents = { triage, orderLookup, billingLookup, resolver };
+*
+* const supportRouter = ai.router({
+*   model,
+*   intents,
+*   systemPrompt: "You coordinate a customer-support team.",
+* });
+*
+* const support = ai.supervisor({
+*   name: "customer-support",
+*   router: supportRouter,
+*   intents,
+*   maxIterations: 6,
+* });
+*/
+function router(config) {
+	if (!config.model) throw new TypeError("ai.router: `model` is required");
+	if (!config.intents || typeof config.intents !== "object") throw new TypeError("ai.router: `intents` is required and must be an object");
+	const intentNames = Object.keys(config.intents);
+	if (intentNames.length === 0) throw new TypeError("ai.router: `intents` must contain at least one entry");
+	const routingPrompt = buildRoutingSystemPrompt(config.intents, resolvePrefix(config.systemPrompt));
+	return agent({
+		name: config.name ?? "router",
+		description: "Routes a supervisor run to the next intent (or terminates it).",
+		model: config.model,
+		systemPrompt: routingPrompt,
+		output: routerOutputSchema(intentNames),
+		placeholders: config.placeholders,
+		modelOptions: config.modelOptions,
+		maxTrips: config.maxTrips ?? 1,
+		on: config.on
+	});
+}
+/**
+* Resolve a caller-supplied `systemPrompt` (string or contract) to
+* plain text for prepending to the generated routing block. Returns
+* `undefined` when none was supplied.
+*/
+function resolvePrefix(prompt) {
+	if (!prompt) return;
+	return typeof prompt === "string" ? prompt : prompt.resolve();
+}
+/**
+* Assemble the routing system prompt: optional caller framing on top,
+* then the mechanical block listing every intent + description, the
+* reserved `END` sentinel, and the rules for emitting `next`.
+*/
+function buildRoutingSystemPrompt(intents, prefix) {
+	const intentLines = Object.entries(intents).map(([name, value]) => {
+		const description = resolveIntentDescription(value);
+		return description ? `- ${name}: ${description}` : `- ${name}`;
+	});
+	const sections = [];
+	if (prefix && prefix.trim().length > 0) sections.push(prefix.trim(), "");
+	sections.push("You are a router. Pick the single best intent to handle the next step, or terminate the run.", "", "Available intents:", ...intentLines, "", "Reserved values:", `- ${END} = terminate the run when no further intent is needed`, "", "Rules:", "- Respond with the `next` field set to exactly one intent name from the list above, or the END sentinel.", "- Put a one-sentence justification in the `reasoning` field.", "- Never invent an intent name that is not listed.");
+	return sections.join("\n");
+}
+/**
+* Read the human-readable description off a supervisor-intent value,
+* regardless of which accepted shape it is (bare agent / workflow,
+* object entry with a `description` override, callback entry). Bare
+* callbacks have no description source — returns `undefined`, and the
+* prompt simply lists the intent by name.
+*/
+function resolveIntentDescription(value) {
+	if (!value || typeof value === "function") return;
+	const entry = value;
+	if (typeof entry.description === "string" && entry.description.trim().length > 0) return entry.description.trim();
+	const agentDescription = entry.agent?.description;
+	if (typeof agentDescription === "string" && agentDescription.trim().length > 0) return agentDescription.trim();
+}
+/**
+* Build the canonical router output Standard Schema. The same shape the
+* supervisor injects per-turn — `{ next: string, reasoning: string }` —
+* with the JSON Schema extension carrying the intent names as an `enum`
+* (plus the `END` sentinel) so capable providers enforce the choice
+* natively rather than via soft prompt coaching. Validation still
+* accepts `string` / `string[]` for framework-level fan-out.
+*/
+function routerOutputSchema(intentNames) {
+	const jsonSchema = {
+		type: "object",
+		properties: {
+			next: {
+				type: "string",
+				enum: [...intentNames, END],
+				description: "Name of the intent to dispatch next, or the END sentinel to terminate."
+			},
+			reasoning: {
+				type: "string",
+				description: "One-sentence justification for the routing choice."
+			}
+		},
+		required: ["next", "reasoning"],
+		additionalProperties: false
+	};
+	return { "~standard": {
+		version: 1,
+		vendor: "warlock-router",
+		jsonSchema: { input: () => jsonSchema },
+		validate(value) {
+			if (!value || typeof value !== "object") return { issues: [{ message: "router output must be an object" }] };
+			const record = value;
+			const rawNext = record.next;
+			if (!(typeof rawNext === "string" || Array.isArray(rawNext) && rawNext.every((element) => typeof element === "string"))) return { issues: [{ message: "router output `next` must be a string, string[], or the END sentinel" }] };
+			return { value: {
+				next: rawNext,
+				reasoning: typeof record.reasoning === "string" ? record.reasoning : ""
+			} };
+		}
+	} };
+}
+
+//#endregion
+export { router };
+//# sourceMappingURL=router-factory.mjs.map

package/esm/supervisor/router-factory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-factory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/router-factory.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { agent } from \"../agent/agent\";\nimport type { AgentEventHandlers } from \"../agent/agent-config.type\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport { END } from \"../contracts/end.type\";\nimport type { ModelCallOptions, ModelContract } from \"../contracts/model.contract\";\nimport type { Placeholders } from \"../contracts/placeholders.type\";\nimport type { SupervisorIntentValue } from \"../contracts/supervisor/intent-entry.type\";\nimport type { Next } from \"../contracts/supervisor/next.type\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\n\n/**\n * Output shape every router agent produced by {@link router} emits —\n * the canonical `{ next, reasoning }` contract the supervisor's\n * dispatch loop reads. Exposed so callers can type a router result\n * they handle directly.\n */\nexport type RouterOutput = {\n  /** Chosen intent name, a fan-out array, or the `END` sentinel. */\n  next: Next;\n  /** One-sentence justification for the routing choice. */\n  reasoning: string;\n};\n\n/**\n * Description source for one intent the router can pick from. Accepts\n * the same value-shapes the supervisor's `intents` map does (bare\n * agent / workflow / callback / object entry) so a caller can pass the\n * very same `intents` object to both `router()` and `ai.supervisor()`.\n *\n * The router only needs each intent's NAME (the map key) and a\n * human-readable DESCRIPTION — it never dispatches anything itself, so\n * the underlying unit is read for its `description` only.\n */\nexport type RouterIntents = Record<string, SupervisorIntentValue>;\n\n/**\n * Config for {@link router}. Mirrors the relevant slice of `AgentConfig`\n * — the router IS an agent — plus the `intents` map it routes over.\n *\n * Everything except `model` and `intents` is optional; the helper\n * generates the output schema and the routing system prompt for you.\n */\nexport type RouterConfig = {\n  /**\n   * Stable identifier for the router agent. Defaults to\n   * `\"<supervisor-ish>-router\"` is NOT assumed — when omitted the helper\n   * uses `\"router\"` so the agent carries a meaningful (non-anonymous)\n   * name, which `ai.supervisor({ router })` is happy to accept.\n   */\n  name?: string;\n  /** The routing LLM. Required — a router with no model can't decide. */\n  model: ModelContract;\n  /**\n   * The intents the router chooses among. Same object you pass to\n   * `ai.supervisor({ intents })`. Their descriptions are rendered into\n   * the generated routing system prompt so the LLM knows what each\n   * option does.\n   */\n  intents: RouterIntents;\n  /**\n   * Extra guidance prepended to the framework-generated routing system\n   * prompt. Use it for domain framing (\"You coordinate a support\n   * team.\"); the mechanical \"here are your options, emit `next`\"\n   * scaffolding is appended automatically.\n   */\n  systemPrompt?: SystemPromptContract | string;\n  /** Placeholder values merged into the router's system prompt template. */\n  placeholders?: Placeholders;\n  /** Base model call options forwarded to the underlying agent. */\n  modelOptions?: ModelCallOptions;\n  /**\n   * Hard cap on LLM trips for the router agent. A router is a\n   * single-shot decision maker, so this defaults to `1` — override\n   * only if the router itself calls tools mid-decision.\n   */\n  maxTrips?: number;\n  /** Factory-level event handlers forwarded to the underlying agent. */\n  on?: AgentEventHandlers;\n};\n\n/**\n * Build a routing agent for `ai.supervisor({ router })` without\n * hand-writing the output schema or the \"pick one of these intents\"\n * system prompt.\n *\n * **What it does for you.**\n * - Generates the canonical `{ next, reasoning }` output schema\n *   (baked onto the agent so it's a valid router standalone, and\n *   identical to what the supervisor injects per-turn) — the model is\n *   steered to emit a single intent name or the `END` sentinel.\n * - Auto-builds a system prompt that lists every intent + its\n *   description + the reserved `END` value + terse routing rules, with\n *   any caller-supplied `systemPrompt` framing kept on top.\n *\n * The result is a plain {@link AgentContract}; pass it straight to\n * `ai.supervisor({ router: ... })`. Because the supervisor also injects\n * the same schema per-turn and prepends its own per-turn context\n * message, the baked schema/prompt are belt-and-suspenders — they make\n * the agent a correct router even when invoked directly.\n *\n * @example\n * const intents = { triage, orderLookup, billingLookup, resolver };\n *\n * const supportRouter = ai.router({\n *   model,\n *   intents,\n *   systemPrompt: \"You coordinate a customer-support team.\",\n * });\n *\n * const support = ai.supervisor({\n *   name: \"customer-support\",\n *   router: supportRouter,\n *   intents,\n *   maxIterations: 6,\n * });\n */\nexport function router(config: RouterConfig): AgentContract<RouterOutput> {\n  if (!config.model) {\n    throw new TypeError(\"ai.router: `model` is required\");\n  }\n\n  if (!config.intents || typeof config.intents !== \"object\") {\n    throw new TypeError(\"ai.router: `intents` is required and must be an object\");\n  }\n\n  const intentNames = Object.keys(config.intents);\n\n  if (intentNames.length === 0) {\n    throw new TypeError(\"ai.router: `intents` must contain at least one entry\");\n  }\n\n  const routingPrompt = buildRoutingSystemPrompt(config.intents, resolvePrefix(config.systemPrompt));\n\n  return agent<RouterOutput>({\n    name: config.name ?? \"router\",\n    description: \"Routes a supervisor run to the next intent (or terminates it).\",\n    model: config.model,\n    systemPrompt: routingPrompt,\n    output: routerOutputSchema(intentNames),\n    placeholders: config.placeholders,\n    modelOptions: config.modelOptions,\n    maxTrips: config.maxTrips ?? 1,\n    on: config.on,\n  });\n}\n\n/**\n * Resolve a caller-supplied `systemPrompt` (string or contract) to\n * plain text for prepending to the generated routing block. Returns\n * `undefined` when none was supplied.\n */\nfunction resolvePrefix(prompt: SystemPromptContract | string | undefined): string | undefined {\n  if (!prompt) {\n    return undefined;\n  }\n\n  return typeof prompt === \"string\" ? prompt : prompt.resolve();\n}\n\n/**\n * Assemble the routing system prompt: optional caller framing on top,\n * then the mechanical block listing every intent + description, the\n * reserved `END` sentinel, and the rules for emitting `next`.\n */\nfunction buildRoutingSystemPrompt(intents: RouterIntents, prefix: string | undefined): string {\n  const intentLines = Object.entries(intents).map(([name, value]) => {\n    const description = resolveIntentDescription(value);\n\n    return description ? `- ${name}: ${description}` : `- ${name}`;\n  });\n\n  const sections: string[] = [];\n\n  if (prefix && prefix.trim().length > 0) {\n    sections.push(prefix.trim(), \"\");\n  }\n\n  sections.push(\n    \"You are a router. Pick the single best intent to handle the next step, or terminate the run.\",\n    \"\",\n    \"Available intents:\",\n    ...intentLines,\n    \"\",\n    \"Reserved values:\",\n    `- ${END} = terminate the run when no further intent is needed`,\n    \"\",\n    \"Rules:\",\n    \"- Respond with the `next` field set to exactly one intent name from the list above, or the END sentinel.\",\n    \"- Put a one-sentence justification in the `reasoning` field.\",\n    \"- Never invent an intent name that is not listed.\",\n  );\n\n  return sections.join(\"\\n\");\n}\n\n/**\n * Read the human-readable description off a supervisor-intent value,\n * regardless of which accepted shape it is (bare agent / workflow,\n * object entry with a `description` override, callback entry). Bare\n * callbacks have no description source — returns `undefined`, and the\n * prompt simply lists the intent by name.\n */\nfunction resolveIntentDescription(value: SupervisorIntentValue): string | undefined {\n  if (!value || typeof value === \"function\") {\n    return undefined;\n  }\n\n  const entry = value as {\n    description?: unknown;\n    agent?: { description?: unknown };\n  };\n\n  if (typeof entry.description === \"string\" && entry.description.trim().length > 0) {\n    return entry.description.trim();\n  }\n\n  const agentDescription = entry.agent?.description;\n\n  if (typeof agentDescription === \"string\" && agentDescription.trim().length > 0) {\n    return agentDescription.trim();\n  }\n\n  return undefined;\n}\n\n/**\n * Build the canonical router output Standard Schema. The same shape the\n * supervisor injects per-turn — `{ next: string, reasoning: string }` —\n * with the JSON Schema extension carrying the intent names as an `enum`\n * (plus the `END` sentinel) so capable providers enforce the choice\n * natively rather than via soft prompt coaching. Validation still\n * accepts `string` / `string[]` for framework-level fan-out.\n */\nfunction routerOutputSchema(intentNames: string[]): StandardSchemaV1<RouterOutput> {\n  const nextEnum = [...intentNames, END];\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      next: {\n        type: \"string\",\n        enum: nextEnum,\n        description: \"Name of the intent to dispatch next, or the END sentinel to terminate.\",\n      },\n      reasoning: {\n        type: \"string\",\n        description: \"One-sentence justification for the routing choice.\",\n      },\n    },\n    required: [\"next\", \"reasoning\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-router\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<RouterOutput> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"router output must be an object\" }] };\n        }\n\n        const record = value as { next?: unknown; reasoning?: unknown };\n        const rawNext = record.next;\n\n        const nextIsValid =\n          typeof rawNext === \"string\" ||\n          (Array.isArray(rawNext) && rawNext.every((element) => typeof element === \"string\"));\n\n        if (!nextIsValid) {\n          return {\n            issues: [\n              { message: \"router output `next` must be a string, string[], or the END sentinel\" },\n            ],\n          };\n        }\n\n        const reasoning = typeof record.reasoning === \"string\" ? record.reasoning : \"\";\n\n        return {\n          value: { next: rawNext as Next, reasoning },\n        };\n      },\n    } as StandardSchemaV1<RouterOutput>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqHA,SAAgB,OAAO,QAAmD;CACxE,IAAI,CAAC,OAAO,OACV,MAAM,IAAI,UAAU,gCAAgC;CAGtD,IAAI,CAAC,OAAO,WAAW,OAAO,OAAO,YAAY,UAC/C,MAAM,IAAI,UAAU,wDAAwD;CAG9E,MAAM,cAAc,OAAO,KAAK,OAAO,OAAO;CAE9C,IAAI,YAAY,WAAW,GACzB,MAAM,IAAI,UAAU,sDAAsD;CAG5E,MAAM,gBAAgB,yBAAyB,OAAO,SAAS,cAAc,OAAO,YAAY,CAAC;CAEjG,OAAO,MAAoB;EACzB,MAAM,OAAO,QAAQ;EACrB,aAAa;EACb,OAAO,OAAO;EACd,cAAc;EACd,QAAQ,mBAAmB,WAAW;EACtC,cAAc,OAAO;EACrB,cAAc,OAAO;EACrB,UAAU,OAAO,YAAY;EAC7B,IAAI,OAAO;CACb,CAAC;AACH;;;;;;AAOA,SAAS,cAAc,QAAuE;CAC5F,IAAI,CAAC,QACH;CAGF,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO,QAAQ;AAC9D;;;;;;AAOA,SAAS,yBAAyB,SAAwB,QAAoC;CAC5F,MAAM,cAAc,OAAO,QAAQ,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,WAAW;EACjE,MAAM,cAAc,yBAAyB,KAAK;EAElD,OAAO,cAAc,KAAK,KAAK,IAAI,gBAAgB,KAAK;CAC1D,CAAC;CAED,MAAM,WAAqB,CAAC;CAE5B,IAAI,UAAU,OAAO,KAAK,CAAC,CAAC,SAAS,GACnC,SAAS,KAAK,OAAO,KAAK,GAAG,EAAE;CAGjC,SAAS,KACP,gGACA,IACA,sBACA,GAAG,aACH,IACA,oBACA,KAAK,IAAI,wDACT,IACA,UACA,4GACA,gEACA,mDACF;CAEA,OAAO,SAAS,KAAK,IAAI;AAC3B;;;;;;;;AASA,SAAS,yBAAyB,OAAkD;CAClF,IAAI,CAAC,SAAS,OAAO,UAAU,YAC7B;CAGF,MAAM,QAAQ;CAKd,IAAI,OAAO,MAAM,gBAAgB,YAAY,MAAM,YAAY,KAAK,CAAC,CAAC,SAAS,GAC7E,OAAO,MAAM,YAAY,KAAK;CAGhC,MAAM,mBAAmB,MAAM,OAAO;CAEtC,IAAI,OAAO,qBAAqB,YAAY,iBAAiB,KAAK,CAAC,CAAC,SAAS,GAC3E,OAAO,iBAAiB,KAAK;AAIjC;;;;;;;;;AAUA,SAAS,mBAAmB,aAAuD;CAGjF,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,MAAM;IACJ,MAAM;IACN,MAAM,CAPM,GAAG,aAAa,GAOf;IACb,aAAa;GACf;GACA,WAAW;IACT,MAAM;IACN,aAAa;GACf;EACF;EACA,UAAU,CAAC,QAAQ,WAAW;EAC9B,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAuD;GAC9D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,kCAAkC,CAAC,EAAE;GAGpE,MAAM,SAAS;GACf,MAAM,UAAU,OAAO;GAMvB,IAAI,EAHF,OAAO,YAAY,YAClB,MAAM,QAAQ,OAAO,KAAK,QAAQ,OAAO,YAAY,OAAO,YAAY,QAAQ,IAGjF,OAAO,EACL,QAAQ,CACN,EAAE,SAAS,uEAAuE,CACpF,EACF;GAKF,OAAO,EACL,OAAO;IAAE,MAAM;IAAiB,WAHhB,OAAO,OAAO,cAAc,WAAW,OAAO,YAAY;GAGhC,EAC5C;EACF;CACF,EAGF;AACF"}

package/esm/supervisor/router-prompt.d.mts

@@ -1,5 +1,5 @@
-import { IterationSnapshot } from "../contracts/supervisor/iteration-snapshot.type.mjs";
 import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.mjs";
+import { IterationSnapshot } from "../contracts/supervisor/iteration-snapshot.type.mjs";
 import { ResolvedIntentEntry } from "./entries.mjs";
 
 //#region ../@warlock.js/ai/src/supervisor/router-prompt.d.ts

package/esm/supervisor/snapshot.d.mts

@@ -1,8 +1,8 @@
-import { IterationSnapshot } from "../contracts/supervisor/iteration-snapshot.type.mjs";
 import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.mjs";
-import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type.mjs";
-import { SupervisorResumeOptions } from "../contracts/supervisor/supervisor-execute-options.type.mjs";
 import { SupervisorSnapshot, SupervisorSnapshotStatus } from "../contracts/supervisor/supervisor-snapshot.type.mjs";
+import { SupervisorResumeOptions } from "../contracts/supervisor/supervisor-execute-options.type.mjs";
+import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type.mjs";
+import { IterationSnapshot } from "../contracts/supervisor/iteration-snapshot.type.mjs";
 
 //#region ../@warlock.js/ai/src/supervisor/snapshot.d.ts
 type PersistParams = {
@@ -43,12 +43,6 @@ declare function loadSnapshotForResume(params: {
   runId: string;
   options?: SupervisorResumeOptions;
 }): Promise<SupervisorSnapshot>;
-/**
- * Canonical key shape used in the KVStore. Prefixed so supervisor
- * snapshots don't collide with workflow / session snapshots in a
- * shared store.
- */
-declare function snapshotKey(runId: string): string;
 //#endregion
-export { loadSnapshotForResume, persistSupervisorSnapshot, snapshotKey };
+export { loadSnapshotForResume, persistSupervisorSnapshot };
 //# sourceMappingURL=snapshot.d.mts.map

package/esm/supervisor/snapshot.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/snapshot.ts"],"mappings":";;;;;;;KAoBY,aAAA;EACV,MAAA,EAAQ,gBAAA;EACR,SAAA;EACA,KAAA;EACA,KAAA,EAAO,eAAA;EACP,SAAA;EACA,SAAA;EACA,SAAA,EAAW,iBAAA;EACX,MAAA,EAAQ,wBAAA;AAAA;AAAA,KAGE,cAAA;EAAmB,EAAA;AAAA;EAAe,EAAA;EAAW,KAAA;AAAA;;;;;;;;;iBAUnC,yBAAA,CACpB,MAAA,EAAQ,aAAA,GACP,OAAA,CAAQ,cAAA;AAZX;;;;;;;AAAA,iBA+CsB,qBAAA,CAAsB,MAAA;EAC1C,MAAA,EAAQ,gBAAA;EACR,SAAA;EACA,KAAA;EACA,OAAA,GAAU,uBAAA;AAAA,IACR,OAAA,CAAQ,kBAAA;;;;;;iBAuCI,WAAA,CAAY,KAAa"}
+{"version":3,"file":"snapshot.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/snapshot.ts"],"mappings":";;;;;;;KAoBY,aAAA;EACV,MAAA,EAAQ,gBAAA;EACR,SAAA;EACA,KAAA;EACA,KAAA,EAAO,eAAA;EACP,SAAA;EACA,SAAA;EACA,SAAA,EAAW,iBAAA;EACX,MAAA,EAAQ,wBAAA;AAAA;AAAA,KAGE,cAAA;EAAmB,EAAA;AAAA;EAAe,EAAA;EAAW,KAAA;AAAA;;;;;;;;;iBAUnC,yBAAA,CACpB,MAAA,EAAQ,aAAA,GACP,OAAA,CAAQ,cAAA;AAZX;;;;;;;AAAA,iBA+CsB,qBAAA,CAAsB,MAAA;EAC1C,MAAA,EAAQ,gBAAA;EACR,SAAA;EACA,KAAA;EACA,OAAA,GAAU,uBAAA;AAAA,IACR,OAAA,CAAQ,kBAAA"}

package/esm/supervisor/snapshot.mjs

@@ -1,16 +1,16 @@
 import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
 import { SupervisorDriftError } from "../errors/supervisor-drift-error.mjs";
 import "../errors/index.mjs";
-import { resolveDefaultStore } from "../config.mjs";
+import { resolveDefaultSnapshotStore } from "../config.mjs";
 
 //#region ../@warlock.js/ai/src/supervisor/snapshot.ts
 /**
-* Resolve the effective snapshot store: the supervisor's own
+* Resolve the effective {@link SnapshotStore}: the supervisor's own
 * `snapshotStore` field wins; absent that, fall back to the global
-* default set via `ai.config({ defaultStore })`.
+* default set via `ai.config({ defaultSnapshotStore })`.
 */
 function resolveSnapshotStore(config) {
-	return config.snapshotStore ?? resolveDefaultStore();
+	return config.snapshotStore ?? resolveDefaultSnapshotStore();
 }
 /**
 * Write the current run state to the resolved snapshot store. No-op
@@ -35,7 +35,7 @@ async function persistSupervisorSnapshot(params) {
 		savedAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
 	try {
-		await store.set(snapshotKey(params.runId), snapshot);
+		await store.save(snapshot);
 		return { ok: true };
 	} catch (error) {
 		return {
@@ -53,8 +53,8 @@ async function persistSupervisorSnapshot(params) {
 */
 async function loadSnapshotForResume(params) {
 	const store = resolveSnapshotStore(params.config);
-	if (!store) throw new SupervisorFailedError(`supervisor "${params.config.name}" has no store configured — set \`snapshotStore\` on the config or call \`ai.config({ defaultStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
-	const snapshot = await store.get(snapshotKey(params.runId)) ?? null;
+	if (!store) throw new SupervisorFailedError(`supervisor "${params.config.name}" has no store configured — set \`snapshotStore\` on the config or call \`ai.config({ defaultSnapshotStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
+	const snapshot = await store.load(params.runId) ?? null;
 	if (!snapshot) throw new SupervisorFailedError(`supervisor "${params.config.name}": no snapshot for runId "${params.runId}"`, { context: { runId: params.runId } });
 	if (!params.options?.force && snapshot.signature !== params.signature) throw new SupervisorDriftError(`supervisor "${params.config.name}" signature drift on resume`, {
 		savedSignature: snapshot.signature,
@@ -63,15 +63,7 @@ async function loadSnapshotForResume(params) {
 	});
 	return snapshot;
 }
-/**
-* Canonical key shape used in the KVStore. Prefixed so supervisor
-* snapshots don't collide with workflow / session snapshots in a
-* shared store.
-*/
-function snapshotKey(runId) {
-	return `supervisor:${runId}`;
-}
 
 //#endregion
-export { loadSnapshotForResume, persistSupervisorSnapshot, snapshotKey };
+export { loadSnapshotForResume, persistSupervisorSnapshot };
 //# sourceMappingURL=snapshot.mjs.map

package/esm/supervisor/snapshot.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/snapshot.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { IterationSnapshot } from \"../contracts/supervisor/iteration-snapshot.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { SupervisorResumeOptions } from \"../contracts/supervisor/supervisor-execute-options.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type {\n  SupervisorSnapshot,\n  SupervisorSnapshotStatus,\n} from \"../contracts/supervisor/supervisor-snapshot.type\";\nimport { SupervisorDriftError, SupervisorFailedError } from \"../errors\";\n\n/**\n * Resolve the effective snapshot store: the supervisor's own\n * `snapshotStore` field wins; absent that, fall back to the global\n * default set via `ai.config({ defaultStore })`.\n */\nfunction resolveSnapshotStore(config: SupervisorConfig<unknown>) {\n  return config.snapshotStore ?? resolveDefaultStore();\n}\n\nexport type PersistParams = {\n  config: SupervisorConfig<unknown>;\n  signature: string;\n  runId: string;\n  input: SupervisorInput;\n  startedAt: string;\n  iteration: number;\n  snapshots: IterationSnapshot[];\n  status: SupervisorSnapshotStatus;\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run state to the resolved snapshot store. No-op\n * (ok) when neither the supervisor's `snapshotStore` nor the global\n * `defaultStore` is configured. Failures are returned as\n * `{ ok: false }` rather than thrown so the engine can surface them\n * via events/logs without aborting the run — callers decide whether\n * a failed checkpoint is fatal.\n */\nexport async function persistSupervisorSnapshot(\n  params: PersistParams,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.config);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  const snapshot: SupervisorSnapshot = {\n    runId: params.runId,\n    supervisorName: params.config.name,\n    signature: params.signature,\n    input: params.input,\n    iteration: params.iteration,\n    snapshots: params.snapshots,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.set(snapshotKey(params.runId), snapshot);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Load a persisted snapshot for `resume()` and run the drift check.\n * Throws `SupervisorFailedError` when no store is configured or when\n * the run is missing; throws `SupervisorDriftError` when the stored\n * signature doesn't match the current definition (unless `force` is\n * set).\n */\nexport async function loadSnapshotForResume(params: {\n  config: SupervisorConfig<unknown>;\n  signature: string;\n  runId: string;\n  options?: SupervisorResumeOptions;\n}): Promise<SupervisorSnapshot> {\n  const store = resolveSnapshotStore(params.config);\n\n  if (!store) {\n    throw new SupervisorFailedError(\n      `supervisor \"${params.config.name}\" has no store configured — set \\`snapshotStore\\` on the config or call \\`ai.config({ defaultStore })\\` at boot before calling resume()`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  const snapshot =\n    (await store.get<SupervisorSnapshot>(snapshotKey(params.runId))) ?? null;\n\n  if (!snapshot) {\n    throw new SupervisorFailedError(\n      `supervisor \"${params.config.name}\": no snapshot for runId \"${params.runId}\"`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  if (!params.options?.force && snapshot.signature !== params.signature) {\n    throw new SupervisorDriftError(\n      `supervisor \"${params.config.name}\" signature drift on resume`,\n      {\n        savedSignature: snapshot.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snapshot;\n}\n\n/**\n * Canonical key shape used in the KVStore. Prefixed so supervisor\n * snapshots don't collide with workflow / session snapshots in a\n * shared store.\n */\nexport function snapshotKey(runId: string): string {\n  return `supervisor:${runId}`;\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAS,qBAAqB,QAAmC;CAC/D,OAAO,OAAO,iBAAiB,oBAAoB;AACrD;;;;;;;;;AAuBA,eAAsB,0BACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,MAAM;CAEhD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,MAAM,WAA+B;EACnC,OAAO,OAAO;EACd,gBAAgB,OAAO,OAAO;EAC9B,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,IAAI,YAAY,OAAO,KAAK,GAAG,QAAQ;EAEnD,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;;AASA,eAAsB,sBAAsB,QAKZ;CAC9B,MAAM,QAAQ,qBAAqB,OAAO,MAAM;CAEhD,IAAI,CAAC,OACH,MAAM,IAAI,sBACR,eAAe,OAAO,OAAO,KAAK,0IAClC,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,MAAM,WACH,MAAM,MAAM,IAAwB,YAAY,OAAO,KAAK,CAAC,KAAM;CAEtE,IAAI,CAAC,UACH,MAAM,IAAI,sBACR,eAAe,OAAO,OAAO,KAAK,4BAA4B,OAAO,MAAM,IAC3E,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,cAAc,OAAO,WAC1D,MAAM,IAAI,qBACR,eAAe,OAAO,OAAO,KAAK,8BAClC;EACE,gBAAgB,SAAS;EACzB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT;;;;;;AAOA,SAAgB,YAAY,OAAuB;CACjD,OAAO,cAAc;AACvB"}
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/snapshot.ts"],"sourcesContent":["import { resolveDefaultSnapshotStore } from \"../config\";\nimport type { IterationSnapshot } from \"../contracts/supervisor/iteration-snapshot.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { SupervisorResumeOptions } from \"../contracts/supervisor/supervisor-execute-options.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type {\n  SupervisorSnapshot,\n  SupervisorSnapshotStatus,\n} from \"../contracts/supervisor/supervisor-snapshot.type\";\nimport { SupervisorDriftError, SupervisorFailedError } from \"../errors\";\n\n/**\n * Resolve the effective {@link SnapshotStore}: the supervisor's own\n * `snapshotStore` field wins; absent that, fall back to the global\n * default set via `ai.config({ defaultSnapshotStore })`.\n */\nfunction resolveSnapshotStore(config: SupervisorConfig<unknown>) {\n  return config.snapshotStore ?? resolveDefaultSnapshotStore();\n}\n\nexport type PersistParams = {\n  config: SupervisorConfig<unknown>;\n  signature: string;\n  runId: string;\n  input: SupervisorInput;\n  startedAt: string;\n  iteration: number;\n  snapshots: IterationSnapshot[];\n  status: SupervisorSnapshotStatus;\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run state to the resolved snapshot store. No-op\n * (ok) when neither the supervisor's `snapshotStore` nor the global\n * `defaultStore` is configured. Failures are returned as\n * `{ ok: false }` rather than thrown so the engine can surface them\n * via events/logs without aborting the run — callers decide whether\n * a failed checkpoint is fatal.\n */\nexport async function persistSupervisorSnapshot(\n  params: PersistParams,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.config);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  const snapshot: SupervisorSnapshot = {\n    runId: params.runId,\n    supervisorName: params.config.name,\n    signature: params.signature,\n    input: params.input,\n    iteration: params.iteration,\n    snapshots: params.snapshots,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.save(snapshot);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Load a persisted snapshot for `resume()` and run the drift check.\n * Throws `SupervisorFailedError` when no store is configured or when\n * the run is missing; throws `SupervisorDriftError` when the stored\n * signature doesn't match the current definition (unless `force` is\n * set).\n */\nexport async function loadSnapshotForResume(params: {\n  config: SupervisorConfig<unknown>;\n  signature: string;\n  runId: string;\n  options?: SupervisorResumeOptions;\n}): Promise<SupervisorSnapshot> {\n  const store = resolveSnapshotStore(params.config);\n\n  if (!store) {\n    throw new SupervisorFailedError(\n      `supervisor \"${params.config.name}\" has no store configured — set \\`snapshotStore\\` on the config or call \\`ai.config({ defaultSnapshotStore })\\` at boot before calling resume()`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  const snapshot = (await store.load(params.runId)) ?? null;\n\n  if (!snapshot) {\n    throw new SupervisorFailedError(\n      `supervisor \"${params.config.name}\": no snapshot for runId \"${params.runId}\"`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  if (!params.options?.force && snapshot.signature !== params.signature) {\n    throw new SupervisorDriftError(\n      `supervisor \"${params.config.name}\" signature drift on resume`,\n      {\n        savedSignature: snapshot.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snapshot;\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAS,qBAAqB,QAAmC;CAC/D,OAAO,OAAO,iBAAiB,4BAA4B;AAC7D;;;;;;;;;AAuBA,eAAsB,0BACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,MAAM;CAEhD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,MAAM,WAA+B;EACnC,OAAO,OAAO;EACd,gBAAgB,OAAO,OAAO;EAC9B,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,KAAK,QAAQ;EAEzB,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;;AASA,eAAsB,sBAAsB,QAKZ;CAC9B,MAAM,QAAQ,qBAAqB,OAAO,MAAM;CAEhD,IAAI,CAAC,OACH,MAAM,IAAI,sBACR,eAAe,OAAO,OAAO,KAAK,kJAClC,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,MAAM,WAAY,MAAM,MAAM,KAAK,OAAO,KAAK,KAAM;CAErD,IAAI,CAAC,UACH,MAAM,IAAI,sBACR,eAAe,OAAO,OAAO,KAAK,4BAA4B,OAAO,MAAM,IAC3E,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,cAAc,OAAO,WAC1D,MAAM,IAAI,qBACR,eAAe,OAAO,OAAO,KAAK,8BAClC;EACE,gBAAgB,SAAS;EACzB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT"}

package/esm/supervisor/supervisor.mjs

@@ -80,6 +80,7 @@ function supervisor(config) {
 	}
 	const instance = {
 		name: config.name,
+		inputSchema: config.inputSchema,
 		signature,
 		execute,
 		stream,