@warlock.js/core 4.8.0 → 4.8.1

package/esm/ai/src/speech/speech.mjs

@@ -1,122 +0,0 @@
-import { AIError } from "../errors/ai-error.mjs";
-import { ProviderError } from "../errors/provider-error.mjs";
-import { computeCost } from "../utils/compute-cost.mjs";
-import { generateRunId } from "../utils/generate-run-id.mjs";
-import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
-import { notifyObservers } from "../observe/resolve-observers.mjs";
-
-//#region ../@warlock.js/ai/src/speech/speech.ts
-/**
-* Synthesize speech from text — the text-to-speech verb of the
-* output-modality track (Theme I), sibling to `ai.image()`. Wraps a
-* {@link SpeechModelContract} (from `openai.speech(...)`) in the
-* framework's uniform result contract:
-*
-* - **Never throws.** Provider failures surface as a typed `AIError` on
-*   `result.error`; `result.data` is then `undefined`.
-* - **Cost-truth.** `result.usage.cost` is filled per-character
-*   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same
-*   `Usage.cost` rollup as text.
-* - **Observable.** The completed {@link SpeechReport} routes to any
-*   registered `Observer` (panoptic, OTel, …) via the `observe` seam.
-*
-* @example
-* const openai = new OpenAISDK({ apiKey });
-* const { data, error } = await ai.speech({
-*   model: openai.speech({ name: "tts-1", voice: "alloy" }),
-*   text: "Your order has shipped.",
-*   format: "mp3",
-* });
-* if (!error) await fs.writeFile("ship.mp3", Buffer.from(data.audio.base64, "base64"));
-*/
-async function speech(params) {
-	const { model, text } = params;
-	const runId = generateRunId("speech");
-	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-	const startPerf = performance.now();
-	const usage = {
-		input: 0,
-		output: 0,
-		total: 0
-	};
-	let data;
-	let error;
-	let status = "completed";
-	let characters = 0;
-	try {
-		const response = await model.generate(text, {
-			voice: params.voice,
-			format: params.format,
-			speed: params.speed,
-			instructions: params.instructions,
-			signal: params.signal,
-			...params.options
-		});
-		Object.assign(usage, response.usage);
-		characters = response.characters;
-		if (usage.cost === void 0) {
-			const cost = computeSpeechCost(usage, characters, model.pricing);
-			if (cost !== void 0) usage.cost = cost;
-		}
-		data = { audio: response.audio };
-	} catch (thrown) {
-		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
-		status = params.signal?.aborted ? "cancelled" : "failed";
-	}
-	const report = {
-		runId,
-		rootRunId: runId,
-		name: params.name ?? "speech",
-		type: "speech",
-		status,
-		error,
-		startedAt,
-		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		duration: performance.now() - startPerf,
-		usage,
-		children: [],
-		model: {
-			name: model.name,
-			provider: model.provider
-		},
-		characters,
-		reportSchemaVersion: 1
-	};
-	stampReportLineage(report, {
-		rootRunId: runId,
-		sessionId: params.sessionId
-	});
-	await notifyObservers(params.observe, report);
-	return {
-		type: "speech",
-		data,
-		error,
-		usage,
-		report
-	};
-}
-/**
-* Price a TTS run: `perMillionCharacters × characters` (per-character
-* metering, attributed to `cost.input`) wins when configured, otherwise
-* the standard token math. Returns `undefined` when no usable pricing
-* is present.
-*/
-function computeSpeechCost(usage, characters, pricing) {
-	if (!pricing) return;
-	if (pricing.perMillionCharacters !== void 0) return {
-		input: characters * pricing.perMillionCharacters / 1e6,
-		output: 0
-	};
-	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
-		input: pricing.input,
-		output: pricing.output
-	});
-}
-/** Best-effort message for a non-`AIError` thrown value. */
-function toMessage(thrown) {
-	return thrown instanceof Error ? thrown.message : String(thrown);
-}
-
-//#endregion
-export { speech };
-//# sourceMappingURL=speech.mjs.map

