@warlock.js/ai 4.1.1

package/esm/contracts/supervisor/dispatch-context.type.d.mts

@@ -0,0 +1,235 @@
+import { Message } from "../conversation-message.type.mjs";
+import { AgentResult } from "../result/agent-result.type.mjs";
+import { StreamContract } from "../stream/stream.contract.mjs";
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { WorkflowResult } from "../result/workflow-result.type.mjs";
+import { WorkflowInstance, WorkflowRunOptions } from "../workflow/workflow.contract.mjs";
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
+import { SupervisorIntentValue } from "./intent-entry.type.mjs";
+import { SupervisorExecuteOptions } from "./supervisor-execute-options.type.mjs";
+import { SupervisorContract } from "./supervisor.contract.mjs";
+import { ClassifierSnapshot } from "./classifier-context.type.mjs";
+import { SupervisorResult } from "../result/supervisor-result.type.mjs";
+import { AgentExecuteOptions } from "../agent/agent-options.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/dispatch-context.type.d.ts
+/**
+ * Runner exposed on `DispatchContext.intents` for each registered
+ * intent. Two methods, mirroring the canonical execute / stream
+ * surface every executable primitive exposes:
+ *
+ * - `.execute(input?)` runs the named intent and returns its resolved
+ *   output value (existing — Phase 3.3).
+ * - `.stream(input?)` runs the named intent in streaming mode and
+ *   returns a `StreamContract` the caller can iterate or
+ *   `await .result` on (Phase 6 / decisions §36). Stream events
+ *   bubble up as `supervisor.agent.streaming` under the calling
+ *   callback's intent name when the supervisor itself is being
+ *   streamed.
+ *
+ * Without `input` → the dispatched primitive sees the calling
+ * callback's own `ctx.input`. With `input` → the override is
+ * forwarded.
+ *
+ * Throws `SupervisorFailedError` (`SUPERVISOR_DISPATCH_CYCLE`) when
+ * invoking would close a per-branch call cycle. Cycle detection is
+ * scoped per fan-out branch — sibling branches dispatching the same
+ * intent in parallel is NOT a cycle.
+ *
+ * Replaces the Phase-3.3 `ctx.dispatch.byName(name, input?)` helper
+ * with property-access + per-key autocomplete (Q5/Q6).
+ */
+type IntentRunner = {
+  execute: (input?: unknown) => Promise<unknown>;
+  stream: (input?: unknown) => StreamContract<SupervisableResult>;
+};
+/**
+ * Discriminated union of executable primitives that `ctx.run`
+ * accepts (Phase 6 / decisions §36). Tools are deliberately
+ * excluded — they have a different lifecycle and compose via
+ * `agent.tools[]`, not via supervised inline dispatch.
+ */
+type SupervisableExecutable = AgentContract<unknown> | WorkflowInstance<unknown, unknown> | SupervisorContract<unknown>;
+/**
+ * Subset of `SupervisableExecutable` that exposes a native
+ * `.stream()` method. Workflows currently expose streaming only
+ * through `workflow.step.streaming` events on `.execute()`; their
+ * inline streaming via `ctx.stream` is deferred to a future phase.
+ * Workflows still work through `ctx.run` — their step-streaming
+ * events bubble through the supervisor's existing top-level forward
+ * chain.
+ */
+type StreamableExecutable = AgentContract<unknown> | SupervisorContract<unknown>;
+/**
+ * Result envelope returned by `ctx.run(executable, ...)` — discriminated
+ * by the executable's kind. Callbacks typically know which one they
+ * passed and TS narrows accordingly.
+ */
+type SupervisableResult = AgentResult<unknown> | WorkflowResult<unknown> | SupervisorResult<unknown>;
+/**
+ * Per-call options to `ctx.run` / `ctx.stream`. Each kind's native
+ * options pass through; the supervisor auto-merges `signal`,
+ * `toolCtx`, and `history` defaults under the option payload before
+ * forwarding. Per-call value REPLACES the auto-default — standard
+ * Warlock convention.
+ */
+type SupervisableExecuteOptions = AgentExecuteOptions<unknown> | WorkflowRunOptions | SupervisorExecuteOptions;
+/**
+ * Map of registered intents keyed by their name in the supervisor's
+ * `intents` config. Generic-typed against the supplied `intents`
+ * object so `ctx.intents.<TAB>` autocompletes against the literal
+ * keys the user supplied.
+ */
+type IntentRunnerMap<TIntents extends Record<string, SupervisorIntentValue>> = { [K in keyof TIntents]: IntentRunner };
+/**
+ * Context passed to callback intents and to per-intent
+ * `input(ctx)` / `output(ctx)` resolvers in entries (callback or
+ * agent/workflow alike, where the resolver opts into the dispatch
+ * shape rather than the legacy `RouteContext`).
+ *
+ * Sibling of `RouteContext` — same conceptual context, but carries
+ * dispatch-specific fields (`intent`, `result`, `intents`) that
+ * don't make sense pre-routing.
+ *
+ * Generic over `TIntents` for autocomplete on `ctx.intents.X`. Most
+ * users never write the generic explicitly — it's inferable from
+ * the `SupervisorConfig<TOutput, TIntents>` argument.
+ *
+ * @example
+ * intents: {
+ *   refund: async (ctx) => {
+ *     if (typeof ctx.input === "object" && (ctx.input as { amount: number }).amount > 1_000) {
+ *       await ctx.intents.auditLog.execute();
+ *     }
+ *     return await callRefundAPI(ctx.input);
+ *   },
+ * }
+ */
+type DispatchContext<TState = Record<string, unknown>, TIntents extends Record<string, SupervisorIntentValue> = Record<string, SupervisorIntentValue>> = {
+  /** Zero-indexed iteration number — turn 0 is the first run. */iteration: number; /** This dispatch's intent name (the key from the `intents` map). */
+  intent: string;
+  /**
+   * Resolved input for this intent. Either the supervisor's
+   * original `execute(input)` value or the result of the entry's
+   * `input(ctx)` resolver when one was supplied.
+   */
+  input: unknown;
+  /**
+   * Per-execute typed accumulator. Built up across iterations as
+   * each intent contributes a slice via shallow-merge. Read-only
+   * from inside callbacks (Q3 — write via return value, not direct
+   * mutation). On the supervisor's clean termination, this is the
+   * value validated against `config.output` and returned as
+   * `result.data`.
+   *
+   * Defaults to `{}` when `config.state` is not declared. JSON-safe
+   * only — no functions / Maps / Sets / class instances (Q16) so
+   * snapshot resume works.
+   */
+  state: TState;
+  /**
+   * Current iteration's snapshot-in-progress — sibling branches
+   * that have already settled this iteration. Empty for the first
+   * branch dispatched in any iteration.
+   */
+  result: IterationSnapshot["result"];
+  /**
+   * Every completed iteration's snapshot, in chronological order.
+   * On turn 0 this is empty.
+   *
+   * Renamed from `history` (Q2) — the iteration trace is not
+   * conversation history; conversation memory is external to the
+   * supervisor (Q3).
+   */
+  iterations: IterationSnapshot[]; /** Cancellation signal — propagated from the `execute()` caller. */
+  signal: AbortSignal;
+  /**
+   * Registered intents accessible by key. Each entry is an
+   * `IntentRunner` exposing `.execute(input?)`. Property access on
+   * a typed map replaces the Phase-3.3 `ctx.dispatch.byName` string
+   * lookup — autocomplete + no typo crashes.
+   */
+  intents: IntentRunnerMap<TIntents>;
+  /**
+   * Read-only request-scoped bag supplied via
+   * `execute(input, { context })`. Shallow-copied + frozen at intake
+   * so callbacks can't mutate the caller's object. Defaults to a
+   * frozen `{}` when no context was passed. NOT persisted in
+   * snapshots — re-supply on `resume()`.
+   */
+  context: Readonly<Record<string, unknown>>;
+  /**
+   * Prior conversation messages supplied via
+   * `execute(input, { history })`. Read-only — passed by reference, not
+   * copied. Defaults to an empty array when no history was supplied.
+   * NOT persisted in snapshots — re-supply on `resume()`.
+   */
+  history: ReadonlyArray<Message>;
+  /**
+   * Resolved natural-language objective from `SupervisorConfig.goal`.
+   * `undefined` when the supervisor was configured without one.
+   * Read-only.
+   */
+  goal?: string;
+  /**
+   * Run an inline / un-registered executable under the supervisor's
+   * supervision (Phase 6 / decisions §36). The framework auto-merges
+   * `signal`, `toolCtx`, `history`, and report-nesting under the
+   * calling callback's intent name. Per-call `options` REPLACE
+   * auto-defaults (standard Warlock convention).
+   *
+   * Use when you need to compose an agent / workflow / supervisor
+   * inline that isn't in the `intents` map — e.g. an agent
+   * dynamically built from per-call config, or a delegate supervisor
+   * pulled from a registry.
+   *
+   * Returns the executable's full result envelope (`{ data, error,
+   * usage, report }`). Calls `.execute()` internally; for streaming,
+   * use `ctx.stream` instead.
+   *
+   * Cycle detection by executable `name` matches `ctx.intents.X.execute()`.
+   *
+   * @example
+   * intents: {
+   *   classifyInline: async ctx => {
+   *     const { data } = await ctx.run(classifierAgent, ctx.input);
+   *     return { category: data.label };
+   *   },
+   * }
+   */
+  run: (executable: SupervisableExecutable, input: unknown, options?: SupervisableExecuteOptions) => Promise<SupervisableResult>;
+  /**
+   * Stream an inline / un-registered executable under the
+   * supervisor's supervision (Phase 6 / decisions §36). Same auto-
+   * merge as `ctx.run` plus stream-event bubbling: deltas surface as
+   * `supervisor.agent.streaming { iteration, intent: "<callback name>",
+   * delta }` when the supervisor itself is being streamed.
+   *
+   * Returns the executable's own `StreamContract` — iterate with
+   * `for await`, `await .result`, or both. The framework attaches
+   * subscriptions transparently; the dev's existing usage of the
+   * returned stream is unchanged.
+   *
+   * @example
+   * intents: {
+   *   chatInline: async ctx => {
+   *     const { result } = ctx.stream(someAgent, enrich(ctx.input));
+   *     const final = await result;
+   *     return { reply: final.text };
+   *   },
+   * }
+   */
+  stream: (executable: StreamableExecutable, input: unknown, options?: SupervisableExecuteOptions) => StreamContract<SupervisableResult>;
+  /**
+   * Forensic record of iter-0 classifier run (Phase 7 / decisions §37).
+   * Present when `SupervisorConfig.classifier` was configured AND
+   * iter 0 has completed; `undefined` otherwise. Callbacks can
+   * read `ctx.classifier?.intent` / `.reasoning` / `.confidence` to
+   * inspect the classification trail without round-tripping through
+   * state.
+   */
+  classifier?: Readonly<ClassifierSnapshot>;
+};
+//#endregion
+export { DispatchContext, IntentRunner, IntentRunnerMap, StreamableExecutable, SupervisableExecutable, SupervisableExecuteOptions, SupervisableResult };
+//# sourceMappingURL=dispatch-context.type.d.mts.map

