@warlock.js/ai 4.4.0 → 4.6.0

package/esm/speech/speech.mjs

@@ -0,0 +1,123 @@
+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 { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.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/speech/speech.mjs.map

@@ -0,0 +1 @@
+{"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/supervisor/as-tool.mjs

@@ -40,9 +40,9 @@ function asTool(supervisorInstance, options) {
 		name: options.name ?? supervisorInstance.name,
 		description: options.description ?? `Invoke supervisor "${supervisorInstance.name}" as a tool.`,
 		input: options.inputSchema,
-		execute: async (input) => {
+		execute: async (input, ctx) => {
 			const coerced = coerceInput(input);
-			const result = await supervisorInstance.execute(coerced);
+			const result = await supervisorInstance.execute(coerced, ctx?.signal ? { signal: ctx.signal } : void 0);
 			if (result.error) throw result.error;
 			return {
 				data: result.data,

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

@@ -1 +1 @@
-{"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) => {\n      const coerced = coerceInput(input);\n      const result = await supervisorInstance.execute(coerced);\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,UAAU;GACxB,MAAM,UAAU,YAAY,KAAK;GACjC,MAAM,SAAS,MAAM,mBAAmB,QAAQ,OAAO;GAEvD,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"}
+{"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/supervisor/entries.mjs

@@ -178,8 +178,8 @@ function isDispatchableUnit(value) {
 	return typeof candidate.name === "string" && typeof candidate.execute === "function";
 }
 function detectType(unit) {
-	if (typeof unit.signature === "string") return "workflow";
-	return "agent";
+	if (typeof unit.stream === "function") return "agent";
+	return "workflow";
 }
 function resolveAgentLikeDescription(intent, entryForm, unit, supervisorName) {
 	const entryOverride = entryForm?.description;

package/esm/supervisor/entries.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"entries.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/entries.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 type { EndSentinel } from \"../contracts/end.type\";\nimport type { AgentResult } from \"../contracts/result/agent-result.type\";\nimport type { WorkflowResult } from \"../contracts/result/workflow-result.type\";\nimport type { DispatchContext } from \"../contracts/supervisor/dispatch-context.type\";\nimport type {\n  DispatchRawResult,\n  IntentCallback,\n  IntentEntry,\n  IntentRunEntry,\n  SupervisorIntentValue,\n} from \"../contracts/supervisor/intent-entry.type\";\nimport type { RouteContext } from \"../contracts/supervisor/route-context.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { WorkflowInstance } from \"../contracts/workflow/workflow.contract\";\nimport { SupervisorFailedError } from \"../errors\";\n\n/**\n * Normalized internal representation of one entry in a supervisor's\n * `intents` map — resolved at factory time from one of the accepted\n * value forms (bare agent / workflow / callback / object entry).\n *\n * Carrying the explicit `type` discriminator keeps downstream code\n * (execution, signature, router-prompt) from having to re-detect\n * shape on every dispatch. The discriminated union below replaces\n * the flat-shape used in Phase 3 so callbacks can carry their own\n * function reference + dispatch-context-shaped resolvers.\n *\n * Discriminator renamed `kind` → `type` (Q12) for codebase-wide\n * consistency — every other discriminated result/report shape uses\n * `type`.\n */\nexport type ResolvedIntentEntry =\n  | ResolvedAgentEntry\n  | ResolvedWorkflowEntry\n  | ResolvedCallbackEntry;\n\n/**\n * Successor directive function type — the resolver-time projection of\n * `IntentEntry.next` / `IntentRunEntry.next`. Single source of truth\n * across the three resolved variants.\n */\nexport type IntentNext = (ctx: DispatchContext) => string | string[] | EndSentinel | undefined;\n\n/**\n * Resolver-time projection of `IntentEntry.history` /\n * `RouterEntry.history` / `AckEntry.history`. Custom slicer that\n * REPLACES the default `historyWindow.<role>` slice.\n */\nexport type EntryHistorySlicer = (ctx: RouteContext) => Message[] | ReadonlyArray<Message>;\n\nexport type ResolvedAgentEntry = {\n  intent: string;\n  type: \"agent\";\n  unit: AgentContract<unknown>;\n  description: string;\n  input?: (ctx: RouteContext) => string;\n  /**\n   * Per-dispatch placeholder values for the agent's systemPrompt\n   * template. Forwarded as `agent.execute(input, { placeholders })`.\n   * Phase 3.4 (Stage 4b) — replaces the dropped `composeAgentInput`\n   * mechanism for threading state into agents.\n   */\n  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;\n  /**\n   * Schema declaring this intent's slice of supervisor state. Agent\n   * output is strip-merged against it; only validated keys appear on\n   * `IterationSnapshot.result[intent].output` AND merge into\n   * supervisor `state`.\n   */\n  output?: StandardSchemaV1<unknown>;\n  /**\n   * Successor directive (Stage 4d / Q24). When present, runs after\n   * this branch's slice merges into state to choose the next dispatch\n   * (or terminate) without invoking the router.\n   */\n  next?: IntentNext;\n  /**\n   * Custom history slicer — replaces the default\n   * `historyWindow.agents` slice when supplied. See `IntentEntry.history`.\n   */\n  history?: EntryHistorySlicer;\n  /**\n   * Phase 5 / decisions §34. `\"stream\"` runs the agent without\n   * structured-output coercion and writes the assembled prose into\n   * `state[streamTo]`; `\"structured\"` is the default. Resolved at\n   * factory time — `undefined` here is treated as `\"structured\"`.\n   */\n  mode?: \"structured\" | \"stream\";\n  /** State key the assembled stream-mode prose writes into. Set iff `mode === \"stream\"`. */\n  streamTo?: string;\n};\n\nexport type ResolvedWorkflowEntry = {\n  intent: string;\n  type: \"workflow\";\n  unit: WorkflowInstance<unknown, unknown>;\n  description: string;\n  input?: (ctx: RouteContext) => string;\n  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;\n  output?: StandardSchemaV1<unknown>;\n  next?: IntentNext;\n  history?: EntryHistorySlicer;\n};\n\nexport type ResolvedCallbackEntry = {\n  intent: string;\n  type: \"callback\";\n  /**\n   * The callback that actually runs at dispatch time. Always present\n   * regardless of whether the user passed bare-function shorthand or\n   * the `{ run, ... }` entry form.\n   */\n  callback: IntentCallback;\n  /**\n   * Description is required only when the supervisor uses a router.\n   * Callback intents under a router are validated separately\n   * (see {@link assertRouterDescriptions}); under deterministic\n   * `route` mode this field is `undefined`.\n   */\n  description?: string;\n  /**\n   * Per-intent input resolver. Receives the upcoming\n   * `DispatchContext` and returns the value forwarded as\n   * `ctx.input` to the callback.\n   */\n  input?: (ctx: DispatchContext) => unknown;\n  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;\n  /**\n   * Schema declaring this callback's slice of state. Without it, the\n   * full return value shallow-merges; with it, return is strip-merged\n   * to declared keys before merging.\n   */\n  output?: StandardSchemaV1<unknown>;\n  next?: IntentNext;\n};\n\n/**\n * Validate and normalize the `intents` map into resolved entries.\n * Runs at factory time — throws `SupervisorFailedError` on the first\n * malformed entry so author-time bugs surface immediately rather\n * than mid-run.\n *\n * Validation rules:\n * - Every value must be an agent, a workflow, a callback function,\n *   or an object entry with `agent` / `workflow` / `run`.\n * - Object entries with more than one of `{ agent, workflow, run }`\n *   throw with code `SUPERVISOR_INTENT_MIXED_DISPATCH`.\n * - Agent / workflow / agent-shaped entries must resolve to a\n *   non-empty description from the underlying unit or the entry's\n *   `description` override. Bare callback shorthand has no\n *   description source — that's enforced separately by\n *   {@link assertRouterDescriptions} when a router is configured.\n */\nexport function resolveIntentEntries(\n  rawIntents: Record<string, SupervisorIntentValue>,\n  supervisorName: string,\n): Map<string, ResolvedIntentEntry> {\n  const entries = Object.entries(rawIntents);\n\n  if (entries.length === 0) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): \\`intents\\` must contain at least one entry`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const resolved = new Map<string, ResolvedIntentEntry>();\n\n  for (const [intent, value] of entries) {\n    if (!intent || typeof intent !== \"string\") {\n      throw new SupervisorFailedError(\n        `ai.supervisor(\"${supervisorName}\"): every \\`intents\\` key must be a non-empty string`,\n        { context: { authoring: true } },\n      );\n    }\n\n    resolved.set(intent, resolveOne(intent, value, supervisorName));\n  }\n\n  return resolved;\n}\n\n/**\n * Construction-time guard: when the supervisor is configured with a\n * `router`, every intent must resolve to a non-empty description so\n * the router LLM has a signal for picking it. Bare callback\n * shorthand and `IntentRunEntry` without `description` fail this\n * check; agents and workflows whose underlying primitive lacks a\n * description fail too — same uniform error message.\n *\n * Deterministic `route` callers skip this check entirely.\n */\nexport function assertRouterDescriptions(\n  config: SupervisorConfig<unknown>,\n  entries: Map<string, ResolvedIntentEntry>,\n): void {\n  if (!config.router) {\n    return;\n  }\n\n  for (const [intent, entry] of entries) {\n    const description = entry.type === \"callback\" ? entry.description : entry.description;\n\n    if (description && description.trim().length > 0) {\n      continue;\n    }\n\n    const fix =\n      entry.type === \"callback\"\n        ? \"upgrade the bare callback to `{ run, description }`\"\n        : \"set `description` on the agent/workflow or via the `IntentEntry` `description` override\";\n\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${config.name}\"): intents[\"${intent}\"] needs a description because a \\`router\\` is configured — ${fix}`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_DESCRIPTION_REQUIRED\",\n    );\n  }\n}\n\nfunction resolveOne(\n  intent: string,\n  value: SupervisorIntentValue,\n  supervisorName: string,\n): ResolvedIntentEntry {\n  // (c) Bare callback shorthand — typeof function. Highest priority\n  // so a user passing `(ctx) => …` never accidentally matches the\n  // object-shape branches below.\n  if (typeof value === \"function\") {\n    return {\n      intent,\n      type: \"callback\",\n      callback: value as IntentCallback,\n      description: undefined,\n    };\n  }\n\n  if (!value || typeof value !== \"object\") {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] is not an agent, workflow, callback, or entry object`,\n      { context: { authoring: true, intent } },\n    );\n  }\n\n  // Detect mixed-dispatch entries up front. Two of `{ agent, workflow,\n  // run }` together is dev confusion, not a feature.\n  assertSingleDispatchField(intent, value, supervisorName);\n\n  // (d.run) Run-entry — `{ run, description?, input?, output? }`.\n  if (\"run\" in value && typeof (value as IntentRunEntry).run === \"function\") {\n    const entry = value as IntentRunEntry;\n\n    return {\n      intent,\n      type: \"callback\",\n      callback: entry.run,\n      description: entry.description,\n      input: entry.input,\n      placeholders: entry.placeholders,\n      output: entry.output,\n      next: entry.next,\n    };\n  }\n\n  // (d.agent / a / b) Agent-entry or bare unit. The existing\n  // `IntentEntry` shape uses `agent: AgentContract | WorkflowInstance`\n  // for both agent and workflow object entries; the resolver still\n  // dispatches the underlying unit kind correctly.\n  const entryForm = asAgentEntryForm(value);\n  const unit = entryForm\n    ? entryForm.agent\n    : (value as AgentContract<unknown> | WorkflowInstance<unknown, unknown>);\n\n  if (!isDispatchableUnit(unit)) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] must be an AgentContract, WorkflowInstance, callback, or entry object`,\n      { context: { authoring: true, intent } },\n    );\n  }\n\n  const detectedType = detectType(unit);\n  const description = resolveAgentLikeDescription(intent, entryForm, unit, supervisorName);\n\n  if (detectedType === \"workflow\") {\n    if (entryForm?.mode === \"stream\") {\n      throw new SupervisorFailedError(\n        `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] sets \\`mode: \"stream\"\\` on a workflow entry — stream mode is agent-only in v1. Wrap the workflow in an agent or remove the \\`mode\\` field.`,\n        { context: { authoring: true, intent } },\n        \"SUPERVISOR_INTENT_STREAM_ON_WORKFLOW\",\n      );\n    }\n\n    return {\n      intent,\n      type: \"workflow\",\n      unit: unit as WorkflowInstance<unknown, unknown>,\n      description,\n      input: entryForm?.input,\n      placeholders: entryForm?.placeholders,\n      output: entryForm?.output,\n      next: entryForm?.next,\n      history: entryForm?.history,\n    };\n  }\n\n  assertStreamModeShape(intent, entryForm, supervisorName);\n\n  return {\n    intent,\n    type: \"agent\",\n    unit: unit as AgentContract<unknown>,\n    description,\n    input: entryForm?.input,\n    placeholders: entryForm?.placeholders,\n    output: entryForm?.output,\n    next: entryForm?.next,\n    history: entryForm?.history,\n    mode: entryForm?.mode,\n    streamTo: entryForm?.streamTo,\n  };\n}\n\n/**\n * Phase 5 / decisions §34 — enforce the two stream-mode invariants at\n * construction time:\n *\n * 1. `mode: \"stream\"` and per-intent `output` are mutually exclusive.\n *    Stream agents declare their state contribution via `streamTo`,\n *    not via a schema; allowing both would silently pick one and\n *    surprise the author.\n * 2. `streamTo` is required when `mode === \"stream\"`. A stream agent\n *    that doesn't write somewhere is a black box — fail loud at the\n *    factory rather than at run-time when state validation surfaces a\n *    missing key.\n */\nfunction assertStreamModeShape(\n  intent: string,\n  entryForm: IntentEntry | undefined,\n  supervisorName: string,\n): void {\n  if (!entryForm || entryForm.mode !== \"stream\") {\n    return;\n  }\n\n  if (entryForm.output) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] sets both \\`mode: \"stream\"\\` and \\`output\\` — stream mode declares its slice via \\`streamTo\\`, not a schema. Drop one.`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_STREAM_AND_OUTPUT\",\n    );\n  }\n\n  if (typeof entryForm.streamTo !== \"string\" || entryForm.streamTo.trim().length === 0) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] sets \\`mode: \"stream\"\\` without a non-empty \\`streamTo\\` — a stream agent must name the state key its assembled prose writes into.`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_STREAM_TO_REQUIRED\",\n    );\n  }\n}\n\n/**\n * Reject entries that mix dispatch fields. `{ agent, run }` is a\n * common copy-paste bug; we surface it at construction with a clear\n * message rather than silently picking one based on resolution\n * order.\n */\nfunction assertSingleDispatchField(intent: string, value: object, supervisorName: string): void {\n  const dispatchKeys = ([\"run\", \"agent\", \"workflow\"] as const).filter((key) => key in value);\n\n  if (dispatchKeys.length > 1) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] has multiple dispatch fields (${dispatchKeys\n        .map((key) => `\\`${key}\\``)\n        .join(\n          \", \",\n        )}) — pick one. Two dispatch fields on the same entry is dev confusion, not a feature.`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_MIXED_DISPATCH\",\n    );\n  }\n}\n\n/**\n * Coerce a `SupervisorIntentValue` into the agent-flavored\n * `IntentEntry` form when the caller passed the object form. Returns\n * `undefined` for bare shorthand. The shape check keys on the\n * presence of an `agent` property because both `AgentContract` and\n * `WorkflowInstance` have their own identifying fields\n * (`isAnonymous` for agents, `signature` for workflows) but neither\n * carries a top-level `agent`.\n */\nfunction asAgentEntryForm(value: object): IntentEntry | undefined {\n  if (!(\"agent\" in value)) {\n    return undefined;\n  }\n\n  const candidate = (value as { agent: unknown }).agent;\n\n  if (!candidate || typeof candidate !== \"object\") {\n    return undefined;\n  }\n\n  return value as IntentEntry;\n}\n\nfunction isDispatchableUnit(\n  value: unknown,\n): value is AgentContract<unknown> | WorkflowInstance<unknown, unknown> {\n  if (!value || typeof value !== \"object\") {\n    return false;\n  }\n\n  const candidate = value as { name?: unknown; execute?: unknown };\n\n  return typeof candidate.name === \"string\" && typeof candidate.execute === \"function\";\n}\n\nfunction detectType(\n  unit: AgentContract<unknown> | WorkflowInstance<unknown, unknown>,\n): \"agent\" | \"workflow\" {\n  // Workflows expose a structural `signature` field; agents don't.\n  if (typeof (unit as WorkflowInstance<unknown, unknown>).signature === \"string\") {\n    return \"workflow\";\n  }\n\n  return \"agent\";\n}\n\nfunction resolveAgentLikeDescription(\n  intent: string,\n  entryForm: IntentEntry | undefined,\n  unit: AgentContract<unknown> | WorkflowInstance<unknown, unknown>,\n  supervisorName: string,\n): string {\n  const entryOverride = entryForm?.description;\n\n  if (entryOverride && entryOverride.trim().length > 0) {\n    return entryOverride;\n  }\n\n  const unitDescription = (unit as { description?: unknown }).description;\n\n  if (typeof unitDescription === \"string\" && unitDescription.trim().length > 0) {\n    return unitDescription;\n  }\n\n  // Empty string sentinel — caller (assertRouterDescriptions) decides\n  // whether a missing description is fatal. Under deterministic\n  // `route` mode it isn't.\n  return \"\";\n}\n\n/**\n * Type guard helper for downstream modules. Narrows a raw\n * `AgentResult | WorkflowResult` based on the resolved entry's kind,\n * so transformers and emitters can pull the right fields without\n * re-checking shape.\n */\nexport function isAgentResult(raw: DispatchRawResult): raw is AgentResult<unknown> {\n  return raw.type === \"agent\";\n}\n\nexport function isWorkflowResult(raw: DispatchRawResult): raw is WorkflowResult<unknown> {\n  return raw.type === \"workflow\";\n}\n"],"mappings":"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"}
+{"version":3,"file":"entries.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/entries.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 type { EndSentinel } from \"../contracts/end.type\";\nimport type { AgentResult } from \"../contracts/result/agent-result.type\";\nimport type { WorkflowResult } from \"../contracts/result/workflow-result.type\";\nimport type { DispatchContext } from \"../contracts/supervisor/dispatch-context.type\";\nimport type {\n  DispatchRawResult,\n  IntentCallback,\n  IntentEntry,\n  IntentRunEntry,\n  SupervisorIntentValue,\n} from \"../contracts/supervisor/intent-entry.type\";\nimport type { RouteContext } from \"../contracts/supervisor/route-context.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { WorkflowInstance } from \"../contracts/workflow/workflow.contract\";\nimport { SupervisorFailedError } from \"../errors\";\n\n/**\n * Normalized internal representation of one entry in a supervisor's\n * `intents` map — resolved at factory time from one of the accepted\n * value forms (bare agent / workflow / callback / object entry).\n *\n * Carrying the explicit `type` discriminator keeps downstream code\n * (execution, signature, router-prompt) from having to re-detect\n * shape on every dispatch. The discriminated union below replaces\n * the flat-shape used in Phase 3 so callbacks can carry their own\n * function reference + dispatch-context-shaped resolvers.\n *\n * Discriminator renamed `kind` → `type` (Q12) for codebase-wide\n * consistency — every other discriminated result/report shape uses\n * `type`.\n */\nexport type ResolvedIntentEntry =\n  | ResolvedAgentEntry\n  | ResolvedWorkflowEntry\n  | ResolvedCallbackEntry;\n\n/**\n * Successor directive function type — the resolver-time projection of\n * `IntentEntry.next` / `IntentRunEntry.next`. Single source of truth\n * across the three resolved variants.\n */\nexport type IntentNext = (ctx: DispatchContext) => string | string[] | EndSentinel | undefined;\n\n/**\n * Resolver-time projection of `IntentEntry.history` /\n * `RouterEntry.history` / `AckEntry.history`. Custom slicer that\n * REPLACES the default `historyWindow.<role>` slice.\n */\nexport type EntryHistorySlicer = (ctx: RouteContext) => Message[] | ReadonlyArray<Message>;\n\nexport type ResolvedAgentEntry = {\n  intent: string;\n  type: \"agent\";\n  unit: AgentContract<unknown>;\n  description: string;\n  input?: (ctx: RouteContext) => string;\n  /**\n   * Per-dispatch placeholder values for the agent's systemPrompt\n   * template. Forwarded as `agent.execute(input, { placeholders })`.\n   * Phase 3.4 (Stage 4b) — replaces the dropped `composeAgentInput`\n   * mechanism for threading state into agents.\n   */\n  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;\n  /**\n   * Schema declaring this intent's slice of supervisor state. Agent\n   * output is strip-merged against it; only validated keys appear on\n   * `IterationSnapshot.result[intent].output` AND merge into\n   * supervisor `state`.\n   */\n  output?: StandardSchemaV1<unknown>;\n  /**\n   * Successor directive (Stage 4d / Q24). When present, runs after\n   * this branch's slice merges into state to choose the next dispatch\n   * (or terminate) without invoking the router.\n   */\n  next?: IntentNext;\n  /**\n   * Custom history slicer — replaces the default\n   * `historyWindow.agents` slice when supplied. See `IntentEntry.history`.\n   */\n  history?: EntryHistorySlicer;\n  /**\n   * Phase 5 / decisions §34. `\"stream\"` runs the agent without\n   * structured-output coercion and writes the assembled prose into\n   * `state[streamTo]`; `\"structured\"` is the default. Resolved at\n   * factory time — `undefined` here is treated as `\"structured\"`.\n   */\n  mode?: \"structured\" | \"stream\";\n  /** State key the assembled stream-mode prose writes into. Set iff `mode === \"stream\"`. */\n  streamTo?: string;\n};\n\nexport type ResolvedWorkflowEntry = {\n  intent: string;\n  type: \"workflow\";\n  unit: WorkflowInstance<unknown, unknown>;\n  description: string;\n  input?: (ctx: RouteContext) => string;\n  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;\n  output?: StandardSchemaV1<unknown>;\n  next?: IntentNext;\n  history?: EntryHistorySlicer;\n};\n\nexport type ResolvedCallbackEntry = {\n  intent: string;\n  type: \"callback\";\n  /**\n   * The callback that actually runs at dispatch time. Always present\n   * regardless of whether the user passed bare-function shorthand or\n   * the `{ run, ... }` entry form.\n   */\n  callback: IntentCallback;\n  /**\n   * Description is required only when the supervisor uses a router.\n   * Callback intents under a router are validated separately\n   * (see {@link assertRouterDescriptions}); under deterministic\n   * `route` mode this field is `undefined`.\n   */\n  description?: string;\n  /**\n   * Per-intent input resolver. Receives the upcoming\n   * `DispatchContext` and returns the value forwarded as\n   * `ctx.input` to the callback.\n   */\n  input?: (ctx: DispatchContext) => unknown;\n  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;\n  /**\n   * Schema declaring this callback's slice of state. Without it, the\n   * full return value shallow-merges; with it, return is strip-merged\n   * to declared keys before merging.\n   */\n  output?: StandardSchemaV1<unknown>;\n  next?: IntentNext;\n};\n\n/**\n * Validate and normalize the `intents` map into resolved entries.\n * Runs at factory time — throws `SupervisorFailedError` on the first\n * malformed entry so author-time bugs surface immediately rather\n * than mid-run.\n *\n * Validation rules:\n * - Every value must be an agent, a workflow, a callback function,\n *   or an object entry with `agent` / `workflow` / `run`.\n * - Object entries with more than one of `{ agent, workflow, run }`\n *   throw with code `SUPERVISOR_INTENT_MIXED_DISPATCH`.\n * - Agent / workflow / agent-shaped entries must resolve to a\n *   non-empty description from the underlying unit or the entry's\n *   `description` override. Bare callback shorthand has no\n *   description source — that's enforced separately by\n *   {@link assertRouterDescriptions} when a router is configured.\n */\nexport function resolveIntentEntries(\n  rawIntents: Record<string, SupervisorIntentValue>,\n  supervisorName: string,\n): Map<string, ResolvedIntentEntry> {\n  const entries = Object.entries(rawIntents);\n\n  if (entries.length === 0) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): \\`intents\\` must contain at least one entry`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const resolved = new Map<string, ResolvedIntentEntry>();\n\n  for (const [intent, value] of entries) {\n    if (!intent || typeof intent !== \"string\") {\n      throw new SupervisorFailedError(\n        `ai.supervisor(\"${supervisorName}\"): every \\`intents\\` key must be a non-empty string`,\n        { context: { authoring: true } },\n      );\n    }\n\n    resolved.set(intent, resolveOne(intent, value, supervisorName));\n  }\n\n  return resolved;\n}\n\n/**\n * Construction-time guard: when the supervisor is configured with a\n * `router`, every intent must resolve to a non-empty description so\n * the router LLM has a signal for picking it. Bare callback\n * shorthand and `IntentRunEntry` without `description` fail this\n * check; agents and workflows whose underlying primitive lacks a\n * description fail too — same uniform error message.\n *\n * Deterministic `route` callers skip this check entirely.\n */\nexport function assertRouterDescriptions(\n  config: SupervisorConfig<unknown>,\n  entries: Map<string, ResolvedIntentEntry>,\n): void {\n  if (!config.router) {\n    return;\n  }\n\n  for (const [intent, entry] of entries) {\n    const description = entry.type === \"callback\" ? entry.description : entry.description;\n\n    if (description && description.trim().length > 0) {\n      continue;\n    }\n\n    const fix =\n      entry.type === \"callback\"\n        ? \"upgrade the bare callback to `{ run, description }`\"\n        : \"set `description` on the agent/workflow or via the `IntentEntry` `description` override\";\n\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${config.name}\"): intents[\"${intent}\"] needs a description because a \\`router\\` is configured — ${fix}`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_DESCRIPTION_REQUIRED\",\n    );\n  }\n}\n\nfunction resolveOne(\n  intent: string,\n  value: SupervisorIntentValue,\n  supervisorName: string,\n): ResolvedIntentEntry {\n  // (c) Bare callback shorthand — typeof function. Highest priority\n  // so a user passing `(ctx) => …` never accidentally matches the\n  // object-shape branches below.\n  if (typeof value === \"function\") {\n    return {\n      intent,\n      type: \"callback\",\n      callback: value as IntentCallback,\n      description: undefined,\n    };\n  }\n\n  if (!value || typeof value !== \"object\") {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] is not an agent, workflow, callback, or entry object`,\n      { context: { authoring: true, intent } },\n    );\n  }\n\n  // Detect mixed-dispatch entries up front. Two of `{ agent, workflow,\n  // run }` together is dev confusion, not a feature.\n  assertSingleDispatchField(intent, value, supervisorName);\n\n  // (d.run) Run-entry — `{ run, description?, input?, output? }`.\n  if (\"run\" in value && typeof (value as IntentRunEntry).run === \"function\") {\n    const entry = value as IntentRunEntry;\n\n    return {\n      intent,\n      type: \"callback\",\n      callback: entry.run,\n      description: entry.description,\n      input: entry.input,\n      placeholders: entry.placeholders,\n      output: entry.output,\n      next: entry.next,\n    };\n  }\n\n  // (d.agent / a / b) Agent-entry or bare unit. The existing\n  // `IntentEntry` shape uses `agent: AgentContract | WorkflowInstance`\n  // for both agent and workflow object entries; the resolver still\n  // dispatches the underlying unit kind correctly.\n  const entryForm = asAgentEntryForm(value);\n  const unit = entryForm\n    ? entryForm.agent\n    : (value as AgentContract<unknown> | WorkflowInstance<unknown, unknown>);\n\n  if (!isDispatchableUnit(unit)) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] must be an AgentContract, WorkflowInstance, callback, or entry object`,\n      { context: { authoring: true, intent } },\n    );\n  }\n\n  const detectedType = detectType(unit);\n  const description = resolveAgentLikeDescription(intent, entryForm, unit, supervisorName);\n\n  if (detectedType === \"workflow\") {\n    if (entryForm?.mode === \"stream\") {\n      throw new SupervisorFailedError(\n        `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] sets \\`mode: \"stream\"\\` on a workflow entry — stream mode is agent-only in v1. Wrap the workflow in an agent or remove the \\`mode\\` field.`,\n        { context: { authoring: true, intent } },\n        \"SUPERVISOR_INTENT_STREAM_ON_WORKFLOW\",\n      );\n    }\n\n    return {\n      intent,\n      type: \"workflow\",\n      unit: unit as WorkflowInstance<unknown, unknown>,\n      description,\n      input: entryForm?.input,\n      placeholders: entryForm?.placeholders,\n      output: entryForm?.output,\n      next: entryForm?.next,\n      history: entryForm?.history,\n    };\n  }\n\n  assertStreamModeShape(intent, entryForm, supervisorName);\n\n  return {\n    intent,\n    type: \"agent\",\n    unit: unit as AgentContract<unknown>,\n    description,\n    input: entryForm?.input,\n    placeholders: entryForm?.placeholders,\n    output: entryForm?.output,\n    next: entryForm?.next,\n    history: entryForm?.history,\n    mode: entryForm?.mode,\n    streamTo: entryForm?.streamTo,\n  };\n}\n\n/**\n * Phase 5 / decisions §34 — enforce the two stream-mode invariants at\n * construction time:\n *\n * 1. `mode: \"stream\"` and per-intent `output` are mutually exclusive.\n *    Stream agents declare their state contribution via `streamTo`,\n *    not via a schema; allowing both would silently pick one and\n *    surprise the author.\n * 2. `streamTo` is required when `mode === \"stream\"`. A stream agent\n *    that doesn't write somewhere is a black box — fail loud at the\n *    factory rather than at run-time when state validation surfaces a\n *    missing key.\n */\nfunction assertStreamModeShape(\n  intent: string,\n  entryForm: IntentEntry | undefined,\n  supervisorName: string,\n): void {\n  if (!entryForm || entryForm.mode !== \"stream\") {\n    return;\n  }\n\n  if (entryForm.output) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] sets both \\`mode: \"stream\"\\` and \\`output\\` — stream mode declares its slice via \\`streamTo\\`, not a schema. Drop one.`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_STREAM_AND_OUTPUT\",\n    );\n  }\n\n  if (typeof entryForm.streamTo !== \"string\" || entryForm.streamTo.trim().length === 0) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] sets \\`mode: \"stream\"\\` without a non-empty \\`streamTo\\` — a stream agent must name the state key its assembled prose writes into.`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_STREAM_TO_REQUIRED\",\n    );\n  }\n}\n\n/**\n * Reject entries that mix dispatch fields. `{ agent, run }` is a\n * common copy-paste bug; we surface it at construction with a clear\n * message rather than silently picking one based on resolution\n * order.\n */\nfunction assertSingleDispatchField(intent: string, value: object, supervisorName: string): void {\n  const dispatchKeys = ([\"run\", \"agent\", \"workflow\"] as const).filter((key) => key in value);\n\n  if (dispatchKeys.length > 1) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${supervisorName}\"): intents[\"${intent}\"] has multiple dispatch fields (${dispatchKeys\n        .map((key) => `\\`${key}\\``)\n        .join(\n          \", \",\n        )}) — pick one. Two dispatch fields on the same entry is dev confusion, not a feature.`,\n      { context: { authoring: true, intent } },\n      \"SUPERVISOR_INTENT_MIXED_DISPATCH\",\n    );\n  }\n}\n\n/**\n * Coerce a `SupervisorIntentValue` into the agent-flavored\n * `IntentEntry` form when the caller passed the object form. Returns\n * `undefined` for bare shorthand. The shape check keys on the\n * presence of an `agent` property because both `AgentContract` and\n * `WorkflowInstance` have their own identifying fields\n * (`isAnonymous` for agents, `signature` for workflows) but neither\n * carries a top-level `agent`.\n */\nfunction asAgentEntryForm(value: object): IntentEntry | undefined {\n  if (!(\"agent\" in value)) {\n    return undefined;\n  }\n\n  const candidate = (value as { agent: unknown }).agent;\n\n  if (!candidate || typeof candidate !== \"object\") {\n    return undefined;\n  }\n\n  return value as IntentEntry;\n}\n\nfunction isDispatchableUnit(\n  value: unknown,\n): value is AgentContract<unknown> | WorkflowInstance<unknown, unknown> {\n  if (!value || typeof value !== \"object\") {\n    return false;\n  }\n\n  const candidate = value as { name?: unknown; execute?: unknown };\n\n  return typeof candidate.name === \"string\" && typeof candidate.execute === \"function\";\n}\n\nfunction detectType(\n  unit: AgentContract<unknown> | WorkflowInstance<unknown, unknown>,\n): \"agent\" | \"workflow\" {\n  // Both agents and workflows now expose a structural `signature` (the\n  // drift fingerprint durable resume added to the agent), so `signature`\n  // no longer distinguishes them. Agents expose a token-`stream()` method;\n  // workflows do not (workflow streaming is step-level, not a `.stream`\n  // API) — use that as the positive agent marker.\n  if (typeof (unit as AgentContract<unknown>).stream === \"function\") {\n    return \"agent\";\n  }\n\n  return \"workflow\";\n}\n\nfunction resolveAgentLikeDescription(\n  intent: string,\n  entryForm: IntentEntry | undefined,\n  unit: AgentContract<unknown> | WorkflowInstance<unknown, unknown>,\n  supervisorName: string,\n): string {\n  const entryOverride = entryForm?.description;\n\n  if (entryOverride && entryOverride.trim().length > 0) {\n    return entryOverride;\n  }\n\n  const unitDescription = (unit as { description?: unknown }).description;\n\n  if (typeof unitDescription === \"string\" && unitDescription.trim().length > 0) {\n    return unitDescription;\n  }\n\n  // Empty string sentinel — caller (assertRouterDescriptions) decides\n  // whether a missing description is fatal. Under deterministic\n  // `route` mode it isn't.\n  return \"\";\n}\n\n/**\n * Type guard helper for downstream modules. Narrows a raw\n * `AgentResult | WorkflowResult` based on the resolved entry's kind,\n * so transformers and emitters can pull the right fields without\n * re-checking shape.\n */\nexport function isAgentResult(raw: DispatchRawResult): raw is AgentResult<unknown> {\n  return raw.type === \"agent\";\n}\n\nexport function isWorkflowResult(raw: DispatchRawResult): raw is WorkflowResult<unknown> {\n  return raw.type === \"workflow\";\n}\n"],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"execution.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/execution.ts"],"mappings":"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"}
+{"version":3,"file":"execution.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/execution.ts"],"mappings":"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"}

package/esm/supervisor/execution.mjs

@@ -4,6 +4,8 @@ import { MaxIterationsError } from "../errors/max-iterations-error.mjs";
 import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
 import { SupervisorCancelledError } from "../errors/supervisor-cancelled-error.mjs";
 import "../errors/index.mjs";
+import { mergeUsage } from "../utils/compute-cost.mjs";
+import { withRunFrame, withoutRunFrame } from "../utils/run-context.mjs";
 import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
 import "../utils/index.mjs";
 import { runPipeline } from "../middleware/pipeline.mjs";
@@ -472,7 +474,7 @@ var SupervisorExecution = class {
 			total: 0
 		};
 		try {
-			rawResult = await this.invokeUnit(entry, resolvedInput, placeholders, routeContext);
+			rawResult = await withoutRunFrame(() => this.invokeUnit(entry, resolvedInput, placeholders, routeContext));
 			if (rawResult.error) branchError = rawResult.error;
 			branchUsage = rawResult.usage;
 			if (rawResult.report) this.childReports.push(rawResult.report);
@@ -572,12 +574,18 @@ var SupervisorExecution = class {
 	async runCallback(entry, input, callStack, reportSink) {
 		const childReports = [];
 		const dispatchCtx = this.seedDispatchContext(entry.intent, input, callStack, childReports);
+		const callbackRunId = `${this.runId}.${entry.intent}`;
 		const startedAt = /* @__PURE__ */ new Date();
 		const startPerf = performance.now();
 		let rawOutput;
 		let error;
 		try {
-			rawOutput = await entry.callback(dispatchCtx);
+			rawOutput = await withRunFrame({
+				sink: childReports,
+				rootRunId: this.runId,
+				parentRunId: callbackRunId,
+				sessionId: this.options?.sessionId
+			}, () => Promise.resolve(entry.callback(dispatchCtx)));
 		} catch (thrown) {
 			error = thrown instanceof AIError ? thrown : new SupervisorFailedError(`callback intent "${entry.intent}" threw: ${thrown instanceof Error ? thrown.message : String(thrown)}`, { cause: thrown });
 		}
@@ -593,7 +601,7 @@ var SupervisorExecution = class {
 		const duration = performance.now() - startPerf;
 		const rolledUsage = aggregateChildUsage(childReports);
 		const report = {
-			runId: `${this.runId}.${entry.intent}`,
+			runId: callbackRunId,
 			rootRunId: this.runId,
 			name: entry.intent,
 			type: "callback",
@@ -669,15 +677,15 @@ var SupervisorExecution = class {
 			const inputString = typeof callerInput === "string" ? callerInput : safeStringify(callerInput);
 			if (entry.type === "agent") {
 				const reentryHistory = this.applyAgentsWindow();
-				const result = await entry.unit.execute(inputString, {
+				const result = await withoutRunFrame(() => entry.unit.execute(inputString, {
 					signal: this.options?.signal,
 					...reentryHistory.length > 0 ? { history: reentryHistory } : {}
-				});
+				}));
 				if (result.report) reportSink.push(result.report);
 				if (result.error) throw result.error;
 				return result.data ?? result.text ?? void 0;
 			}
-			const result = await entry.unit.execute(inputString, { signal: this.options?.signal });
+			const result = await withoutRunFrame(() => entry.unit.execute(inputString, { signal: this.options?.signal }));
 			if (result.report) reportSink.push(result.report);
 			if (result.error) throw result.error;
 			return result.data;
@@ -722,7 +730,7 @@ var SupervisorExecution = class {
 		try {
 			const merged = this.mergeInlineOptions(options);
 			const inputForExecutable = this.coerceInlineInput(executable, input);
-			const result = await executable.execute(inputForExecutable, merged);
+			const result = await withoutRunFrame(() => executable.execute(inputForExecutable, merged));
 			if (result.report) reportSink.push(result.report);
 			return result;
 		} finally {
@@ -759,7 +767,7 @@ var SupervisorExecution = class {
 	*/
 	streamSupervisedExecutable(executable, input, options, callerIntent, reportSink, release) {
 		const merged = this.mergeInlineOptions(options);
-		const stream = executable.stream(input, merged);
+		const stream = withoutRunFrame(() => executable.stream(input, merged));
 		stream.on({
 			"agent.trip.streaming": ({ delta }) => {
 				this.emit("supervisor.agent.streaming", {
@@ -1181,7 +1189,7 @@ var SupervisorExecution = class {
 				usage,
 				error
 			};
-			this.aggregateUsage(this.usage, usage);
+			mergeUsage(this.usage, usage);
 			this.emit("supervisor.classifier.failed", { error });
 			throw error;
 		}
@@ -1201,7 +1209,7 @@ var SupervisorExecution = class {
 				usage,
 				error
 			};
-			this.aggregateUsage(this.usage, usage);
+			mergeUsage(this.usage, usage);
 			this.emit("supervisor.classifier.failed", { error });
 			throw error;
 		}
@@ -1226,7 +1234,7 @@ var SupervisorExecution = class {
 					usage,
 					error
 				};
-				this.aggregateUsage(this.usage, usage);
+				mergeUsage(this.usage, usage);
 				this.emit("supervisor.classifier.failed", { error });
 				throw error;
 			}
@@ -1243,7 +1251,7 @@ var SupervisorExecution = class {
 					usage,
 					error: interpretation.error
 				};
-				this.aggregateUsage(this.usage, usage);
+				mergeUsage(this.usage, usage);
 				this.emit("supervisor.classifier.failed", { error: interpretation.error });
 				throw interpretation.error;
 			}
@@ -1265,7 +1273,7 @@ var SupervisorExecution = class {
 			duration: performance.now() - startPerf,
 			usage
 		};
-		this.aggregateUsage(this.usage, usage);
+		mergeUsage(this.usage, usage);
 		this.emit("supervisor.classifier.completed", {
 			output: {
 				intent: this.classifierSnapshot.intent,
@@ -1655,17 +1663,18 @@ var SupervisorExecution = class {
 			this.terminatedBy = "error";
 		}
 		const endedAt = /* @__PURE__ */ new Date();
-		const finalStatus = this.status === "max-iterations" || this.status === "awaiting-input" ? "failed" : this.status;
+		const finalStatus = this.status === "max-iterations" || this.status === "awaiting-input" || this.status === "awaiting-approval" ? "failed" : this.status;
 		await this.checkpoint(finalStatus);
 		const report = {
 			runId: this.runId,
 			rootRunId: this.runId,
 			name: this.config.name,
 			version: this.config.version,
-			type: "supervisor",
+			type: this.config.reportType ?? "supervisor",
 			supervisorName: this.config.name,
 			signature: this.signature,
 			status: this.status,
+			...this.error ? { error: this.error } : {},
 			terminatedBy: this.terminatedBy,
 			iterations: this.snapshots.length,
 			startedAt: this.startedAtIso,
@@ -1683,7 +1692,7 @@ var SupervisorExecution = class {
 			sessionId: this.options?.sessionId
 		});
 		return {
-			type: "supervisor",
+			type: this.config.reportType ?? "supervisor",
 			data: this.data,
 			report,
 			usage: this.usage,
@@ -1770,12 +1779,8 @@ var SupervisorExecution = class {
 	*/
 	aggregateUsage(iterationUsage, partial) {
 		if (!partial) return;
-		this.usage.input += partial.input;
-		this.usage.output += partial.output;
-		this.usage.total += partial.total;
-		iterationUsage.input += partial.input;
-		iterationUsage.output += partial.output;
-		iterationUsage.total += partial.total;
+		mergeUsage(this.usage, partial);
+		mergeUsage(iterationUsage, partial);
 	}
 	/**
 	* Fan an event out through the three-tier emitter AND mirror it
@@ -1883,15 +1888,13 @@ function toAIError(thrown) {
 * `ctx.intents.X.execute()`. Mirrors `compositeAsTool` semantics.
 */
 function aggregateChildUsage(children) {
-	return children.reduce((acc, child) => ({
-		input: acc.input + child.usage.input,
-		output: acc.output + child.usage.output,
-		total: acc.total + child.usage.total
-	}), {
+	const total = {
 		input: 0,
 		output: 0,
 		total: 0
-	});
+	};
+	for (const child of children) mergeUsage(total, child.usage);
+	return total;
 }
 /**
 * Best-effort stringification for the snapshot's `input` field when