{"version":3,"file":"entries.mjs","names":[],"sources":["../../../../../../../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.` slice.\n */\nexport type EntryHistorySlicer = (ctx: RouteContext) => Message[] | ReadonlyArray;\n\nexport type ResolvedAgentEntry = {\n intent: string;\n type: \"agent\";\n unit: AgentContract;\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;\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;\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;\n description: string;\n input?: (ctx: RouteContext) => string;\n placeholders?: (ctx: DispatchContext) => Record;\n output?: StandardSchemaV1;\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;\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;\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,\n supervisorName: string,\n): Map {\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();\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,\n entries: Map,\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 | WorkflowInstance);\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,\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,\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 | WorkflowInstance {\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 | WorkflowInstance,\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).stream === \"function\") {\n return \"agent\";\n }\n\n return \"workflow\";\n}\n\nfunction resolveAgentLikeDescription(\n intent: string,\n entryForm: IntentEntry | undefined,\n unit: AgentContract | WorkflowInstance,\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 {\n return raw.type === \"agent\";\n}\n\nexport function isWorkflowResult(raw: DispatchRawResult): raw is WorkflowResult {\n return raw.type === \"workflow\";\n}\n"],"mappings":"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"}