package/esm/ai/src/speech/speech.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"speech.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/speech/speech.ts"],"sourcesContent":["import type {\n  GeneratedAudio,\n  SpeechModelContract,\n  SpeechModelPricing,\n} from \"../contracts/speech-model.contract\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { computeCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\n\n/** Parameters for {@link speech}. `model` comes from `sdk.speech({ name })`. */\nexport type SpeechParams = {\n  /** The TTS model to synthesize with. */\n  model: SpeechModelContract;\n  /** The text to speak. */\n  text: string;\n  /** Voice id/name; overrides the model's default voice. */\n  voice?: string;\n  /** Output container (`\"mp3\"` / `\"opus\"` / `\"aac\"` / `\"flac\"` / `\"wav\"` / `\"pcm\"`). */\n  format?: string;\n  /** Playback speed multiplier. */\n  speed?: number;\n  /** Extra tone/delivery steering (model-dependent). */\n  instructions?: string;\n  /** Cancellation handle. */\n  signal?: AbortSignal;\n  /** Observability routing — same `observe` seam as agents. */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"speech\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of a {@link speech} run. */\nexport type SpeechData = {\n  /** The synthesized audio, normalized to the discriminated shape. */\n  audio: GeneratedAudio;\n};\n\n/** The report node a {@link speech} run produces (`type: \"speech\"`). */\nexport type SpeechReport = BaseReport & {\n  type: \"speech\";\n  /** Identity of the TTS model this run used. */\n  model: { name: string; provider: string };\n  /** Number of input characters synthesized (0 on failure). */\n  characters: number;\n};\n\n/** Result envelope of {@link speech} — the uniform `{ data, error, usage, report }`. */\nexport type SpeechResult = ExecuteResult<SpeechData> & {\n  type: \"speech\";\n  report: SpeechReport;\n};\n\n/**\n * Synthesize speech from text — the text-to-speech verb of the\n * output-modality track (Theme I), sibling to `ai.image()`. Wraps a\n * {@link SpeechModelContract} (from `openai.speech(...)`) in the\n * framework's uniform result contract:\n *\n * - **Never throws.** Provider failures surface as a typed `AIError` on\n *   `result.error`; `result.data` is then `undefined`.\n * - **Cost-truth.** `result.usage.cost` is filled per-character\n *   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same\n *   `Usage.cost` rollup as text.\n * - **Observable.** The completed {@link SpeechReport} routes to any\n *   registered `Observer` (panoptic, OTel, …) via the `observe` seam.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error } = await ai.speech({\n *   model: openai.speech({ name: \"tts-1\", voice: \"alloy\" }),\n *   text: \"Your order has shipped.\",\n *   format: \"mp3\",\n * });\n * if (!error) await fs.writeFile(\"ship.mp3\", Buffer.from(data.audio.base64, \"base64\"));\n */\nexport async function speech(params: SpeechParams): Promise<SpeechResult> {\n  const { model, text } = params;\n\n  const runId = generateRunId(\"speech\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: SpeechData | undefined;\n  let error: AIError | undefined;\n  let status: SpeechReport[\"status\"] = \"completed\";\n  let characters = 0;\n\n  try {\n    const response = await model.generate(text, {\n      voice: params.voice,\n      format: params.format,\n      speed: params.speed,\n      instructions: params.instructions,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    Object.assign(usage, response.usage);\n    characters = response.characters;\n\n    if (usage.cost === undefined) {\n      const cost = computeSpeechCost(usage, characters, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { audio: response.audio };\n  } catch (thrown) {\n    error =\n      thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: SpeechReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"speech\",\n    type: \"speech\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    characters,\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"speech\", data, error, usage, report };\n}\n\n/**\n * Price a TTS run: `perMillionCharacters × characters` (per-character\n * metering, attributed to `cost.input`) wins when configured, otherwise\n * the standard token math. Returns `undefined` when no usable pricing\n * is present.\n */\nfunction computeSpeechCost(\n  usage: Usage,\n  characters: number,\n  pricing: SpeechModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  if (pricing.perMillionCharacters !== undefined) {\n    return { input: (characters * pricing.perMillionCharacters) / 1_000_000, output: 0 };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,eAAsB,OAAO,QAA6C;CACxE,MAAM,EAAE,OAAO,SAAS;CAExB,MAAM,QAAQ,cAAc,QAAQ;CACpC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAiC;CACrC,IAAI,aAAa;CAEjB,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,SAAS,MAAM;GAC1C,OAAO,OAAO;GACd,QAAQ,OAAO;GACf,OAAO,OAAO;GACd,cAAc,OAAO;GACrB,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,KAAK;EACnC,aAAa,SAAS;EAEtB,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,kBAAkB,OAAO,YAAY,MAAM,OAAO;GAC/D,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO,EAAE,OAAO,SAAS,MAAM;CACjC,SAAS,QAAQ;EACf,QACE,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAC7F,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAAuB;EAC3B;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD;EACA;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAU;EAAM;EAAO;EAAO;CAAO;AACtD;;;;;;;AAQA,SAAS,kBACP,OACA,YACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAGF,IAAI,QAAQ,yBAAyB,QACnC,OAAO;EAAE,OAAQ,aAAa,QAAQ,uBAAwB;EAAW,QAAQ;CAAE;CAGrF,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}

package/esm/ai/src/supervisor/as-tool.mjs

@@ -1,74 +0,0 @@
-import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
-import "../errors/index.mjs";
-import { compositeAsTool } from "../tool/tool.mjs";
-
-//#region ../@warlock.js/ai/src/supervisor/as-tool.ts
-/**
-* Wrap a `SupervisorContract` as a `ToolContract` so an outer agent
-* can invoke it from its tool-call loop. Mirrors
-* `workflow.asTool()` / `agent.asTool()` — same composition pattern,
-* same error-normalization behavior.
-*
-* Behavior:
-* - The tool's `name` mirrors the supervisor's `name` unless the
-*   caller overrides via `options.name`. Supervisors without a
-*   meaningful name throw `SupervisorFailedError` — an outer agent
-*   can't route to an anonymous tool.
-* - Tool `input` is the supplied schema; the validated value is
-*   coerced to a string (via `String()` for non-string values, or
-*   `JSON.stringify()` for objects) before being forwarded to
-*   `supervisor.execute(input)`. Consumers whose inputs need
-*   richer shaping should pre-format the string themselves.
-* - On `result.error`, the supervisor error is thrown so the tool
-*   wrapper catches it and produces a `ToolExecutionError` with
-*   `cause` set to the original typed supervisor error — the outer
-*   agent sees one uniform error class regardless of which
-*   primitive failed.
-*
-* @example
-* const support = ai.supervisor({ ... });
-* const supportTool = support.asTool({
-*   name: "handle_support_ticket",
-*   description: "Process a customer support ticket end-to-end.",
-*   inputSchema: z.object({ ticket: z.string() }),
-* });
-* const concierge = ai.agent({ model, tools: [supportTool] });
-*/
-function asTool(supervisorInstance, options) {
-	if (!supervisorInstance.name || typeof supervisorInstance.name !== "string") throw new SupervisorFailedError("supervisor.asTool(): supervisor must have a `name` to be wrapped as a tool");
-	return compositeAsTool({
-		name: options.name ?? supervisorInstance.name,
-		description: options.description ?? `Invoke supervisor "${supervisorInstance.name}" as a tool.`,
-		input: options.inputSchema,
-		execute: async (input, ctx) => {
-			const coerced = coerceInput(input);
-			const result = await supervisorInstance.execute(coerced, ctx?.signal ? { signal: ctx.signal } : void 0);
-			if (result.error) throw result.error;
-			return {
-				data: result.data,
-				usage: result.usage,
-				report: result.report
-			};
-		}
-	});
-}
-/**
-* Coerce a tool-input value into the `string` shape supervisor
-* `execute()` expects. Strings pass through; everything else gets
-* JSON-stringified so supervisors invoked via tool wrappers receive a
-* predictable textual input regardless of how the outer agent shaped
-* its call.
-*/
-function coerceInput(value) {
-	if (typeof value === "string") return value;
-	if (value === void 0 || value === null) return "";
-	try {
-		return JSON.stringify(value);
-	} catch {
-		return String(value);
-	}
-}
-
-//#endregion
-export { asTool };
-//# sourceMappingURL=as-tool.mjs.map

package/esm/ai/src/supervisor/as-tool.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/supervisor/as-tool.ts"],"sourcesContent":["import type {\n  SupervisorAsToolOptions,\n  SupervisorContract,\n} from \"../contracts/supervisor/supervisor.contract\";\nimport { SupervisorFailedError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"../tool/tool\";\n\n/**\n * Wrap a `SupervisorContract` as a `ToolContract` so an outer agent\n * can invoke it from its tool-call loop. Mirrors\n * `workflow.asTool()` / `agent.asTool()` — same composition pattern,\n * same error-normalization behavior.\n *\n * Behavior:\n * - The tool's `name` mirrors the supervisor's `name` unless the\n *   caller overrides via `options.name`. Supervisors without a\n *   meaningful name throw `SupervisorFailedError` — an outer agent\n *   can't route to an anonymous tool.\n * - Tool `input` is the supplied schema; the validated value is\n *   coerced to a string (via `String()` for non-string values, or\n *   `JSON.stringify()` for objects) before being forwarded to\n *   `supervisor.execute(input)`. Consumers whose inputs need\n *   richer shaping should pre-format the string themselves.\n * - On `result.error`, the supervisor error is thrown so the tool\n *   wrapper catches it and produces a `ToolExecutionError` with\n *   `cause` set to the original typed supervisor error — the outer\n *   agent sees one uniform error class regardless of which\n *   primitive failed.\n *\n * @example\n * const support = ai.supervisor({ ... });\n * const supportTool = support.asTool({\n *   name: \"handle_support_ticket\",\n *   description: \"Process a customer support ticket end-to-end.\",\n *   inputSchema: z.object({ ticket: z.string() }),\n * });\n * const concierge = ai.agent({ model, tools: [supportTool] });\n */\nexport function asTool<TOutput, TToolInput>(\n  supervisorInstance: SupervisorContract<TOutput>,\n  options: SupervisorAsToolOptions<TToolInput>,\n): ToolContract<TToolInput, TOutput> {\n  if (!supervisorInstance.name || typeof supervisorInstance.name !== \"string\") {\n    throw new SupervisorFailedError(\n      \"supervisor.asTool(): supervisor must have a `name` to be wrapped as a tool\",\n    );\n  }\n\n  return compositeAsTool<TToolInput, TOutput>({\n    name: options.name ?? supervisorInstance.name,\n    description: options.description ?? `Invoke supervisor \"${supervisorInstance.name}\" as a tool.`,\n    input: options.inputSchema,\n    execute: async (input, ctx) => {\n      const coerced = coerceInput(input);\n      // Relay the outer agent's cancellation signal so cancelling the\n      // parent aborts this nested supervisor run — its mid-iteration\n      // aborts then propagate into every in-flight child (C2).\n      const result = await supervisorInstance.execute(\n        coerced,\n        ctx?.signal ? { signal: ctx.signal } : undefined,\n      );\n\n      if (result.error) {\n        // Surface the typed supervisor error — the outer ToolContract\n        // wraps it as a ToolExecutionError with `cause` preserved.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Coerce a tool-input value into the `string` shape supervisor\n * `execute()` expects. Strings pass through; everything else gets\n * JSON-stringified so supervisors invoked via tool wrappers receive a\n * predictable textual input regardless of how the outer agent shaped\n * its call.\n */\nfunction coerceInput(value: unknown): string {\n  if (typeof value === \"string\") {\n    return value;\n  }\n\n  if (value === undefined || value === null) {\n    return \"\";\n  }\n\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,OACd,oBACA,SACmC;CACnC,IAAI,CAAC,mBAAmB,QAAQ,OAAO,mBAAmB,SAAS,UACjE,MAAM,IAAI,sBACR,4EACF;CAGF,OAAO,gBAAqC;EAC1C,MAAM,QAAQ,QAAQ,mBAAmB;EACzC,aAAa,QAAQ,eAAe,sBAAsB,mBAAmB,KAAK;EAClF,OAAO,QAAQ;EACf,SAAS,OAAO,OAAO,QAAQ;GAC7B,MAAM,UAAU,YAAY,KAAK;GAIjC,MAAM,SAAS,MAAM,mBAAmB,QACtC,SACA,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MACzC;GAEA,IAAI,OAAO,OAGT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;;;;AASA,SAAS,YAAY,OAAwB;CAC3C,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO;CAGT,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF"}

package/esm/ai/src/supervisor/cancellation.mjs

@@ -1,22 +0,0 @@
-import { SupervisorCancelledError } from "../errors/supervisor-cancelled-error.mjs";
-import "../errors/index.mjs";
-
-//#region ../@warlock.js/ai/src/supervisor/cancellation.ts
-/**
-* Build a `SupervisorCancelledError` from an `AbortSignal`. Extracts a
-* human-readable reason from `signal.reason` whether it was a string,
-* an `Error`, or some other value. Used at between-iteration boundaries
-* and on any mid-iteration cancellation path.
-*/
-function createCancelledError(signal) {
-	const reason = signal?.reason;
-	const reasonText = typeof reason === "string" ? reason : reason instanceof Error ? reason.message : reason === void 0 ? "" : String(reason);
-	return new SupervisorCancelledError(`supervisor cancelled${reasonText ? `: ${reasonText}` : ""}`, {
-		cancelledAt: (/* @__PURE__ */ new Date()).toISOString(),
-		reason: reasonText
-	});
-}
-
-//#endregion
-export { createCancelledError };
-//# sourceMappingURL=cancellation.mjs.map

package/esm/ai/src/supervisor/cancellation.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"cancellation.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/supervisor/cancellation.ts"],"sourcesContent":["import { SupervisorCancelledError } from \"../errors\";\n\n/**\n * Build a `SupervisorCancelledError` from an `AbortSignal`. Extracts a\n * human-readable reason from `signal.reason` whether it was a string,\n * an `Error`, or some other value. Used at between-iteration boundaries\n * and on any mid-iteration cancellation path.\n */\nexport function createCancelledError(\n  signal: AbortSignal | undefined,\n): SupervisorCancelledError {\n  const reason = signal?.reason;\n  const reasonText =\n    typeof reason === \"string\"\n      ? reason\n      : reason instanceof Error\n        ? reason.message\n        : reason === undefined\n          ? \"\"\n          : String(reason);\n\n  return new SupervisorCancelledError(\n    `supervisor cancelled${reasonText ? `: ${reasonText}` : \"\"}`,\n    { cancelledAt: new Date().toISOString(), reason: reasonText },\n  );\n}\n"],"mappings":";;;;;;;;;;AAQA,SAAgB,qBACd,QAC0B;CAC1B,MAAM,SAAS,QAAQ;CACvB,MAAM,aACJ,OAAO,WAAW,WACd,SACA,kBAAkB,QAChB,OAAO,UACP,WAAW,SACT,KACA,OAAO,MAAM;CAEvB,OAAO,IAAI,yBACT,uBAAuB,aAAa,KAAK,eAAe,MACxD;EAAE,8BAAa,IAAI,KAAK,EAAC,CAAC,YAAY;EAAG,QAAQ;CAAW,CAC9D;AACF"}