package/esm/contracts/supervisor/dispatch-context.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-context.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/dispatch-context.type.ts"],"mappings":";;;;;;;;;;;;;;;;;AAwCA;;;;;;;;;;;;;;;;AAEgE;AAShE;;;;;;;KAXY,YAAA;EACV,OAAA,GAAU,KAAA,eAAoB,OAAA;EAC9B,MAAA,GAAS,KAAA,eAAoB,cAAA,CAAe,kBAAA;AAAA;;AAYxB;AAWtB;;;;KAdY,sBAAA,GACR,aAAA,YACA,gBAAA,qBACA,kBAAA;AAoBJ;;;;;;;;;AAAA,KATY,oBAAA,GACR,aAAA,YACA,kBAAkB;;;AAUF;AASpB;;KAZY,kBAAA,GACR,WAAA,YACA,cAAA,YACA,gBAAA;;;;;;;;KASQ,0BAAA,GACR,mBAAA,YACA,kBAAA,GACA,wBAAA;;AAAwB;AAQ5B;;;;KAAY,eAAA,kBAAiC,MAAA,SAAe,qBAAA,mBAC9C,QAAA,GAAW,YAAA;;;;;;;;;;AAAY;AA2BrC;;;;;;;;;;;;;;KAAY,eAAA,UACD,MAAA,oCACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAAe,qBAAA;EAwD/D,+DArDT,SAAA,UA4DS;EA1DT,MAAA;EA8FY;;;;;EAxFZ,KAAA;EAmHK;;;;;;;;;;;;EAtGL,KAAA,EAAO,MAAA;EAnBP;;;;;EAyBA,MAAA,EAAQ,iBAAA;EASR;;;;;;;;EAAA,UAAA,EAAY,iBAAA,IAiBM;EAflB,MAAA,EAAQ,WAAA;EAsBC;;;;;;EAfT,OAAA,EAAS,eAAA,CAAgB,QAAA;EAmDb;;;;;;;EA3CZ,OAAA,EAAS,QAAA,CAAS,MAAA;EAqEN;;;;;;EA9DZ,OAAA,EAAS,aAAA,CAAc,OAAA;EAwEiB;AAAA;;;;EAlExC,IAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BA,GAAA,GACE,UAAA,EAAY,sBAAA,EACZ,KAAA,WACA,OAAA,GAAU,0BAAA,KACP,OAAA,CAAQ,kBAAA;;;;;;;;;;;;;;;;;;;;;;EAsBb,MAAA,GACE,UAAA,EAAY,oBAAA,EACZ,KAAA,WACA,OAAA,GAAU,0BAAA,KACP,cAAA,CAAe,kBAAA;;;;;;;;;EASpB,UAAA,GAAa,QAAA,CAAS,kBAAA;AAAA"}

