@warlock.js/ai 4.1.1

package/esm/supervisor/cancellation.mjs

@@ -0,0 +1,22 @@
+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/supervisor/cancellation.mjs.map

@@ -0,0 +1 @@
+{"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,GAAE,YAAY;EAAG,QAAQ;CAAW,CAC9D;AACF"}

package/esm/supervisor/decide.mjs

@@ -0,0 +1,272 @@
+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/supervisor/decide.mjs.map

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

package/esm/supervisor/emitter.d.mts

@@ -0,0 +1,27 @@
+import { SupervisorEventHandler, SupervisorEventHandlers } from "../contracts/supervisor/supervisor-config.type.mjs";
+import { SupervisorEventMap } from "../contracts/events/event-map.type.mjs";
+
+//#region ../../@warlock.js/ai/src/supervisor/emitter.d.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);
+ */
+declare class SupervisorEmitter {
+  private readonly factoryHandlers?;
+  private readonly instanceHandlers;
+  constructor(factoryHandlers?: SupervisorEventHandlers);
+  on<K extends keyof SupervisorEventMap>(event: K, handler: SupervisorEventHandler<K>): () => void;
+  off<K extends keyof SupervisorEventMap>(event: K, handler: SupervisorEventHandler<K>): void;
+  emit<K extends keyof SupervisorEventMap>(event: K, payload: SupervisorEventMap[K], executionHandlers?: SupervisorEventHandlers): void;
+}
+//#endregion
+export { SupervisorEmitter };
+//# sourceMappingURL=emitter.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/emitter.ts"],"mappings":";;;;;;AAoBA;;;;;;;;;;cAAa,iBAAA;EAAA,iBACM,eAAA;EAAA,iBACA,gBAAA;cAKE,eAAA,GAAkB,uBAAA;EAI9B,EAAA,iBAAmB,kBAAA,CAAA,CACxB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,sBAAA,CAAuB,CAAA;EAc3B,GAAA,iBAAoB,kBAAA,CAAA,CACzB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,sBAAA,CAAuB,CAAA;EAK3B,IAAA,iBAAqB,kBAAA,CAAA,CAC1B,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,kBAAA,CAAmB,CAAA,GAC5B,iBAAA,GAAoB,uBAAA;AAAA"}

package/esm/supervisor/emitter.mjs

@@ -0,0 +1,47 @@
+//#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/supervisor/emitter.mjs.map

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

package/esm/supervisor/entries.d.mts