package/esm/ai/src/supervisor/decide.mjs

@@ -1,272 +0,0 @@
-import { AIError } from "../errors/ai-error.mjs";
-import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
-import { SupervisorRoutingError } from "../errors/supervisor-routing-error.mjs";
-import "../errors/index.mjs";
-import { END } from "../contracts/end.type.mjs";
-import { buildRouterContextMessage } from "./router-prompt.mjs";
-
-//#region ../@warlock.js/ai/src/supervisor/decide.ts
-/**
-* Unified dispatch decision entry — calls either the `route` callback
-* or the `router` agent based on the supervisor's configured mode and
-* normalizes the result into a `DispatchDecision`. Runtime validates
-* every routing value against the configured agent keys; unknown keys
-* surface as `SupervisorRoutingError`.
-*/
-async function decide(params) {
-	if (params.useInitialAgent && params.config.initialAgent) {
-		const intent = params.config.initialAgent;
-		validateKey(intent, params.entries);
-		return {
-			kind: "dispatch",
-			intents: [intent],
-			source: "initialAgent",
-			raw: intent,
-			durationMs: 0
-		};
-	}
-	if (params.config.route) return decideViaCallback(params);
-	if (params.config.router) return decideViaRouter(params);
-	throw new SupervisorFailedError(`ai.supervisor("${params.config.name}"): neither \`route\` nor \`router\` is configured — factory validation should have prevented this`, { context: { authoring: true } });
-}
-async function decideViaCallback(params) {
-	const started = performance.now();
-	const ctx = {
-		iteration: params.iteration,
-		input: params.input,
-		state: params.state,
-		iterations: params.iterations,
-		feedback: typeof params.evaluateFeedback?.feedback === "string" ? params.evaluateFeedback.feedback : void 0,
-		evaluateFeedback: params.evaluateFeedback,
-		context: params.context,
-		history: params.history,
-		goal: params.goal,
-		classifier: params.classifier
-	};
-	let raw;
-	try {
-		raw = await params.config.route(ctx);
-	} catch (thrown) {
-		throw wrapRouteError(params.config.name, thrown);
-	}
-	const durationMs = performance.now() - started;
-	return normalize(raw, params.entries, "route", durationMs);
-}
-async function decideViaRouter(params) {
-	const { agent, placeholders, inputOverride, historySlicer } = resolveRouterEntry(params.config.router);
-	const started = performance.now();
-	const routeCtx = {
-		iteration: params.iteration,
-		input: params.input,
-		state: params.state,
-		iterations: params.iterations,
-		feedback: typeof params.evaluateFeedback?.feedback === "string" ? params.evaluateFeedback.feedback : void 0,
-		evaluateFeedback: params.evaluateFeedback,
-		context: params.context,
-		history: params.history,
-		goal: params.goal
-	};
-	const userMessage = inputOverride?.(routeCtx) ?? buildRouterContextMessage({
-		entries: params.entries,
-		iteration: params.iteration,
-		maxIterations: params.maxIterations,
-		iterations: params.iterations,
-		input: params.input,
-		state: params.state,
-		feedback: routeCtx.feedback,
-		supervisorPrompt: resolveSupervisorPromptText(params.config),
-		goal: params.goal
-	});
-	const resolvedPlaceholders = placeholders?.(routeCtx);
-	const routerHistory = resolveRouterHistory(historySlicer, routeCtx, params.history, params.config.historyWindow?.router);
-	const routerResult = await agent.execute(userMessage, {
-		signal: params.signal,
-		output: ROUTER_OUTPUT_SCHEMA,
-		...resolvedPlaceholders ? { placeholders: resolvedPlaceholders } : {},
-		...routerHistory.length > 0 ? { history: routerHistory } : {}
-	});
-	const durationMs = performance.now() - started;
-	if (routerResult.error) throw routerResult.error instanceof AIError ? routerResult.error : new SupervisorFailedError(`router agent failed`, { cause: routerResult.error });
-	const data = routerResult.data;
-	if (!data || typeof data !== "object") throw new SupervisorRoutingError(`router agent returned no structured \`next\` — did its output schema include { next, reasoning? }?`, {
-		returned: data,
-		availableKeys: [...params.entries.keys()]
-	});
-	const rawNext = data.next;
-	const reasoning = data.reasoning;
-	if (rawNext === void 0) throw new SupervisorRoutingError(`router agent output missing \`next\` field`, {
-		returned: data,
-		availableKeys: [...params.entries.keys()]
-	});
-	return {
-		...normalize(rawNext, params.entries, "router", durationMs),
-		reasoning: typeof reasoning === "string" ? reasoning : void 0,
-		usage: routerResult.usage,
-		routerReport: routerResult.report
-	};
-}
-/**
-* Normalize the `router` config field — accepts either a bare
-* `AgentContract` (shorthand) or a full `RouterEntry` — into a
-* uniform `{ agent, placeholders?, inputOverride? }` triple. Centralized
-* so the dispatch path doesn't branch on shape.
-*/
-function resolveRouterEntry(router) {
-	if (typeof router.execute === "function") return { agent: router };
-	const entry = router;
-	return {
-		agent: entry.agent,
-		placeholders: entry.placeholders,
-		inputOverride: entry.input,
-		historySlicer: entry.history
-	};
-}
-/**
-* Resolve the supervisor's own `systemPrompt` (string or contract)
-* into plain text. Returns `undefined` when the supervisor didn't
-* configure one. The resolved text is surfaced in the per-turn
-* router user message so the router sees team/domain context without
-* disturbing the router agent's own factory-level system prompt —
-* functionally equivalent to prepending, without requiring an API
-* expansion on `AgentContract` to read the router's system prompt.
-*/
-function resolveSupervisorPromptText(config) {
-	if (!config.systemPrompt) return;
-	return typeof config.systemPrompt === "string" ? config.systemPrompt : config.systemPrompt.resolve();
-}
-/**
-* Convert the raw routing value (callback return OR router agent
-* `next` field) into a canonical `DispatchDecision`, validating every
-* named intent against the supervisor's `intents` map.
-*/
-function normalize(raw, entries, source, durationMs) {
-	if (isEnd(raw)) return {
-		kind: "end",
-		source,
-		raw,
-		durationMs
-	};
-	if (typeof raw === "string") {
-		validateKey(raw, entries);
-		return {
-			kind: "dispatch",
-			intents: [raw],
-			source,
-			raw,
-			durationMs
-		};
-	}
-	if (Array.isArray(raw)) {
-		if (raw.length === 0) throw new SupervisorRoutingError(`router returned an empty array — must be a non-empty list of agent intents`, {
-			returned: raw,
-			availableKeys: [...entries.keys()]
-		});
-		for (const intent of raw) {
-			if (typeof intent !== "string") throw new SupervisorRoutingError(`router returned a non-string inside its fan-out array`, {
-				returned: raw,
-				availableKeys: [...entries.keys()]
-			});
-			validateKey(intent, entries);
-		}
-		return {
-			kind: "dispatch",
-			intents: raw,
-			source,
-			raw,
-			durationMs
-		};
-	}
-	throw new SupervisorRoutingError(`router returned an unsupported value — expected a string, string[], or END`, {
-		returned: raw,
-		availableKeys: [...entries.keys()]
-	});
-}
-function validateKey(intent, entries) {
-	if (!entries.has(intent)) throw new SupervisorRoutingError(`router returned unknown agent key "${intent}"`, {
-		returned: intent,
-		availableKeys: [...entries.keys()]
-	});
-}
-function isEnd(value) {
-	return value === END;
-}
-/**
-* Resolve the history slice forwarded to the router agent. Mirrors
-* `SupervisorExecution.resolveHistoryFor("router", ...)` — duplicated
-* here so the standalone `decide()` function stays callable without
-* threading the execution instance through. Precedence is identical:
-* entry slicer > `historyWindow.router` > full history.
-*/
-function resolveRouterHistory(slicer, routeCtx, full, window) {
-	if (slicer) {
-		const sliced = slicer(routeCtx);
-		return sliced ? [...sliced] : [];
-	}
-	if (window === void 0 || window < 0) return [...full];
-	if (window === 0) return [];
-	return full.slice(-window);
-}
-/**
-* JSON Schema form of the canonical router output shape. Surfaced via
-* the Standard JSON Schema V1 extension path (`["~standard"].jsonSchema.input`)
-* so `extractJsonSchema()` can pull it for native structured-output
-* enforcement on capable providers (OpenAI strict json_schema mode,
-* Anthropic tool-use shape, etc.). Without this, the model is told to
-* emit JSON only via soft system-prompt instruction — fragile, and
-* skipped entirely when the model advertises `structuredOutput: true`.
-*
-* `next` is intentionally `string` (not a union with arrays) because
-* OpenAI strict mode rejects polymorphic root types — fan-out via
-* `string[]` is still validated at the framework layer; the model
-* just emits a single intent name (or the END sentinel) and the
-* supervisor's own normalizer handles the rest.
-*/
-const ROUTER_OUTPUT_JSON_SCHEMA = {
-	type: "object",
-	properties: {
-		next: {
-			type: "string",
-			description: "Name of the agent to dispatch next, or the END sentinel to terminate the run."
-		},
-		reasoning: {
-			type: "string",
-			description: "One-sentence justification for the routing choice."
-		}
-	},
-	required: ["next", "reasoning"],
-	additionalProperties: false
-};
-/**
-* Canonical Standard Schema the supervisor injects when calling the
-* router agent. Pragmatic — accepts any `next` shape the router can
-* plausibly emit (`string`, `string[]`, or the `END` literal) plus an
-* optional `reasoning` field. Rejects anything else so a broken
-* router output surfaces cleanly via the agent's own validation path.
-*
-* Exposes `["~standard"].jsonSchema.input()` (Standard JSON Schema V1)
-* so capable providers enforce the shape natively rather than relying
-* on prompt-side coaching.
-*/
-const ROUTER_OUTPUT_SCHEMA = { "~standard": {
-	version: 1,
-	vendor: "warlock-supervisor",
-	jsonSchema: { input: () => ROUTER_OUTPUT_JSON_SCHEMA },
-	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 : void 0
-		} };
-	}
-} };
-function wrapRouteError(supervisorName, thrown) {
-	if (thrown instanceof AIError) return thrown;
-	return new SupervisorFailedError(`\`route\` callback threw in supervisor "${supervisorName}": ${thrown instanceof Error ? thrown.message : String(thrown)}`, { cause: thrown });
-}
-
-//#endregion
-export { decide };
-//# sourceMappingURL=decide.mjs.map