package/esm/contracts/supervisor/evaluate-context.type.d.mts

@@ -0,0 +1,124 @@
+import { Message } from "../conversation-message.type.mjs";
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "../result/usage.type.mjs";
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
+import { SupervisorInput } from "./supervisor-input.type.mjs";
+import { ClassifierSnapshot } from "./classifier-context.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/evaluate-context.type.d.ts
+/**
+ * Per-branch summary passed to `evaluate` via
+ * `EvaluateContext.result[intent]`. Carries exactly what `evaluate`
+ * needs to judge the turn — the transformed output, timing, token
+ * usage, and any per-branch error that didn't abort the sibling
+ * dispatches.
+ *
+ * Distinct from `AgentBranchSnapshot` because it's the `evaluate`
+ * contract, not the persistence contract — snapshots mirror the same
+ * fields plus canonical timestamps and a frozen shape.
+ */
+type EvaluateBranchResult = {
+  /** Output after the per-agent `output` transformer (if any). */output: unknown; /** The resolved input string sent to the agent this iteration. */
+  input: string;
+  usage: Usage;
+  durationMs: number;
+  /**
+   * Per-branch typed error. Set only when this specific branch
+   * failed; sibling branches and the evaluate pass still run.
+   */
+  error?: AIError;
+};
+/**
+ * Context passed to a supervisor's `evaluate` callback. Fires
+ * retrospectively after the iteration's agent(s) have settled —
+ * never before dispatch — so `result` is populated.
+ *
+ * `result` is a `Record` keyed by intent name (not an array) — see
+ * design §10 for why: it keeps consumer code uniform whether one
+ * agent or three ran, matches the `intents` config shape, and
+ * expresses "didn't run this iteration" cleanly as key absence.
+ *
+ * @example
+ * evaluate: (ctx) => {
+ *   if (ctx.result.resolver?.output) { return { satisfied: true }; }
+ *   if (!ctx.result.research) { return { reassignTo: "research" }; }
+ *   return undefined;
+ * }
+ */
+type EvaluateContext<TState = Record<string, unknown>> = {
+  iteration: number; /** The supervisor's original `execute(input)` value. */
+  input: SupervisorInput;
+  /**
+   * Per-execute typed accumulator AFTER this iteration's intents
+   * have merged their outputs. State-driven termination logic
+   * (`return ctx.state.reply ? { satisfied: true } : undefined`)
+   * lives here.
+   */
+  state: TState;
+  /**
+   * Outputs from this iteration's dispatched agents, keyed by intent
+   * name. Absent key = didn't run this iteration. Always an object —
+   * even single-agent iterations produce a one-key record.
+   */
+  result: Record<string, EvaluateBranchResult>;
+  /**
+   * Prior iterations' snapshots, in chronological order.
+   *
+   * Renamed from `history` (Q2).
+   */
+  iterations: IterationSnapshot[];
+  /**
+   * Read-only request-scoped bag supplied via
+   * `execute(input, { context })`. Shallow-copied + frozen at intake
+   * so callbacks can't mutate the caller's object. Defaults to a
+   * frozen `{}` when no context was passed. NOT persisted in
+   * snapshots — re-supply on `resume()`.
+   */
+  context: Readonly<Record<string, unknown>>;
+  /**
+   * Prior conversation messages supplied via
+   * `execute(input, { history })`. Read-only — passed by reference, not
+   * copied. Defaults to an empty array when no history was supplied.
+   * NOT persisted in snapshots — re-supply on `resume()`.
+   */
+  history: ReadonlyArray<Message>;
+  /**
+   * Resolved natural-language objective from `SupervisorConfig.goal`.
+   * `undefined` when the supervisor was configured without one.
+   * Read-only. Especially useful for goal-aware satisfaction checks:
+   * `evaluate` can compare `ctx.state` against `ctx.goal` semantics
+   * without hardcoded strings.
+   */
+  goal?: string;
+  /**
+   * Forensic record of iter-0 classifier run (Phase 7 / decisions §37).
+   * Present when `SupervisorConfig.classifier` was configured AND
+   * iter 0 has completed (classifier mode supervisors only). Lets
+   * `evaluate` factor the classification trail into satisfaction
+   * checks without re-reading from state.
+   */
+  classifier?: Readonly<ClassifierSnapshot>;
+};
+/**
+ * Verdict returned by `evaluate`. Fields may be combined:
+ *
+ * - `undefined` — trust the router/route; continue to the next
+ *   iteration unchanged.
+ * - `{ satisfied: true }` — terminate the run successfully.
+ * - `{ reassignTo: string | string[] }` — override the next
+ *   iteration's dispatch decision. Supports fan-out via array form.
+ * - `{ feedback: string }` — inject reviewer feedback into the next
+ *   iteration's composed input.
+ *
+ * Combining works exactly as expected: `{ reassignTo: "critic",
+ * feedback: "focus on factual errors" }` forces a critic dispatch
+ * with the feedback threaded into its input.
+ */
+type EvaluateResult = undefined | {
+  satisfied?: boolean;
+  reassignTo?: string | string[];
+  feedback?: string;
+};
+//#endregion
+export { EvaluateBranchResult, EvaluateContext, EvaluateResult };
+//# sourceMappingURL=evaluate-context.type.d.mts.map