@@ -0,0 +1,141 @@
+import { Message } from "../contracts/conversation-message.type.mjs";
+import { AgentContract } from "../contracts/agent/agent.contract.mjs";
+import { EndSentinel } from "../contracts/end.type.mjs";
+import { WorkflowInstance } from "../contracts/workflow/workflow.contract.mjs";
+import { RouteContext } from "../contracts/supervisor/route-context.type.mjs";
+import { IntentCallback, SupervisorIntentValue } from "../contracts/supervisor/intent-entry.type.mjs";
+import { DispatchContext } from "../contracts/supervisor/dispatch-context.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/supervisor/entries.d.ts
+/**
+ * Normalized internal representation of one entry in a supervisor's
+ * `intents` map — resolved at factory time from one of the accepted
+ * value forms (bare agent / workflow / callback / object entry).
+ *
+ * Carrying the explicit `type` discriminator keeps downstream code
+ * (execution, signature, router-prompt) from having to re-detect
+ * shape on every dispatch. The discriminated union below replaces
+ * the flat-shape used in Phase 3 so callbacks can carry their own
+ * function reference + dispatch-context-shaped resolvers.
+ *
+ * Discriminator renamed `kind` → `type` (Q12) for codebase-wide
+ * consistency — every other discriminated result/report shape uses
+ * `type`.
+ */
+type ResolvedIntentEntry = ResolvedAgentEntry | ResolvedWorkflowEntry | ResolvedCallbackEntry;
+/**
+ * Successor directive function type — the resolver-time projection of
+ * `IntentEntry.next` / `IntentRunEntry.next`. Single source of truth
+ * across the three resolved variants.
+ */
+type IntentNext = (ctx: DispatchContext) => string | string[] | EndSentinel | undefined;
+/**
+ * Resolver-time projection of `IntentEntry.history` /
+ * `RouterEntry.history` / `AckEntry.history`. Custom slicer that
+ * REPLACES the default `historyWindow.<role>` slice.
+ */
+type EntryHistorySlicer = (ctx: RouteContext) => Message[] | ReadonlyArray<Message>;
+type ResolvedAgentEntry = {
+  intent: string;
+  type: "agent";
+  unit: AgentContract<unknown>;
+  description: string;
+  input?: (ctx: RouteContext) => string;
+  /**
+   * Per-dispatch placeholder values for the agent's systemPrompt
+   * template. Forwarded as `agent.execute(input, { placeholders })`.
+   * Phase 3.4 (Stage 4b) — replaces the dropped `composeAgentInput`
+   * mechanism for threading state into agents.
+   */
+  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;
+  /**
+   * Schema declaring this intent's slice of supervisor state. Agent
+   * output is strip-merged against it; only validated keys appear on
+   * `IterationSnapshot.result[intent].output` AND merge into
+   * supervisor `state`.
+   */
+  output?: StandardSchemaV1<unknown>;
+  /**
+   * Successor directive (Stage 4d / Q24). When present, runs after
+   * this branch's slice merges into state to choose the next dispatch
+   * (or terminate) without invoking the router.
+   */
+  next?: IntentNext;
+  /**
+   * Custom history slicer — replaces the default
+   * `historyWindow.agents` slice when supplied. See `IntentEntry.history`.
+   */
+  history?: EntryHistorySlicer;
+  /**
+   * Phase 5 / decisions §34. `"stream"` runs the agent without
+   * structured-output coercion and writes the assembled prose into
+   * `state[streamTo]`; `"structured"` is the default. Resolved at
+   * factory time — `undefined` here is treated as `"structured"`.
+   */
+  mode?: "structured" | "stream"; /** State key the assembled stream-mode prose writes into. Set iff `mode === "stream"`. */
+  streamTo?: string;
+};
+type ResolvedWorkflowEntry = {
+  intent: string;
+  type: "workflow";
+  unit: WorkflowInstance<unknown, unknown>;
+  description: string;
+  input?: (ctx: RouteContext) => string;
+  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;
+  output?: StandardSchemaV1<unknown>;
+  next?: IntentNext;
+  history?: EntryHistorySlicer;
+};
+type ResolvedCallbackEntry = {
+  intent: string;
+  type: "callback";
+  /**
+   * The callback that actually runs at dispatch time. Always present
+   * regardless of whether the user passed bare-function shorthand or
+   * the `{ run, ... }` entry form.
+   */
+  callback: IntentCallback;
+  /**
+   * Description is required only when the supervisor uses a router.
+   * Callback intents under a router are validated separately
+   * (see {@link assertRouterDescriptions}); under deterministic
+   * `route` mode this field is `undefined`.
+   */
+  description?: string;
+  /**
+   * Per-intent input resolver. Receives the upcoming
+   * `DispatchContext` and returns the value forwarded as
+   * `ctx.input` to the callback.
+   */
+  input?: (ctx: DispatchContext) => unknown;
+  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;
+  /**
+   * Schema declaring this callback's slice of state. Without it, the
+   * full return value shallow-merges; with it, return is strip-merged
+   * to declared keys before merging.
+   */
+  output?: StandardSchemaV1<unknown>;
+  next?: IntentNext;
+};
+/**
+ * Validate and normalize the `intents` map into resolved entries.
+ * Runs at factory time — throws `SupervisorFailedError` on the first
+ * malformed entry so author-time bugs surface immediately rather
+ * than mid-run.
+ *
+ * Validation rules:
+ * - Every value must be an agent, a workflow, a callback function,
+ *   or an object entry with `agent` / `workflow` / `run`.
+ * - Object entries with more than one of `{ agent, workflow, run }`
+ *   throw with code `SUPERVISOR_INTENT_MIXED_DISPATCH`.
+ * - Agent / workflow / agent-shaped entries must resolve to a
+ *   non-empty description from the underlying unit or the entry's
+ *   `description` override. Bare callback shorthand has no
+ *   description source — that's enforced separately by
+ *   {@link assertRouterDescriptions} when a router is configured.
+ */
+declare function resolveIntentEntries(rawIntents: Record<string, SupervisorIntentValue>, supervisorName: string): Map<string, ResolvedIntentEntry>;
+//#endregion
+export { ResolvedIntentEntry, resolveIntentEntries };
+//# sourceMappingURL=entries.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/entries.ts"],"mappings":";;;;;;;;;;AAkCA;;;;;;;;;;;;AAGyB;AAOzB;;AAVA,KAAY,mBAAA,GACR,kBAAA,GACA,qBAAA,GACA,qBAAA;;;;;;KAOQ,UAAA,IAAc,GAAA,EAAK,eAAA,yBAAwC,WAAW;AAOlF;;;;;AAAA,KAAY,kBAAA,IAAsB,GAAA,EAAK,YAAA,KAAiB,OAAA,KAAY,aAAA,CAAc,OAAA;AAAA,KAEtE,kBAAA;EACV,MAAA;EACA,IAAA;EACA,IAAA,EAAM,aAAA;EACN,WAAA;EACA,KAAA,IAAS,GAAA,EAAK,YAAA;EAPoD;;;AAAqB;AAEzF;;EAYE,YAAA,IAAgB,GAAA,EAAK,eAAA,KAAoB,MAAA;EATnC;;;;;;EAgBN,MAAA,GAAS,gBAAA;EAWmB;;;;;EAL5B,IAAA,GAAO,UAAA;EArBP;;;;EA0BA,OAAA,GAAU,kBAAA;EAlBW;;;;;;EAyBrB,IAAA,4BAPA;EASA,QAAA;AAAA;AAAA,KAGU,qBAAA;EACV,MAAA;EACA,IAAA;EACA,IAAA,EAAM,gBAAA;EACN,WAAA;EACA,KAAA,IAAS,GAAA,EAAK,YAAA;EACd,YAAA,IAAgB,GAAA,EAAK,eAAA,KAAoB,MAAA;EACzC,MAAA,GAAS,gBAAA;EACT,IAAA,GAAO,UAAA;EACP,OAAA,GAAU,kBAAA;AAAA;AAAA,KAGA,qBAAA;EACV,MAAA;EACA,IAAA;EAL4B;;;;;EAW5B,QAAA,EAAU,cAAA;EAfV;;;;;;EAsBA,WAAA;EApBA;;;;;EA0BA,KAAA,IAAS,GAAA,EAAK,eAAA;EACd,YAAA,IAAgB,GAAA,EAAK,eAAA,KAAoB,MAAA;EAzBb;AAG9B;;;;EA4BE,MAAA,GAAS,gBAAA;EACT,IAAA,GAAO,UAAA;AAAA;;;;;;;;;;;;;;;;;;iBAoBO,oBAAA,CACd,UAAA,EAAY,MAAA,SAAe,qBAAA,GAC3B,cAAA,WACC,GAAA,SAAY,mBAAA"}