package/esm/ai/src/supervisor/decide.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"decide.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/supervisor/decide.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport { END, type EndSentinel } from \"../contracts/end.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { IterationSnapshot } from \"../contracts/supervisor/iteration-snapshot.type\";\nimport type { Next } from \"../contracts/supervisor/next.type\";\nimport type { RouteContext } from \"../contracts/supervisor/route-context.type\";\nimport type { RouterEntry } from \"../contracts/supervisor/router-entry.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport { AIError, SupervisorFailedError, SupervisorRoutingError } from \"../errors\";\nimport type { ResolvedIntentEntry } from \"./entries\";\nimport { buildRouterContextMessage } from \"./router-prompt\";\n\n/**\n * Outcome of one dispatch decision — what the iteration loop needs to\n * act on. `kind: \"end\"` signals termination; `kind: \"dispatch\"` carries\n * the resolved intents (always an array; single-agent dispatch has\n * length 1). `source` records which path made the call so the\n * iteration snapshot can surface it to debuggers.\n */\nexport type DispatchDecision =\n  | {\n      kind: \"end\";\n      source: \"route\" | \"router\" | \"initialAgent\" | \"classifier\";\n      raw: Next;\n      reasoning?: string;\n      durationMs: number;\n      usage?: { input: number; output: number; total: number };\n      /** Full router-agent report when this decision came from a router. */\n      routerReport?: BaseReport;\n    }\n  | {\n      kind: \"dispatch\";\n      intents: string[];\n      source: \"route\" | \"router\" | \"initialAgent\" | \"classifier\";\n      raw: Next;\n      reasoning?: string;\n      durationMs: number;\n      usage?: { input: number; output: number; total: number };\n      /** Full router-agent report when this decision came from a router. */\n      routerReport?: BaseReport;\n    };\n\nexport type DecideParams = {\n  config: SupervisorConfig<unknown>;\n  entries: Map<string, ResolvedIntentEntry>;\n  iteration: number;\n  maxIterations: number;\n  iterations: IterationSnapshot[];\n  input: SupervisorInput;\n  /**\n   * Per-execute state accumulator at the start of this iteration.\n   * Threaded into `RouteContext` for the route callback and\n   * rendered into the router prompt so routing decisions can be\n   * state-aware (Q14).\n   */\n  state: Record<string, unknown>;\n  /**\n   * Frozen request-scoped bag from the `execute({ context })` call —\n   * surfaced on `RouteContext.context` for both `route` callbacks\n   * and `RouterEntry.placeholders` / `RouterEntry.input` resolvers.\n   */\n  context: Readonly<Record<string, unknown>>;\n  /**\n   * Frozen prior-conversation history from `execute({ history })` —\n   * surfaced on `RouteContext.history` and forwarded to the router\n   * agent as `agent.execute(input, { history })` so router decisions\n   * are conversation-aware.\n   */\n  history: ReadonlyArray<Message>;\n  /**\n   * Resolved natural-language objective from `SupervisorConfig.goal`\n   * (materialized to plain text at supervisor construction). Surfaced\n   * on `RouteContext.goal` for `route` / `RouterEntry` resolvers, and\n   * injected into the router agent's per-turn user message via\n   * `buildRouterContextMessage`. `undefined` when no goal was set.\n   */\n  goal: string | undefined;\n  evaluateFeedback?: RouteContext[\"evaluateFeedback\"];\n  /**\n   * Forensic record of the iter-0 classifier (Phase 7). Threaded into\n   * `RouteContext.classifier` so route callbacks and router-agent\n   * input composers can read the classification trail without\n   * re-parsing state.\n   */\n  classifier?: RouteContext[\"classifier\"];\n  signal?: AbortSignal;\n  /**\n   * Override for the very first iteration — when `initialAgent` is\n   * set, the first turn skips `route`/`router` and dispatches the\n   * named intent directly. `runIteration` passes `true` only on turn\n   * 0 when the config has `initialAgent`.\n   */\n  useInitialAgent?: boolean;\n};\n\n/**\n * Unified dispatch decision entry — calls either the `route` callback\n * or the `router` agent based on the supervisor's configured mode and\n * normalizes the result into a `DispatchDecision`. Runtime validates\n * every routing value against the configured agent keys; unknown keys\n * surface as `SupervisorRoutingError`.\n */\nexport async function decide(params: DecideParams): Promise<DispatchDecision> {\n  if (params.useInitialAgent && params.config.initialAgent) {\n    const intent = params.config.initialAgent;\n    validateKey(intent, params.entries);\n\n    return {\n      kind: \"dispatch\",\n      intents: [intent],\n      source: \"initialAgent\",\n      raw: intent,\n      durationMs: 0,\n    };\n  }\n\n  if (params.config.route) {\n    return decideViaCallback(params);\n  }\n\n  if (params.config.router) {\n    return decideViaRouter(params);\n  }\n\n  throw new SupervisorFailedError(\n    `ai.supervisor(\"${params.config.name}\"): neither \\`route\\` nor \\`router\\` is configured — factory validation should have prevented this`,\n    { context: { authoring: true } },\n  );\n}\n\nasync function decideViaCallback(params: DecideParams): Promise<DispatchDecision> {\n  const started = performance.now();\n  const ctx: RouteContext = {\n    iteration: params.iteration,\n    input: params.input,\n    state: params.state,\n    iterations: params.iterations,\n    feedback:\n      typeof params.evaluateFeedback?.feedback === \"string\"\n        ? params.evaluateFeedback.feedback\n        : undefined,\n    evaluateFeedback: params.evaluateFeedback,\n    context: params.context,\n    history: params.history,\n    goal: params.goal,\n    classifier: params.classifier,\n  };\n\n  let raw: Next;\n\n  try {\n    raw = await params.config.route!(ctx);\n  } catch (thrown) {\n    throw wrapRouteError(params.config.name, thrown);\n  }\n\n  const durationMs = performance.now() - started;\n\n  return normalize(raw, params.entries, \"route\", durationMs);\n}\n\nasync function decideViaRouter(params: DecideParams): Promise<DispatchDecision> {\n  const { agent, placeholders, inputOverride, historySlicer } = resolveRouterEntry(\n    params.config.router!,\n  );\n  const started = performance.now();\n\n  const routeCtx: RouteContext = {\n    iteration: params.iteration,\n    input: params.input,\n    state: params.state,\n    iterations: params.iterations,\n    feedback:\n      typeof params.evaluateFeedback?.feedback === \"string\"\n        ? params.evaluateFeedback.feedback\n        : undefined,\n    evaluateFeedback: params.evaluateFeedback,\n    context: params.context,\n    history: params.history,\n    goal: params.goal,\n  };\n\n  const userMessage =\n    inputOverride?.(routeCtx) ??\n    buildRouterContextMessage({\n      entries: params.entries,\n      iteration: params.iteration,\n      maxIterations: params.maxIterations,\n      iterations: params.iterations,\n      input: params.input,\n      state: params.state,\n      feedback: routeCtx.feedback,\n      supervisorPrompt: resolveSupervisorPromptText(params.config),\n      goal: params.goal,\n    });\n\n  const resolvedPlaceholders = placeholders?.(routeCtx);\n\n  // Inject the canonical router output schema so the supervisor gets\n  // a predictable `{ next, reasoning? }` shape regardless of what the\n  // user scripted on the router agent. Lets the router stay a plain\n  // agent — no supervisor-specific config needed at construction.\n  const routerHistory = resolveRouterHistory(\n    historySlicer,\n    routeCtx,\n    params.history,\n    params.config.historyWindow?.router,\n  );\n\n  const routerResult = await agent.execute(userMessage, {\n    signal: params.signal,\n    output: ROUTER_OUTPUT_SCHEMA as unknown as StandardSchemaV1<{\n      next: Next;\n      reasoning?: string;\n    }>,\n    ...(resolvedPlaceholders ? { placeholders: resolvedPlaceholders } : {}),\n    ...(routerHistory.length > 0 ? { history: routerHistory } : {}),\n  });\n\n  const durationMs = performance.now() - started;\n\n  if (routerResult.error) {\n    throw routerResult.error instanceof AIError\n      ? routerResult.error\n      : new SupervisorFailedError(`router agent failed`, {\n          cause: routerResult.error,\n        });\n  }\n\n  const data = routerResult.data;\n\n  if (!data || typeof data !== \"object\") {\n    throw new SupervisorRoutingError(\n      `router agent returned no structured \\`next\\` — did its output schema include { next, reasoning? }?`,\n      { returned: data, availableKeys: [...params.entries.keys()] },\n    );\n  }\n\n  const rawNext = (data as { next?: unknown }).next;\n  const reasoning = (data as { reasoning?: unknown }).reasoning;\n\n  if (rawNext === undefined) {\n    throw new SupervisorRoutingError(`router agent output missing \\`next\\` field`, {\n      returned: data,\n      availableKeys: [...params.entries.keys()],\n    });\n  }\n\n  const decision = normalize(rawNext as Next, params.entries, \"router\", durationMs);\n\n  return {\n    ...decision,\n    reasoning: typeof reasoning === \"string\" ? reasoning : undefined,\n    usage: routerResult.usage,\n    routerReport: routerResult.report,\n  };\n}\n\n/**\n * Normalize the `router` config field — accepts either a bare\n * `AgentContract` (shorthand) or a full `RouterEntry` — into a\n * uniform `{ agent, placeholders?, inputOverride? }` triple. Centralized\n * so the dispatch path doesn't branch on shape.\n */\nfunction resolveRouterEntry(router: AgentContract<unknown> | RouterEntry): {\n  agent: AgentContract<unknown>;\n  placeholders?: RouterEntry[\"placeholders\"];\n  inputOverride?: RouterEntry[\"input\"];\n  historySlicer?: RouterEntry[\"history\"];\n} {\n  if (typeof (router as { execute?: unknown }).execute === \"function\") {\n    return { agent: router as AgentContract<unknown> };\n  }\n\n  const entry = router as RouterEntry;\n\n  return {\n    agent: entry.agent,\n    placeholders: entry.placeholders,\n    inputOverride: entry.input,\n    historySlicer: entry.history,\n  };\n}\n\n/**\n * Resolve the supervisor's own `systemPrompt` (string or contract)\n * into plain text. Returns `undefined` when the supervisor didn't\n * configure one. The resolved text is surfaced in the per-turn\n * router user message so the router sees team/domain context without\n * disturbing the router agent's own factory-level system prompt —\n * functionally equivalent to prepending, without requiring an API\n * expansion on `AgentContract` to read the router's system prompt.\n */\nfunction resolveSupervisorPromptText(config: SupervisorConfig<unknown>): string | undefined {\n  if (!config.systemPrompt) {\n    return undefined;\n  }\n\n  return typeof config.systemPrompt === \"string\"\n    ? config.systemPrompt\n    : config.systemPrompt.resolve();\n}\n\n/**\n * Convert the raw routing value (callback return OR router agent\n * `next` field) into a canonical `DispatchDecision`, validating every\n * named intent against the supervisor's `intents` map.\n */\nfunction normalize(\n  raw: Next,\n  entries: Map<string, ResolvedIntentEntry>,\n  source: \"route\" | \"router\",\n  durationMs: number,\n): DispatchDecision {\n  if (isEnd(raw)) {\n    return { kind: \"end\", source, raw, durationMs };\n  }\n\n  if (typeof raw === \"string\") {\n    validateKey(raw, entries);\n\n    return {\n      kind: \"dispatch\",\n      intents: [raw],\n      source,\n      raw,\n      durationMs,\n    };\n  }\n\n  if (Array.isArray(raw)) {\n    if (raw.length === 0) {\n      throw new SupervisorRoutingError(\n        `router returned an empty array — must be a non-empty list of agent intents`,\n        { returned: raw, availableKeys: [...entries.keys()] },\n      );\n    }\n\n    for (const intent of raw) {\n      if (typeof intent !== \"string\") {\n        throw new SupervisorRoutingError(`router returned a non-string inside its fan-out array`, {\n          returned: raw,\n          availableKeys: [...entries.keys()],\n        });\n      }\n\n      validateKey(intent, entries);\n    }\n\n    return {\n      kind: \"dispatch\",\n      intents: raw,\n      source,\n      raw,\n      durationMs,\n    };\n  }\n\n  throw new SupervisorRoutingError(\n    `router returned an unsupported value — expected a string, string[], or END`,\n    { returned: raw, availableKeys: [...entries.keys()] },\n  );\n}\n\nfunction validateKey(intent: string, entries: Map<string, ResolvedIntentEntry>): void {\n  if (!entries.has(intent)) {\n    throw new SupervisorRoutingError(`router returned unknown agent key \"${intent}\"`, {\n      returned: intent,\n      availableKeys: [...entries.keys()],\n    });\n  }\n}\n\nfunction isEnd(value: unknown): value is EndSentinel {\n  return value === END;\n}\n\n/**\n * Resolve the history slice forwarded to the router agent. Mirrors\n * `SupervisorExecution.resolveHistoryFor(\"router\", ...)` — duplicated\n * here so the standalone `decide()` function stays callable without\n * threading the execution instance through. Precedence is identical:\n * entry slicer > `historyWindow.router` > full history.\n */\nfunction resolveRouterHistory(\n  slicer: RouterEntry[\"history\"] | undefined,\n  routeCtx: RouteContext,\n  full: ReadonlyArray<Message>,\n  window: number | undefined,\n): Message[] {\n  if (slicer) {\n    const sliced = slicer(routeCtx);\n    return sliced ? [...sliced] : [];\n  }\n\n  if (window === undefined || window < 0) {\n    return [...full];\n  }\n\n  if (window === 0) {\n    return [];\n  }\n\n  return full.slice(-window);\n}\n\n/**\n * JSON Schema form of the canonical router output shape. Surfaced via\n * the Standard JSON Schema V1 extension path (`[\"~standard\"].jsonSchema.input`)\n * so `extractJsonSchema()` can pull it for native structured-output\n * enforcement on capable providers (OpenAI strict json_schema mode,\n * Anthropic tool-use shape, etc.). Without this, the model is told to\n * emit JSON only via soft system-prompt instruction — fragile, and\n * skipped entirely when the model advertises `structuredOutput: true`.\n *\n * `next` is intentionally `string` (not a union with arrays) because\n * OpenAI strict mode rejects polymorphic root types — fan-out via\n * `string[]` is still validated at the framework layer; the model\n * just emits a single intent name (or the END sentinel) and the\n * supervisor's own normalizer handles the rest.\n */\nconst ROUTER_OUTPUT_JSON_SCHEMA = {\n  type: \"object\",\n  properties: {\n    next: {\n      type: \"string\",\n      description: \"Name of the agent to dispatch next, or the END sentinel to terminate the run.\",\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/**\n * Canonical Standard Schema the supervisor injects when calling the\n * router agent. Pragmatic — accepts any `next` shape the router can\n * plausibly emit (`string`, `string[]`, or the `END` literal) plus an\n * optional `reasoning` field. Rejects anything else so a broken\n * router output surfaces cleanly via the agent's own validation path.\n *\n * Exposes `[\"~standard\"].jsonSchema.input()` (Standard JSON Schema V1)\n * so capable providers enforce the shape natively rather than relying\n * on prompt-side coaching.\n */\nconst ROUTER_OUTPUT_SCHEMA: StandardSchemaV1<{\n  next: Next;\n  reasoning?: string;\n}> = {\n  \"~standard\": {\n    version: 1,\n    vendor: \"warlock-supervisor\",\n    jsonSchema: {\n      input: () => ROUTER_OUTPUT_JSON_SCHEMA,\n    },\n    validate(value: unknown): StandardSchemaV1.Result<{ next: Next; reasoning?: string }> {\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            {\n              message: \"router output `next` must be a string, string[], or the END sentinel\",\n            },\n          ],\n        };\n      }\n\n      const reasoning = typeof record.reasoning === \"string\" ? record.reasoning : undefined;\n\n      return {\n        value: { next: rawNext as Next, reasoning },\n      };\n    },\n  } as StandardSchemaV1<{ next: Next; reasoning?: string }>[\"~standard\"] & {\n    jsonSchema: { input: () => Record<string, unknown> };\n  },\n};\n\nfunction wrapRouteError(supervisorName: string, thrown: unknown): AIError {\n  if (thrown instanceof AIError) {\n    return thrown;\n  }\n\n  const message = thrown instanceof Error ? thrown.message : String(thrown);\n\n  return new SupervisorFailedError(\n    `\\`route\\` callback threw in supervisor \"${supervisorName}\": ${message}`,\n    { cause: thrown },\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;AAyGA,eAAsB,OAAO,QAAiD;CAC5E,IAAI,OAAO,mBAAmB,OAAO,OAAO,cAAc;EACxD,MAAM,SAAS,OAAO,OAAO;EAC7B,YAAY,QAAQ,OAAO,OAAO;EAElC,OAAO;GACL,MAAM;GACN,SAAS,CAAC,MAAM;GAChB,QAAQ;GACR,KAAK;GACL,YAAY;EACd;CACF;CAEA,IAAI,OAAO,OAAO,OAChB,OAAO,kBAAkB,MAAM;CAGjC,IAAI,OAAO,OAAO,QAChB,OAAO,gBAAgB,MAAM;CAG/B,MAAM,IAAI,sBACR,kBAAkB,OAAO,OAAO,KAAK,qGACrC,EAAE,SAAS,EAAE,WAAW,KAAK,EAAE,CACjC;AACF;AAEA,eAAe,kBAAkB,QAAiD;CAChF,MAAM,UAAU,YAAY,IAAI;CAChC,MAAM,MAAoB;EACxB,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,OAAO,OAAO;EACd,YAAY,OAAO;EACnB,UACE,OAAO,OAAO,kBAAkB,aAAa,WACzC,OAAO,iBAAiB,WACxB;EACN,kBAAkB,OAAO;EACzB,SAAS,OAAO;EAChB,SAAS,OAAO;EAChB,MAAM,OAAO;EACb,YAAY,OAAO;CACrB;CAEA,IAAI;CAEJ,IAAI;EACF,MAAM,MAAM,OAAO,OAAO,MAAO,GAAG;CACtC,SAAS,QAAQ;EACf,MAAM,eAAe,OAAO,OAAO,MAAM,MAAM;CACjD;CAEA,MAAM,aAAa,YAAY,IAAI,IAAI;CAEvC,OAAO,UAAU,KAAK,OAAO,SAAS,SAAS,UAAU;AAC3D;AAEA,eAAe,gBAAgB,QAAiD;CAC9E,MAAM,EAAE,OAAO,cAAc,eAAe,kBAAkB,mBAC5D,OAAO,OAAO,MAChB;CACA,MAAM,UAAU,YAAY,IAAI;CAEhC,MAAM,WAAyB;EAC7B,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,OAAO,OAAO;EACd,YAAY,OAAO;EACnB,UACE,OAAO,OAAO,kBAAkB,aAAa,WACzC,OAAO,iBAAiB,WACxB;EACN,kBAAkB,OAAO;EACzB,SAAS,OAAO;EAChB,SAAS,OAAO;EAChB,MAAM,OAAO;CACf;CAEA,MAAM,cACJ,gBAAgB,QAAQ,KACxB,0BAA0B;EACxB,SAAS,OAAO;EAChB,WAAW,OAAO;EAClB,eAAe,OAAO;EACtB,YAAY,OAAO;EACnB,OAAO,OAAO;EACd,OAAO,OAAO;EACd,UAAU,SAAS;EACnB,kBAAkB,4BAA4B,OAAO,MAAM;EAC3D,MAAM,OAAO;CACf,CAAC;CAEH,MAAM,uBAAuB,eAAe,QAAQ;CAMpD,MAAM,gBAAgB,qBACpB,eACA,UACA,OAAO,SACP,OAAO,OAAO,eAAe,MAC/B;CAEA,MAAM,eAAe,MAAM,MAAM,QAAQ,aAAa;EACpD,QAAQ,OAAO;EACf,QAAQ;EAIR,GAAI,uBAAuB,EAAE,cAAc,qBAAqB,IAAI,CAAC;EACrE,GAAI,cAAc,SAAS,IAAI,EAAE,SAAS,cAAc,IAAI,CAAC;CAC/D,CAAC;CAED,MAAM,aAAa,YAAY,IAAI,IAAI;CAEvC,IAAI,aAAa,OACf,MAAM,aAAa,iBAAiB,UAChC,aAAa,QACb,IAAI,sBAAsB,uBAAuB,EAC/C,OAAO,aAAa,MACtB,CAAC;CAGP,MAAM,OAAO,aAAa;CAE1B,IAAI,CAAC,QAAQ,OAAO,SAAS,UAC3B,MAAM,IAAI,uBACR,sGACA;EAAE,UAAU;EAAM,eAAe,CAAC,GAAG,OAAO,QAAQ,KAAK,CAAC;CAAE,CAC9D;CAGF,MAAM,UAAW,KAA4B;CAC7C,MAAM,YAAa,KAAiC;CAEpD,IAAI,YAAY,QACd,MAAM,IAAI,uBAAuB,8CAA8C;EAC7E,UAAU;EACV,eAAe,CAAC,GAAG,OAAO,QAAQ,KAAK,CAAC;CAC1C,CAAC;CAKH,OAAO;EACL,GAHe,UAAU,SAAiB,OAAO,SAAS,UAAU,UAG1D;EACV,WAAW,OAAO,cAAc,WAAW,YAAY;EACvD,OAAO,aAAa;EACpB,cAAc,aAAa;CAC7B;AACF;;;;;;;AAQA,SAAS,mBAAmB,QAK1B;CACA,IAAI,OAAQ,OAAiC,YAAY,YACvD,OAAO,EAAE,OAAO,OAAiC;CAGnD,MAAM,QAAQ;CAEd,OAAO;EACL,OAAO,MAAM;EACb,cAAc,MAAM;EACpB,eAAe,MAAM;EACrB,eAAe,MAAM;CACvB;AACF;;;;;;;;;;AAWA,SAAS,4BAA4B,QAAuD;CAC1F,IAAI,CAAC,OAAO,cACV;CAGF,OAAO,OAAO,OAAO,iBAAiB,WAClC,OAAO,eACP,OAAO,aAAa,QAAQ;AAClC;;;;;;AAOA,SAAS,UACP,KACA,SACA,QACA,YACkB;CAClB,IAAI,MAAM,GAAG,GACX,OAAO;EAAE,MAAM;EAAO;EAAQ;EAAK;CAAW;CAGhD,IAAI,OAAO,QAAQ,UAAU;EAC3B,YAAY,KAAK,OAAO;EAExB,OAAO;GACL,MAAM;GACN,SAAS,CAAC,GAAG;GACb;GACA;GACA;EACF;CACF;CAEA,IAAI,MAAM,QAAQ,GAAG,GAAG;EACtB,IAAI,IAAI,WAAW,GACjB,MAAM,IAAI,uBACR,8EACA;GAAE,UAAU;GAAK,eAAe,CAAC,GAAG,QAAQ,KAAK,CAAC;EAAE,CACtD;EAGF,KAAK,MAAM,UAAU,KAAK;GACxB,IAAI,OAAO,WAAW,UACpB,MAAM,IAAI,uBAAuB,yDAAyD;IACxF,UAAU;IACV,eAAe,CAAC,GAAG,QAAQ,KAAK,CAAC;GACnC,CAAC;GAGH,YAAY,QAAQ,OAAO;EAC7B;EAEA,OAAO;GACL,MAAM;GACN,SAAS;GACT;GACA;GACA;EACF;CACF;CAEA,MAAM,IAAI,uBACR,8EACA;EAAE,UAAU;EAAK,eAAe,CAAC,GAAG,QAAQ,KAAK,CAAC;CAAE,CACtD;AACF;AAEA,SAAS,YAAY,QAAgB,SAAiD;CACpF,IAAI,CAAC,QAAQ,IAAI,MAAM,GACrB,MAAM,IAAI,uBAAuB,sCAAsC,OAAO,IAAI;EAChF,UAAU;EACV,eAAe,CAAC,GAAG,QAAQ,KAAK,CAAC;CACnC,CAAC;AAEL;AAEA,SAAS,MAAM,OAAsC;CACnD,OAAO,UAAU;AACnB;;;;;;;;AASA,SAAS,qBACP,QACA,UACA,MACA,QACW;CACX,IAAI,QAAQ;EACV,MAAM,SAAS,OAAO,QAAQ;EAC9B,OAAO,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC;CACjC;CAEA,IAAI,WAAW,UAAa,SAAS,GACnC,OAAO,CAAC,GAAG,IAAI;CAGjB,IAAI,WAAW,GACb,OAAO,CAAC;CAGV,OAAO,KAAK,MAAM,CAAC,MAAM;AAC3B;;;;;;;;;;;;;;;;AAiBA,MAAM,4BAA4B;CAChC,MAAM;CACN,YAAY;EACV,MAAM;GACJ,MAAM;GACN,aAAa;EACf;EACA,WAAW;GACT,MAAM;GACN,aAAa;EACf;CACF;CACA,UAAU,CAAC,QAAQ,WAAW;CAC9B,sBAAsB;AACxB;;;;;;;;;;;;AAaA,MAAM,uBAGD,EACH,aAAa;CACX,SAAS;CACT,QAAQ;CACR,YAAY,EACV,aAAa,0BACf;CACA,SAAS,OAA6E;EACpF,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,kCAAkC,CAAC,EAAE;EAGpE,MAAM,SAAS;EACf,MAAM,UAAU,OAAO;EAMvB,IAAI,EAHF,OAAO,YAAY,YAClB,MAAM,QAAQ,OAAO,KAAK,QAAQ,OAAO,YAAY,OAAO,YAAY,QAAQ,IAGjF,OAAO,EACL,QAAQ,CACN,EACE,SAAS,uEACX,CACF,EACF;EAKF,OAAO,EACL,OAAO;GAAE,MAAM;GAAiB,WAHhB,OAAO,OAAO,cAAc,WAAW,OAAO,YAAY;EAGhC,EAC5C;CACF;AACF,EAGF;AAEA,SAAS,eAAe,gBAAwB,QAA0B;CACxE,IAAI,kBAAkB,SACpB,OAAO;CAKT,OAAO,IAAI,sBACT,2CAA2C,eAAe,KAH5C,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM,KAItE,EAAE,OAAO,OAAO,CAClB;AACF"}