package/esm/contracts/supervisor/evaluate-context.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-context.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/evaluate-context.type.ts"],"mappings":";;;;;;;;;;AAkBA;;;;;;;;;KAAY,oBAAA;EAWF,gEATR,MAAA,WASe;EAPf,KAAA;EACA,KAAA,EAAO,KAAA;EACP,UAAA;EAyBmC;;;;EApBnC,KAAA,GAAQ,OAAO;AAAA;;;;;;;;;;;;;;;;;;KAoBL,eAAA,UAAyB,MAAA;EACnC,SAAA,UAqBY;EAnBZ,KAAA,EAAO,eAAA;EA2BE;;;;;;EApBT,KAAA,EAAO,MAAA;EA2CM;;;AAA2B;AAkB1C;EAvDE,MAAA,EAAQ,MAAA,SAAe,oBAAA;;;;;;EAMvB,UAAA,EAAY,iBAAA;EAsDA;;;;;;;EA9CZ,OAAA,EAAS,QAAA,CAAS,MAAA;;;;;;;EAOlB,OAAA,EAAS,aAAA,CAAc,OAAA;;;;;;;;EAQvB,IAAA;;;;;;;;EAQA,UAAA,GAAa,QAAA,CAAS,kBAAA;AAAA;;;;;;;;;;;;;;;;KAkBZ,cAAA;EAGN,SAAA;EACA,UAAA;EACA,QAAA;AAAA"}

package/esm/contracts/supervisor/index.d.mts

@@ -0,0 +1,16 @@
+import { END, EndSentinel } from "../end.type.mjs";
+import { Next } from "./next.type.mjs";
+import { AckSnapshot, AgentBranchSnapshot, DecisionSource, IterationDecision, IterationSnapshot } from "./iteration-snapshot.type.mjs";
+import { SupervisorInput } from "./supervisor-input.type.mjs";
+import { EvaluateBranchResult, EvaluateContext, EvaluateResult } from "./evaluate-context.type.mjs";
+import { RouteContext } from "./route-context.type.mjs";
+import { AckCallback, AckConfig, AckEntry, AckRunEntry } from "./ack-entry.type.mjs";
+import { DispatchRawResult, IntentCallback, IntentEntry, IntentRunEntry, SupervisorIntentValue } from "./intent-entry.type.mjs";
+import { RouterEntry } from "./router-entry.type.mjs";
+import { SupervisorConfig, SupervisorEventHandler, SupervisorEventHandlers } from "./supervisor-config.type.mjs";
+import { SupervisorExecuteOptions, SupervisorResumeOptions } from "./supervisor-execute-options.type.mjs";
+import { SupervisorStreamEvent } from "./supervisor-stream-event.type.mjs";
+import { SupervisorAsToolOptions, SupervisorContract } from "./supervisor.contract.mjs";
+import { DispatchContext, IntentRunner, IntentRunnerMap } from "./dispatch-context.type.mjs";
+import { ClassifierAgentEntry, ClassifierCallback, ClassifierConfig, ClassifierContext, ClassifierOutput, ClassifierRefineContext, ClassifierRefineResult, ClassifierRunEntry, ClassifierSnapshot } from "./classifier-context.type.mjs";
+import { SupervisorSnapshot, SupervisorSnapshotStatus } from "./supervisor-snapshot.type.mjs";

package/esm/contracts/supervisor/intent-entry.type.d.mts