package/esm/ai/src/supervisor/emitter.mjs

@@ -1,47 +0,0 @@
-//#region ../@warlock.js/ai/src/supervisor/emitter.ts
-/**
-* Three-tier supervisor event emitter — factory (definition) → instance
-* → per-execution. Mirrors `WorkflowEmitter` structurally; the only
-* difference is the event map. All matching handlers fire in layer
-* order. Handler errors are swallowed so a listener bug can never
-* derail the run.
-*
-* @example
-* const emitter = new SupervisorEmitter(definition.on);
-* const unsubscribe = emitter.on("supervisor.completed", (payload) => ...);
-* emitter.emit("supervisor.starting", { runId, rootRunId, supervisorName, input }, perCallHandlers);
-*/
-var SupervisorEmitter = class {
-	constructor(factoryHandlers) {
-		this.instanceHandlers = /* @__PURE__ */ new Map();
-		this.factoryHandlers = factoryHandlers;
-	}
-	on(event, handler) {
-		let bucket = this.instanceHandlers.get(event);
-		if (!bucket) {
-			bucket = /* @__PURE__ */ new Set();
-			this.instanceHandlers.set(event, bucket);
-		}
-		bucket.add(handler);
-		return () => this.off(event, handler);
-	}
-	off(event, handler) {
-		this.instanceHandlers.get(event)?.delete(handler);
-	}
-	emit(event, payload, executionHandlers) {
-		invoke(this.factoryHandlers?.[event], payload);
-		const bucket = this.instanceHandlers.get(event);
-		if (bucket) for (const handler of bucket) invoke(handler, payload);
-		invoke(executionHandlers?.[event], payload);
-	}
-};
-function invoke(handler, payload) {
-	if (typeof handler !== "function") return;
-	try {
-		handler(payload);
-	} catch {}
-}
-
-//#endregion
-export { SupervisorEmitter };
-//# sourceMappingURL=emitter.mjs.map