@@ -0,0 +1,254 @@
+import { Message } from "../conversation-message.type.mjs";
+import { AgentResult } from "../result/agent-result.type.mjs";
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { EndSentinel } from "../end.type.mjs";
+import { WorkflowResult } from "../result/workflow-result.type.mjs";
+import { WorkflowInstance } from "../workflow/workflow.contract.mjs";
+import { RouteContext } from "./route-context.type.mjs";
+import { DispatchContext } from "./dispatch-context.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/intent-entry.type.d.ts
+/**
+ * Raw result produced by a dispatched unit — either an agent or a
+ * workflow — before any per-intent strip-merge runs.
+ *
+ * Exposed as a named alias so consumers reading
+ * `IterationSnapshot.result[intent].output` know the shape.
+ */
+type DispatchRawResult = AgentResult<unknown> | WorkflowResult<unknown>;
+/**
+ * Object form of an entry in a supervisor's `intents` map (agent
+ * variant). Use when you need to override the unit's `description`,
+ * customize the per-dispatch input string, declare a state slice via
+ * an `output` schema, or supply per-dispatch placeholder values for
+ * the agent's systemPrompt template.
+ *
+ * Every field other than `agent` is optional — the shorthand form
+ * (`intents: { triage: triageAgent }`) simply omits all of them.
+ *
+ * Phase 3.4 (Stage 4b) — `output` shifted from a transformer
+ * `(raw) => unknown` to a `StandardSchemaV1` schema (Q11/Q13). The
+ * schema declares the slice this intent contributes to supervisor
+ * state; agent output is strip-merged against it. `placeholders`
+ * is new — feeds into `agent.execute(input, { placeholders })`.
+ *
+ * @example
+ * intents: {
+ *   classify: {
+ *     agent: classifierAgent,
+ *     description: "First-pass classifier",
+ *     placeholders: (ctx) => ({ message: ctx.input }),
+ *     output: v.object({ classification: v.enum(["billing", "shipping"]) }),
+ *   },
+ * }
+ */
+type IntentEntry = {
+  /** The underlying dispatchable unit — an agent or a workflow. */agent: AgentContract<unknown> | WorkflowInstance<unknown, unknown>;
+  /**
+   * Overrides the unit's own `description` when the router agent's
+   * per-turn context is assembled. Required fallback when the
+   * underlying agent/workflow doesn't carry one.
+   */
+  description?: string;
+  /**
+   * Per-intent input composer — escape hatch for the rare case where
+   * the agent's user message itself must vary per intent. Runs after
+   * routing decides this intent should dispatch. Without it, the
+   * agent receives the supervisor's `ctx.input` unchanged.
+   */
+  input?: (ctx: RouteContext) => string;
+  /**
+   * Per-dispatch placeholder values for the agent's `systemPrompt`
+   * template. Receives the upcoming `DispatchContext` so the
+   * computation can read `ctx.state`, `ctx.iterations`, etc. Result
+   * is forwarded as `agent.execute(input, { placeholders })` —
+   * filling in `{{key}}` references in the agent's systemPrompt.
+   *
+   * Phase 3.4 — replaces the dropped `composeAgentInput` mechanism
+   * for threading prior-iteration context into agents. Use this for
+   * "what should the agent know about state right now?" rather than
+   * for "what's the agent's user message?" (that's `input`).
+   */
+  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;
+  /**
+   * Schema declaring the slice this intent contributes to supervisor
+   * state. Agent output is strip-merged against it: only validated
+   * keys land on `IterationSnapshot.result[intent].output` AND merge
+   * into supervisor `state`.
+   *
+   * Without `output`: the agent's full `data` (or `text` fallback)
+   * passes through to the snapshot but is NOT auto-merged into
+   * state — explicit opt-in keeps state clean.
+   *
+   * Validation failure surfaces as a per-branch error on the
+   * iteration snapshot; sibling branches still run.
+   */
+  output?: StandardSchemaV1<unknown>;
+  /**
+   * Per-intent successor directive (Phase 3.4 Stage 4d / Q24).
+   * After this intent runs and its slice merges into state, the
+   * supervisor calls `next(ctx)`:
+   *
+   * - Returns intent name (or array) → next iteration dispatches
+   *   that. **No router LLM call.**
+   * - Returns `END` → terminate. **No router call, no evaluate.**
+   * - Returns `undefined` → fall back to router/route as today.
+   *
+   * Precedence: `evaluate` outranks `next`; `next` outranks
+   * router/route. Fan-out: each branch's `next` is collected after
+   * all branches settle; the union of unique intents drives the
+   * next iteration; any `END` terminates; silent branches abstain.
+   */
+  next?: (ctx: DispatchContext) => string | string[] | EndSentinel | undefined;
+  /**
+   * Custom history slicer for this intent's agent/workflow. When
+   * supplied, REPLACES the default slice (full history clipped by
+   * `SupervisorConfig.historyWindow.agents` if set).
+   *
+   * Precedence: entry `history` callback > `historyWindow.agents` >
+   * full history. Return `[]` to send no history at all (handy for
+   * pure-retrieval RAG agents that just need the current input).
+   *
+   * @example
+   * intents: {
+   *   sales: {
+   *     agent: salesAgent,
+   *     history: (ctx) => ctx.history.slice(-15),
+   *   },
+   *   rag: { agent: ragAgent, history: () => [] },
+   * }
+   */
+  history?: (ctx: RouteContext) => Message[] | ReadonlyArray<Message>;
+  /**
+   * Dispatch mode (Phase 5 / decisions §34).
+   *
+   * - `"structured"` (default) — agent runs with the per-intent
+   *   `output` schema (or a free-form completion if `output` is
+   *   absent). Existing behavior; every prior intent keeps it.
+   * - `"stream"` — agent runs **without** structured-output coercion.
+   *   Raw text deltas forward as `supervisor.agent.streaming` events;
+   *   the assembled prose lands on `state[streamTo]` at completion.
+   *
+   * Stream mode is mutually exclusive with `output` at the intent
+   * level — a stream-mode intent declares its state contribution via
+   * `streamTo`, not via a schema. The factory throws
+   * `SUPERVISOR_INTENT_STREAM_AND_OUTPUT` if both are set, and
+   * `SUPERVISOR_INTENT_STREAM_TO_REQUIRED` if `mode === "stream"` and
+   * `streamTo` is missing.
+   *
+   * **Workflow entries do NOT support stream mode in v1** — workflows
+   * have no guaranteed single-LLM-text terminal contract. The factory
+   * throws if `mode: "stream"` is set on a workflow entry.
+   */
+  mode?: "structured" | "stream";
+  /**
+   * State key the assembled stream-mode prose writes into. Required
+   * when `mode === "stream"`; ignored otherwise. The supervisor
+   * builds `{ [streamTo]: assembledText }` as the branch's output
+   * slice and merges it into `state` like any other slice.
+   */
+  streamTo?: string;
+};
+/**
+ * Callback dispatch shorthand — an intent handled by dev code rather
+ * than by an agent or workflow. Same shape as `ai.step({ run })`.
+ *
+ * Receives a {@link DispatchContext} and returns a value (sync or
+ * async). The return value shallow-merges into supervisor state.
+ * The framework wraps the return value in a synthesized leaf report
+ * (`type: "callback"`, zero usage, real timing). Throws propagate
+ * as `SupervisorFailedError` with `cause` set.
+ *
+ * @example
+ * intents: {
+ *   refund: async (ctx) => {
+ *     const id = await callRefundAPI(ctx.input);
+ *     return { refundId: id };  // shallow-merged into ctx.state
+ *   },
+ * }
+ */
+type IntentCallback = (ctx: DispatchContext) => unknown | Promise<unknown>;
+/**
+ * Object form of a callback intent — preferred when you need a
+ * `description` (required under a router) or want per-intent
+ * `input` / `output` shapes.
+ *
+ * Mirrors `ai.step({ run, description, ... })` so users moving
+ * between workflow and supervisor see the same vocabulary.
+ *
+ * Phase 3.4 (Stage 4b) — `output` shifted from a transformer to
+ * a `StandardSchemaV1`. Without it, the callback's full return
+ * shallow-merges into state. With it, the return is strip-merged
+ * to declared keys only.
+ *
+ * @example
+ * intents: {
+ *   cancel: {
+ *     run: async (ctx) => ({ cancelledId: await cancelOrder(ctx.input) }),
+ *     description: "Cancel an order on explicit customer request",
+ *     output: v.object({ cancelledId: v.string() }),
+ *   },
+ * }
+ */
+type IntentRunEntry = {
+  /** The dispatch callback. Receives a {@link DispatchContext}. */run: IntentCallback;
+  /**
+   * Required when the supervisor is configured with a `router` —
+   * otherwise the router LLM has no signal for picking this intent.
+   * Optional in deterministic-route mode.
+   */
+  description?: string;
+  /**
+   * Per-intent input resolver. Receives a {@link DispatchContext}
+   * (the callback's eventual context) and returns the value passed
+   * as `ctx.input`. Defaults to the supervisor's input string.
+   */
+  input?: (ctx: DispatchContext) => unknown;
+  /**
+   * Per-dispatch placeholder values. Same role as on `IntentEntry` —
+   * available on callback entries for symmetry, though callbacks
+   * usually don't have a systemPrompt template to fill.
+   */
+  placeholders?: (ctx: DispatchContext) => Record<string, unknown>;
+  /**
+   * Schema declaring the slice this callback contributes to
+   * supervisor state. Without it, the full return value
+   * shallow-merges. With it, return is strip-merged to declared keys.
+   */
+  output?: StandardSchemaV1<unknown>;
+  /**
+   * Per-intent successor directive (Phase 3.4 Stage 4d / Q24). See
+   * `IntentEntry.next` — same semantics, available on callback
+   * intents too.
+   */
+  next?: (ctx: DispatchContext) => string | string[] | EndSentinel | undefined;
+};
+/**
+ * The accepted shapes for a value in the supervisor's
+ * `intents: Record<string, …>` config:
+ *
+ * - `AgentContract` — shorthand; description inferred from the agent.
+ * - `WorkflowInstance` — shorthand; description inferred from the
+ *   workflow (must be present).
+ * - `IntentCallback` — bare async/sync function shorthand, dispatched
+ *   as dev code. Description-less; allowed only in deterministic
+ *   `route` mode. Under a router, upgrade to `IntentRunEntry`.
+ * - `IntentEntry` — full object form for an agent/workflow with
+ *   optional overrides.
+ * - `IntentRunEntry` — full object form for a callback intent.
+ *
+ * The runtime resolver discriminates by checking, in order:
+ * `function → "run" in value → "agent" in value → instanceof`.
+ * Mixed dispatch fields (e.g. `{ agent, run }`) throw at construction.
+ *
+ * Every key must ultimately resolve to a non-empty description when
+ * the supervisor is configured with a `router` — the factory throws
+ * `SupervisorFailedError` (`SUPERVISOR_INTENT_DESCRIPTION_REQUIRED`)
+ * if any router-routed intent lacks one. Deterministic-route callers
+ * skip the check.
+ */
+type SupervisorIntentValue = AgentContract<unknown> | WorkflowInstance<unknown, unknown> | IntentCallback | IntentEntry | IntentRunEntry;
+//#endregion
+export { DispatchRawResult, IntentCallback, IntentEntry, IntentRunEntry, SupervisorIntentValue };
+//# sourceMappingURL=intent-entry.type.d.mts.map