package/esm/ai/src/supervisor/emitter.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"emitter.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/supervisor/emitter.ts"],"sourcesContent":["import type { SupervisorEventMap } from \"../contracts/events/event-map.type\";\nimport type {\n  SupervisorEventHandler,\n  SupervisorEventHandlers,\n} from \"../contracts/supervisor/supervisor-config.type\";\n\ntype AnyHandler = SupervisorEventHandler<keyof SupervisorEventMap>;\n\n/**\n * Three-tier supervisor event emitter — factory (definition) → instance\n * → per-execution. Mirrors `WorkflowEmitter` structurally; the only\n * difference is the event map. All matching handlers fire in layer\n * order. Handler errors are swallowed so a listener bug can never\n * derail the run.\n *\n * @example\n * const emitter = new SupervisorEmitter(definition.on);\n * const unsubscribe = emitter.on(\"supervisor.completed\", (payload) => ...);\n * emitter.emit(\"supervisor.starting\", { runId, rootRunId, supervisorName, input }, perCallHandlers);\n */\nexport class SupervisorEmitter {\n  private readonly factoryHandlers?: SupervisorEventHandlers;\n  private readonly instanceHandlers = new Map<\n    keyof SupervisorEventMap,\n    Set<AnyHandler>\n  >();\n\n  public constructor(factoryHandlers?: SupervisorEventHandlers) {\n    this.factoryHandlers = factoryHandlers;\n  }\n\n  public on<K extends keyof SupervisorEventMap>(\n    event: K,\n    handler: SupervisorEventHandler<K>,\n  ): () => void {\n    let bucket = this.instanceHandlers.get(event);\n\n    if (!bucket) {\n      bucket = new Set();\n      this.instanceHandlers.set(event, bucket);\n    }\n\n    bucket.add(handler as AnyHandler);\n\n    return () => this.off(event, handler);\n  }\n\n  public off<K extends keyof SupervisorEventMap>(\n    event: K,\n    handler: SupervisorEventHandler<K>,\n  ): void {\n    this.instanceHandlers.get(event)?.delete(handler as AnyHandler);\n  }\n\n  public emit<K extends keyof SupervisorEventMap>(\n    event: K,\n    payload: SupervisorEventMap[K],\n    executionHandlers?: SupervisorEventHandlers,\n  ): void {\n    invoke(this.factoryHandlers?.[event], payload);\n\n    const bucket = this.instanceHandlers.get(event);\n\n    if (bucket) {\n      for (const handler of bucket) {\n        invoke(handler, payload);\n      }\n    }\n\n    invoke(executionHandlers?.[event], payload);\n  }\n}\n\nfunction invoke<K extends keyof SupervisorEventMap>(\n  handler: ((payload: SupervisorEventMap[K]) => void) | undefined,\n  payload: SupervisorEventMap[K],\n): void {\n  if (typeof handler !== \"function\") {\n    return;\n  }\n\n  try {\n    handler(payload);\n  } catch {\n    // Listener bugs must not derail the supervisor.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAoBA,IAAa,oBAAb,MAA+B;CAO7B,AAAO,YAAY,iBAA2C;0CAL1B,IAAI,IAGtC;EAGA,KAAK,kBAAkB;CACzB;CAEA,AAAO,GACL,OACA,SACY;EACZ,IAAI,SAAS,KAAK,iBAAiB,IAAI,KAAK;EAE5C,IAAI,CAAC,QAAQ;GACX,yBAAS,IAAI,IAAI;GACjB,KAAK,iBAAiB,IAAI,OAAO,MAAM;EACzC;EAEA,OAAO,IAAI,OAAqB;EAEhC,aAAa,KAAK,IAAI,OAAO,OAAO;CACtC;CAEA,AAAO,IACL,OACA,SACM;EACN,KAAK,iBAAiB,IAAI,KAAK,CAAC,EAAE,OAAO,OAAqB;CAChE;CAEA,AAAO,KACL,OACA,SACA,mBACM;EACN,OAAO,KAAK,kBAAkB,QAAQ,OAAO;EAE7C,MAAM,SAAS,KAAK,iBAAiB,IAAI,KAAK;EAE9C,IAAI,QACF,KAAK,MAAM,WAAW,QACpB,OAAO,SAAS,OAAO;EAI3B,OAAO,oBAAoB,QAAQ,OAAO;CAC5C;AACF;AAEA,SAAS,OACP,SACA,SACM;CACN,IAAI,OAAO,YAAY,YACrB;CAGF,IAAI;EACF,QAAQ,OAAO;CACjB,QAAQ,CAER;AACF"}