package/esm/contracts/supervisor/intent-entry.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-entry.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/intent-entry.type.ts"],"mappings":";;;;;;;;;;;;;AAiBA;;;;AAAqE;KAAzD,iBAAA,GAAoB,WAAA,YAAuB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BzD,WAAA;EA0CV,iEAxCA,KAAA,EAAO,aAAA,YAAyB,gBAAA;EAwDhC;;;;;EAlDA,WAAA;EAqEW;;;;;;EA9DX,KAAA,IAAS,GAAA,EAAK,YAAA;EA2FN;AAqBV;;;;;;;;AAAwE;AAwBxE;;EA3HE,YAAA,IAAgB,GAAA,EAAK,eAAA,KAAoB,MAAA;EA6HpC;;;;;;;;;;;;;EA/GL,MAAA,GAAS,gBAAA;EA2HA;;;;;;;;;;;;AAkBuD;AA2BlE;;EAxJE,IAAA,IAAQ,GAAA,EAAK,eAAA,yBAAwC,WAAA;EAyJnD;;;;;;;;;;;;;AAIc;;;;;EA1IhB,OAAA,IAAW,GAAA,EAAK,YAAA,KAAiB,OAAA,KAAY,aAAA,CAAc,OAAA;;;;;;;;;;;;;;;;;;;;;;EAsB3D,IAAA;;;;;;;EAOA,QAAA;AAAA;;;;;;;;;;;;;;;;;;;KAqBU,cAAA,IAAkB,GAAA,EAAK,eAAA,eAA8B,OAAO;;;;;;;;;;;;;;;;;;;;;;;KAwB5D,cAAA;mEAEV,GAAA,EAAK,cAAA;;;;;;EAML,WAAA;;;;;;EAMA,KAAA,IAAS,GAAA,EAAK,eAAA;;;;;;EAMd,YAAA,IAAgB,GAAA,EAAK,eAAA,KAAoB,MAAA;;;;;;EAMzC,MAAA,GAAS,gBAAA;;;;;;EAMT,IAAA,IAAQ,GAAA,EAAK,eAAA,yBAAwC,WAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;KA2B3C,qBAAA,GACR,aAAA,YACA,gBAAA,qBACA,cAAA,GACA,WAAA,GACA,cAAA"}