@warlock.js/ai 4.1.1

package/esm/contracts/supervisor/iteration-snapshot.type.d.mts

@@ -0,0 +1,117 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "../result/usage.type.mjs";
+import { Next } from "./next.type.mjs";
+import { EvaluateResult } from "./evaluate-context.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/iteration-snapshot.type.d.ts
+/**
+ * Per-branch snapshot captured during dispatch — one per intent that
+ * ran in the iteration. The persistence-grade record of what each
+ * agent did, kept frozen (`Readonly`) so consumers can safely pass
+ * snapshots across async boundaries without defensive cloning.
+ *
+ * Keyed into `IterationSnapshot.result` by the intent name (the key
+ * from the supervisor's `intents` config). Absent key = the intent
+ * didn't dispatch this iteration.
+ */
+type AgentBranchSnapshot = Readonly<{
+  /** The `intents` map key that identified this dispatch. */intent: string; /** Resolved input string the agent/workflow received. */
+  input: string; /** Output after the per-agent `output` transformer (if any). */
+  output: unknown;
+  usage: Usage;
+  startedAt: string;
+  endedAt: string;
+  duration: number; /** Typed error if this branch failed — siblings still ran. */
+  error?: AIError;
+}>;
+/**
+ * Forensic record of the receptionist (`ackAgent`) run. Set on
+ * `SupervisorReport.ack` only when an ack agent was configured AND the
+ * run started fresh (resumes don't re-fire ack). Mirrors
+ * `AgentBranchSnapshot` shape minus the per-iteration `intent` field —
+ * ack is not an iterating intent, it's a one-shot kickoff.
+ */
+type AckSnapshot = Readonly<{
+  input: string; /** Ack output after schema validation (if `ackAgent.output` declared). */
+  output: unknown;
+  usage: Usage;
+  startedAt: string;
+  endedAt: string;
+  duration: number;
+  /**
+   * Set when the ack agent failed. Run continues regardless — the
+   * receptionist tripping doesn't stop the specialist from doing the
+   * actual job.
+   */
+  error?: AIError;
+}>;
+/**
+ * Origin of a dispatch decision, recorded for debugging and drift
+ * analysis. `initialAgent` fires only on turn 0 when the supervisor
+ * was configured to skip the router on the first iteration.
+ */
+type DecisionSource = "route" | "router" | "initialAgent" | "classifier";
+/**
+ * Dispatch decision record — everything a reader needs to answer the
+ * question "why did this iteration run these agents?" without
+ * replaying the router agent.
+ */
+type IterationDecision = Readonly<{
+  source: DecisionSource; /** The raw routing value — string, string[], or END sentinel. */
+  next: Next;
+  /**
+   * Router agents may include a `reasoning` field alongside `next`
+   * in their output schema; when present it's preserved here.
+   */
+  reasoning?: string; /** Wall-clock time spent deciding (router call or callback). */
+  durationMs: number;
+}>;
+/**
+ * One full iteration's forensic record, written after the iteration
+ * settles (agents returned, evaluate ran, state updated). The
+ * `snapshots[]` array on `SupervisorReport` is the primary debug
+ * artifact — users debugging routing bugs ask "why did it pick X on
+ * turn 3?" and the answer is here.
+ *
+ * See design §10 for why `result` is a `Record` keyed by intent and
+ * not an array — load-bearing design call, don't normalize.
+ */
+type IterationSnapshot = Readonly<{
+  /** Zero-indexed iteration number. */iteration: number;
+  /**
+   * Per-branch dispatch records keyed by intent. Empty object only
+   * when the iteration terminated before dispatching (e.g. the very
+   * first decision returned `END`).
+   */
+  result: Record<string, AgentBranchSnapshot>;
+  decision: IterationDecision; /** Present only if `evaluate` ran this iteration. */
+  evaluateVerdict?: EvaluateResult;
+  /**
+   * Supervisor state at the end of this iteration (after every
+   * branch's strip-merge). Snapshot persistence stores this so
+   * `resume()` can rehydrate state without replaying intents.
+   *
+   * Phase 3.4 (Stage 4b) — added as part of the state model
+   * rollout.
+   */
+  state: Record<string, unknown>;
+  /**
+   * Raw `ctx.artifacts` bag captured at this iteration's merge point
+   * — BEFORE `finalizeArtifacts` (or auto-spread) reshaped it into
+   * state (Phase 8 / decisions §38). Pre-merge view; lets observers
+   * inspect what the tools contributed before any transformation.
+   *
+   * Empty `{}` when no tool wrote artifacts this iteration. Frozen
+   * (read-only). Reconstructable into a flat aggregate by consumers
+   * who want a run-level view: `snapshots.map(s => s.artifacts)`.
+   */
+  artifacts: Readonly<Record<string, unknown>>;
+  startedAt: string;
+  endedAt: string;
+  duration: number; /** Sum of router + every branch + evaluate (if evaluate is an agent). */
+  usage: Usage; /** Iteration-level fatal error, if one terminated the loop here. */
+  error?: AIError;
+}>;
+//#endregion
+export { AckSnapshot, AgentBranchSnapshot, DecisionSource, IterationDecision, IterationSnapshot };
+//# sourceMappingURL=iteration-snapshot.type.d.mts.map

package/esm/contracts/supervisor/iteration-snapshot.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iteration-snapshot.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/iteration-snapshot.type.ts"],"mappings":";;;;;;;;AAeA;;;;;;;;KAAY,mBAAA,GAAsB,QAAA;EAEhC,2DAAA,MAAA,UAIA;EAFA,KAAA,UAGO;EADP,MAAA;EACA,KAAA,EAAO,KAAA;EACP,SAAA;EACA,OAAA;EACA,QAAA,UAEe;EAAf,KAAA,GAAQ,OAAA;AAAA;;;;;;;;KAUE,WAAA,GAAc,QAAA;EACxB,KAAA,UAEA;EAAA,MAAA;EACA,KAAA,EAAO,KAAA;EACP,SAAA;EACA,OAAA;EACA,QAAA;EAMA;;;AAAe;AAQjB;EARE,KAAA,GAAQ,OAAA;AAAA;;AAQgB;AAO1B;;;KAPY,cAAA;;;;;;KAOA,iBAAA,GAAoB,QAAA;EAC9B,MAAA,EAAQ,cAAA,EAER;EAAA,IAAA,EAAM,IAAA;EAKN;;;AAEU;EAFV,SAAA,WAe2B;EAb3B,UAAA;AAAA;;;;;;;;;;;KAaU,iBAAA,GAAoB,QAAA;EAAA,qCAE9B,SAAA;EAMA;;;;;EAAA,MAAA,EAAQ,MAAA,SAAe,mBAAA;EACvB,QAAA,EAAU,iBAAA,EAWV;EATA,eAAA,GAAkB,cAAA;EAoBlB;;;;;;;;EAXA,KAAA,EAAO,MAAA;EAkBC;;AAAO;;;;;;;;EAPf,SAAA,EAAW,QAAA,CAAS,MAAA;EACpB,SAAA;EACA,OAAA;EACA,QAAA;EAEA,KAAA,EAAO,KAAA;EAEP,KAAA,GAAQ,OAAA;AAAA"}

package/esm/contracts/supervisor/next.type.d.mts

@@ -0,0 +1,25 @@
+import { EndSentinel } from "../end.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/next.type.d.ts
+/**
+ * The legal return shape of a supervisor's dispatch decision — what
+ * both `route` callbacks and router agents produce for `next`:
+ *
+ * - `string` — single agent key; supervisor dispatches that one agent.
+ * - `string[]` — fan-out; supervisor dispatches all listed keys in
+ *   parallel via `Promise.all`.
+ * - `EndSentinel` — the framework-global `END` constant; terminates.
+ *
+ * Shape decides dispatch; there is no separate "strategy" enum.
+ *
+ * @example
+ * import { END, type Next } from "@warlock.js/ai";
+ *
+ * const single: Next = "triage";
+ * const fanOut: Next = ["orderLookup", "billingLookup"];
+ * const stop:   Next = END;
+ */
+type Next = string | string[] | EndSentinel;
+//#endregion
+export { Next };
+//# sourceMappingURL=next.type.d.mts.map

package/esm/contracts/supervisor/next.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/next.type.ts"],"mappings":";;;;;AAoBA;;;;AAAkD;;;;;;;;;;;;KAAtC,IAAA,uBAA2B,WAAW"}

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

@@ -0,0 +1,91 @@
+import { Message } from "../conversation-message.type.mjs";
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
+import { SupervisorInput } from "./supervisor-input.type.mjs";
+import { EvaluateResult } from "./evaluate-context.type.mjs";
+import { ClassifierSnapshot } from "./classifier-context.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/route-context.type.d.ts
+/**
+ * Context passed to a supervisor's `route` callback (deterministic
+ * dispatch mode) and also exposed to router-agent input composers
+ * and per-agent `input` transformers.
+ *
+ * The context is read-only from the callback's perspective —
+ * mutating it is a bug; consumers that need derived state should
+ * build it in the callback body.
+ *
+ * @example
+ * route: (ctx) => {
+ *   if (ctx.iteration >= 5) { return END; }
+ *   if (ctx.state.draft && !ctx.state.critique) { return "critic"; }
+ *   return "writer";
+ * }
+ */
+type RouteContext<TState = Record<string, unknown>> = {
+  /** Zero-indexed iteration number — turn 0 is the first run. */iteration: number;
+  /**
+   * The supervisor's original `execute(input)` value. Either a raw
+   * string or a structured `Record<string, unknown>` payload — see
+   * `SupervisorInput`.
+   */
+  input: SupervisorInput;
+  /**
+   * Per-execute typed accumulator. Updated after each iteration's
+   * intents merge their outputs. Read-only from the route callback;
+   * built up by intents themselves.
+   */
+  state: TState;
+  /**
+   * Every completed iteration's snapshot, in chronological order.
+   * On turn 0 this is empty.
+   *
+   * Renamed from `history` (Q2).
+   */
+  iterations: IterationSnapshot[];
+  /**
+   * Reviewer feedback string produced by `evaluate.feedback` at the
+   * end of the previous iteration. Visible to router/route only
+   * (Q18 — feedback is router-targeted; not auto-injected into agent
+   * placeholders). Absent on turn 0 and turns where evaluate didn't
+   * return a feedback string.
+   */
+  feedback?: string;
+  /**
+   * Full previous-iteration evaluate verdict (raw). Available to
+   * route callbacks that want the full shape (e.g. inspect
+   * `reassignTo` in addition to `feedback`).
+   */
+  evaluateFeedback?: EvaluateResult;
+  /**
+   * 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;
+  /**
+   * Forensic record of iter-0 classifier run (Phase 7 / decisions §37).
+   * Present only when `SupervisorConfig.classifier` was configured
+   * AND iter 0 has completed; `undefined` for iter-0 routing
+   * decisions (classifier hasn't run yet) and for supervisors that
+   * don't use classifier mode.
+   */
+  classifier?: Readonly<ClassifierSnapshot>;
+};
+//#endregion
+export { RouteContext };
+//# sourceMappingURL=route-context.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route-context.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/route-context.type.ts"],"mappings":";;;;;;;;;AAsBA;;;;;;;;;;;;;;KAAY,YAAA,UAAsB,MAAA;EAgEX,+DA9DrB,SAAA;EAFgC;;;;;EAQhC,KAAA,EAAO,eAAA;EAaP;;;;;EAPA,KAAA,EAAO,MAAA;EA6BE;;;;;;EAtBT,UAAA,EAAY,iBAAA;EA2CC;;;AAA2B;;;;EAnCxC,QAAA;;;;;;EAMA,gBAAA,GAAmB,cAAA;;;;;;;;EAQnB,OAAA,EAAS,QAAA,CAAS,MAAA;;;;;;;EAOlB,OAAA,EAAS,aAAA,CAAc,OAAA;;;;;;EAMvB,IAAA;;;;;;;;EAQA,UAAA,GAAa,QAAA,CAAS,kBAAA;AAAA"}

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

@@ -0,0 +1,67 @@
+import { Message } from "../conversation-message.type.mjs";
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { RouteContext } from "./route-context.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/router-entry.type.d.ts
+/**
+ * Object form for `SupervisorConfig.router` — symmetric with
+ * `IntentEntry`, but a strict subset:
+ *
+ * - `agent` — the routing LLM agent. Required.
+ * - `placeholders` — values fed into the router agent's
+ *   `systemPrompt` template. Lets dev surface state-aware context
+ *   ("user is a VIP", "iteration budget remaining") into the routing
+ *   prompt without forcing it through the user-message scaffolding.
+ * - `input` — full override for the per-turn user message the router
+ *   agent receives. By default the supervisor builds a structured
+ *   message (intents list + state + feedback + original input).
+ *   Returning a string here REPLACES that scaffolding entirely —
+ *   you take responsibility for surfacing whatever the router needs
+ *   to make its decision.
+ *
+ * Deliberately omits:
+ * - `description` — the router isn't an intent, has no peer to
+ *   describe itself to.
+ * - `output` — the framework owns the canonical `{ next, reasoning }`
+ *   schema; overriding it would silently break dispatch resolution.
+ * - `next` — the router IS the dispatcher; a `next` directive on
+ *   the router itself is meaningless.
+ *
+ * Shorthand: passing a bare `AgentContract` to `router` is equivalent
+ * to `{ agent }` — same as `IntentEntry`'s shorthand on `intents`.
+ */
+type RouterEntry<TState = Record<string, unknown>> = {
+  /** The router agent — must declare an output that includes `next`. */agent: AgentContract<unknown>;
+  /**
+   * Per-turn template values fed into the router agent's
+   * `systemPrompt`. Receives the same `RouteContext` the route
+   * callback would.
+   */
+  placeholders?: (ctx: RouteContext<TState>) => Record<string, unknown>;
+  /**
+   * Replaces the supervisor's default per-turn user message.
+   * Returning a string short-circuits the built-in scaffolding —
+   * the router sees only what you produce.
+   */
+  input?: (ctx: RouteContext<TState>) => string;
+  /**
+   * Custom history slicer for the router agent. When supplied, REPLACES
+   * the default slice (full history clipped by
+   * `SupervisorConfig.historyWindow.router` if set) — return whatever
+   * subset/transformation the router should see.
+   *
+   * Precedence: `history` callback > `historyWindow.router` > full
+   * history. Return `[]` to send no history at all.
+   *
+   * @example
+   * router: {
+   *   agent: routerAgent,
+   *   // last 3 user turns only — keep router prompt small
+   *   history: (ctx) => ctx.history.filter(m => m.role === "user").slice(-3),
+   * }
+   */
+  history?: (ctx: RouteContext<TState>) => Message[] | ReadonlyArray<Message>;
+};
+//#endregion
+export { RouterEntry };
+//# sourceMappingURL=router-entry.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router-entry.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/router-entry.type.ts"],"mappings":";;;;;;;AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,WAAA,UAAqB,MAAA;EAc/B,sEAZA,KAAA,EAAO,aAAA;EAYoB;;;;;EAN3B,YAAA,IAAgB,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,MAAA;EAuBL;;;;AAAiC;EAjB1E,KAAA,IAAS,GAAA,EAAK,YAAA,CAAa,MAAA;;;;;;;;;;;;;;;;;EAiB3B,OAAA,IAAW,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,OAAA,KAAY,aAAA,CAAc,OAAA;AAAA"}

package/esm/contracts/supervisor/supervisor-config.type.d.mts

@@ -0,0 +1,356 @@
+import { Message } from "../conversation-message.type.mjs";
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { SystemPromptContract } from "../system-prompt.contract.mjs";
+import { Next } from "./next.type.mjs";
+import { EvaluateContext, EvaluateResult } from "./evaluate-context.type.mjs";
+import { RouteContext } from "./route-context.type.mjs";
+import { AckConfig } from "./ack-entry.type.mjs";
+import { SupervisorIntentValue } from "./intent-entry.type.mjs";
+import { RouterEntry } from "./router-entry.type.mjs";
+import { ClassifierConfig } from "./classifier-context.type.mjs";
+import { SupervisorEventMap } from "../events/event-map.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { CacheDriver } from "@warlock.js/cache";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/supervisor-config.type.d.ts
+/**
+ * Handler function for a single supervisor event. Receives the
+ * event's typed payload; return value is ignored.
+ */
+type SupervisorEventHandler<K extends keyof SupervisorEventMap> = (payload: SupervisorEventMap[K]) => void;
+type SupervisorEventHandlers = Partial<{ [K in keyof SupervisorEventMap]: SupervisorEventHandler<K> }>;
+/**
+ * Full factory config for `ai.supervisor(config)`.
+ *
+ * Two dispatch modes are exposed as mutually-exclusive top-level
+ * fields: `route` (deterministic callback) XOR `router` (LLM-driven
+ * agent). The factory throws `SupervisorFailedError` at author time
+ * when both or neither is present. `evaluate` pairs with both `route`
+ * and `router` (Phase 3.4 Q9 — the earlier router-only restriction
+ * was lifted).
+ *
+ * `intents` is a `Record<string, …>` — keys are intent names the
+ * router/route emits. Values are shorthand `AgentContract` /
+ * `WorkflowInstance` or the full `IntentEntry` object form. (Phase
+ * 3.3 stage 3b extends the union with callback dispatch.)
+ *
+ * `output` is a Standard Schema; when provided, supervisor validates
+ * the final value before populating `result.data`. On failure the
+ * error surfaces via `result.error` (never thrown).
+ *
+ * Phase 3.4 (Stage 4c) — `combine` removed. Fan-out branches now
+ * shallow-merge into supervisor `state` via per-intent `output`
+ * schemas (Q11/Q15). Use a callback-orchestrator intent for custom
+ * merging (max, sum, deep merge): dispatch siblings via
+ * `ctx.intents.X.execute()` and assemble the result yourself.
+ *
+ * @example
+ * const supervisor = ai.supervisor<{ response: string; refund: boolean }>({
+ *   name: "customer-support",
+ *   systemPrompt: ai.systemPrompt().persona("You coordinate a support team."),
+ *   router: routerAgent,
+ *   intents: { triage, orderLookup, billingLookup, resolver },
+ *   evaluate: (ctx) =>
+ *     ctx.state.response ? { satisfied: true } : undefined,
+ *   maxIterations: 6,
+ *   output: v.object({ response: v.string(), refund: v.boolean() }),
+ *   snapshotStore: cache.driver("redis", { client }),
+ * });
+ */
+type SupervisorConfig<TOutput = unknown, TState = TOutput, TIntents extends Record<string, SupervisorIntentValue> = Record<string, SupervisorIntentValue>, TArtifacts = Record<string, unknown>> = {
+  /** Stable identifier — used in logs, events, snapshots, signature. */name: string;
+  /**
+   * Dev-curated version string mirrored onto every report node this
+   * supervisor produces. Free-form — semver, date, hash. Bump when
+   * routing logic, intent set, or evaluate criteria change in a way
+   * worth distinguishing in trip archives. The framework neither
+   * parses nor compares it; signature drift detection remains
+   * independent.
+   */
+  version?: string;
+  /**
+   * Prepended to the router agent's own system prompt (router mode
+   * only). Does not touch child agents' system prompts — they stay
+   * independent, reusable units.
+   */
+  systemPrompt?: SystemPromptContract | string;
+  /**
+   * Natural-language statement of what "done" looks like for this
+   * supervisor — the high-level objective every iteration is
+   * working toward. First-class concept rather than buried in
+   * `systemPrompt` so:
+   *
+   * - The router agent's per-turn user message includes it explicitly,
+   *   so routing decisions are objective-aware without manual prompt
+   *   stuffing.
+   * - `route` / `evaluate` / dispatch callbacks receive it on
+   *   `ctx.goal` (read-only) for state-driven satisfaction checks
+   *   without hardcoded strings.
+   * - Dispatched agents can reference it via the `{{goal}}`
+   *   placeholder on their own systemPrompt templates without the
+   *   supervisor wiring it through `entry.placeholders` manually.
+   *
+   * Accepts a plain `string` or a `SystemPromptContract` (for
+   * placeholder-rendered goals); resolved to text at construction.
+   *
+   * NOT persisted in snapshots — re-resolved from the config on
+   * `resume()`.
+   *
+   * @example
+   * ai.supervisor({
+   *   name: "ac-recommender",
+   *   goal: "Recommend an AC unit. Must include BTU calculation, " +
+   *         "matching catalog product, and city-specific install notes.",
+   *   router: routerAgent,
+   *   intents: { ... },
+   *   evaluate: (ctx) => {
+   *     if (ctx.state.recommendation && ctx.state.btu && ctx.state.installNotes) {
+   *       return { satisfied: true };
+   *     }
+   *     return undefined;
+   *   },
+   * });
+   */
+  goal?: string | SystemPromptContract;
+  /**
+   * Factory-level default conversation history — the prior turns the
+   * supervisor (router + every dispatched agent + ack) sees on each
+   * `execute()` call when the caller does NOT supply per-call history.
+   *
+   * **Precedence:** `execute(input, { history })` (per-call) overrides
+   * this entirely when supplied. When neither is set, history is `[]`.
+   *
+   * Use this for "background" priming messages every run should see —
+   * onboarding context, persona warm-up, baseline tenant info. For
+   * actual chat-driver scenarios where each turn carries fresh prior
+   * turns, pass `history` per-call via `execute()` instead.
+   *
+   * Subject to the same `historyWindow` slicing + per-entry `history`
+   * callbacks as per-call history once resolved.
+   *
+   * NOT persisted in snapshots — `resume()` re-resolves it from the
+   * config (or per-call `history` on the resume options).
+   */
+  history?: Message[];
+  /**
+   * LLM-driven dispatch. Accepts either a bare `AgentContract`
+   * (shorthand) or a `RouterEntry` object — `{ agent, placeholders?,
+   * input? }` — symmetric with `IntentEntry`. The framework injects
+   * the canonical `{ next, reasoning }` output schema; do not declare
+   * a custom `output` for the router agent. Mutually exclusive with
+   * `route`.
+   */
+  router?: AgentContract<unknown> | RouterEntry<TState>;
+  /**
+   * Deterministic dispatch. Runs once per iteration to pick the next
+   * intent(s) or terminate. Mutually exclusive with `router`.
+   */
+  route?: (ctx: RouteContext<TState>) => Next | Promise<Next>;
+  /**
+   * Dispatchable units keyed by intent name. Shorthand accepts any
+   * `AgentContract` or `WorkflowInstance`; full form is `IntentEntry`
+   * with optional overrides for `description`, `input`, `output`.
+   * Callback dispatch (`run` shorthand / `IntentRunEntry`) is wired
+   * into the union in Phase 3.3.
+   *
+   * Typed as the literal `TIntents` shape so `ctx.intents.<TAB>`
+   * autocompletes against the actual keys the user supplied (Q6).
+   */
+  intents: TIntents;
+  /**
+   * Retrospective verdict callback. Fires after the iteration's
+   * intents settle and their outputs have merged into state — never
+   * before dispatch. Pairs with both `router` AND `route` modes
+   * (Phase 3.4 Q9 — restriction lifted; state-driven termination is
+   * useful in either dispatch mode).
+   *
+   * Receives `ctx.state` (post-merge) so verdicts can be state-aware.
+   */
+  evaluate?: (ctx: EvaluateContext<TState>) => EvaluateResult | Promise<EvaluateResult>;
+  /**
+   * Initial seed for the per-execute state accumulator. Defaults to
+   * `{}`. Each intent contributes a slice via shallow-merge across
+   * iterations; the final shape is validated against `output` at
+   * termination.
+   *
+   * `TState` defaults to `TOutput` — for the common case where state
+   * IS the output shape, you only declare the schema once. Override
+   * `TState` (second generic) when the working accumulator carries
+   * intermediate fields that don't survive validation.
+   *
+   * Must be JSON-serializable (Q16) — no functions / Maps / Sets /
+   * class instances. Snapshot resume rehydrates `state` from the
+   * last persisted iteration.
+   */
+  state?: TState;
+  /**
+   * Hard cap on iteration count. Hitting the cap terminates the run
+   * with `MaxIterationsError` on `result.error`. Default: `10`.
+   */
+  maxIterations?: number;
+  /**
+   * When set, turn 0 dispatches this intent directly and skips the
+   * first router/route call. Must be a key in `intents`.
+   */
+  initialAgent?: string;
+  /**
+   * Final-state schema. On clean termination the supervisor's
+   * accumulated `state` is validated against this; success populates
+   * `result.data`, failure surfaces `SchemaValidationError` on
+   * `result.error`.
+   *
+   * Phase 3.4 (Stage 4b) — semantics shifted from "validates the
+   * terminal iteration's value" to "validates the accumulated
+   * state." Same field name; broader role.
+   */
+  output?: StandardSchemaV1<TOutput>;
+  /**
+   * Optional durable store enabling `supervisor.resume(runId)`.
+   * Snapshots are written after every iteration settles plus once
+   * more at final completion / cancel / fail. Accepts any
+   * `@warlock.js/cache` driver — `MemoryCacheDriver` for dev/tests,
+   * `RedisCacheDriver` / `PgCacheDriver` for production.
+   *
+   * Falls back to `ai.config({ defaultStore })` when omitted. When
+   * neither is set, `resume()` throws and snapshot writes silently
+   * skip (current behavior preserved).
+   */
+  snapshotStore?: CacheDriver<any, any>;
+  /**
+   * Definition-level event handlers — tier 1 of the 3-tier model.
+   * Fire on every run of this supervisor, before instance and
+   * per-call handlers.
+   */
+  on?: SupervisorEventHandlers;
+  /**
+   * Optional receptionist — fires in parallel with phase A on
+   * iteration 0 only. Streams a brief acknowledgment to the user the
+   * moment its first token lands so the UI doesn't show a blank
+   * screen while a slow router or specialist works.
+   *
+   * Three accepted shapes (order of conciseness):
+   * - `AckEntry` — `{ agent, placeholders?, input?, output? }` (LLM)
+   * - `AckRunEntry` — `{ run, output? }` (pure-code callback)
+   * - `AckCallback` — bare `(ctx) => slice` (shorthand)
+   *
+   * Loses gracefully — if ack hasn't settled by the time the run is
+   * otherwise ready to finalize, the slice drops with a warning log
+   * and the run completes regardless. See `AckConfig` for full
+   * runtime semantics.
+   */
+  ack?: AckConfig<TState>;
+  /**
+   * One-shot iter-0 prelude that classifies the input and dispatches
+   * the chosen intent (Phase 7 / decisions §37). Composes with
+   * `router` / `route` — when both are configured, classifier drives
+   * iter 0 and router/route picks up at iter 1+. When classifier is
+   * configured alone (no router, no route), the supervisor terminates
+   * after iter 0's branch settles.
+   *
+   * Accepts the same value-shape union as `intents` and `router`:
+   * bare `AgentContract` shorthand, bare callback shorthand, or full
+   * object form (`{ agent, placeholders?, input?, history?, refine? }`
+   * or `{ run, refine? }`).
+   *
+   * Output schema is locked at the framework level —
+   * `{ intent, reasoning?, confidence? }`. Devs may extend with
+   * additional fields by declaring a richer typed schema on their
+   * classifier agent; the extra fields strip-merge into supervisor
+   * state per the supervisor's `output` schema.
+   *
+   * **Mutually exclusive with `initialAgent`** — both answer "what
+   * runs first?" and coexistence is meaningless. Factory throws
+   * `SupervisorFailedError` when both are set.
+   *
+   * @example
+   * classifier: {
+   *   agent: classifyAgent,
+   *   refine: async ctx => {
+   *     // Override on weak-confidence signal:
+   *     if ((ctx.result.data.confidence ?? 1) < 0.7) {
+   *       return { intent: "fallback" };
+   *     }
+   *     // Halt on policy violation:
+   *     if (isToxic(ctx.input)) {
+   *       return END;
+   *     }
+   *   },
+   * }
+   */
+  classifier?: ClassifierConfig<TState>;
+  /**
+   * Global default windows applied to the prior conversation history
+   * supplied via `execute(input, { history })` — keeps the **last N**
+   * messages (most recent, chronological) per role.
+   *
+   * - `router` — slice for the routing LLM. Recommended small (3–5)
+   *   since the router only needs recent intent signal. Default:
+   *   unbounded.
+   * - `agents` — slice for every dispatched agent/workflow. Default:
+   *   unbounded.
+   * - `ack` — slice for the receptionist. Default: `0` — receptionists
+   *   are template-y and rarely need scroll-back; full history wastes
+   *   tokens on a path explicitly chosen for speed. Override per-call
+   *   via the entry `history` callback when needed.
+   *
+   * Precedence (per role): entry-level `history` callback >
+   * `historyWindow.<role>` > full history (or empty for ack).
+   *
+   * @example
+   * historyWindow: { router: 5, agents: 10 }
+   */
+  historyWindow?: {
+    router?: number;
+    agents?: number;
+    ack?: number;
+  };
+  /**
+   * Schema for the artifacts bag tools may write into via
+   * `ctx.artifacts` (Phase 5 / decisions §35). Declared once on the
+   * supervisor; threaded into every tool registered to the
+   * supervisor's agents so `ctx.artifacts.*` autocompletes against
+   * `TArtifacts`.
+   *
+   * The bag starts empty at every iteration boundary, accumulates
+   * across all tool calls in that iteration, validates against this
+   * schema (when set), then merges into supervisor `state` via
+   * `finalizeArtifacts` if supplied — otherwise via auto-spread.
+   *
+   * Validation failure aborts the run with
+   * `SchemaValidationError` carrying the offending iteration on
+   * `result.error`.
+   *
+   * @example
+   * artifactsSchema: v.object({
+   *   blocks: v.array(blockSchema).optional(),
+   *   citations: v.array(citationSchema).optional(),
+   * }),
+   */
+  artifactsSchema?: StandardSchemaV1<TArtifacts>;
+  /**
+   * Per-iteration merger for the artifacts bag (Phase 5 /
+   * decisions §35). When omitted the framework auto-spreads:
+   * `state = { ...state, ...artifacts }`. Replace semantics —
+   * artifact values overwrite same-keyed state values.
+   *
+   * Supply this callback for concat / dedupe / transform / cross-
+   * iteration accumulation. Typical pattern: blocks should
+   * accumulate across iterations rather than replace, so the
+   * callback concatenates `state.blocks ?? []` with
+   * `artifacts.blocks ?? []`.
+   *
+   * Called once per iteration with the post-branch-merge state and
+   * the iteration's accumulated artifacts. The bag resets to `{}`
+   * for the next iteration regardless of what the callback does.
+   *
+   * @example
+   * finalizeArtifacts: (state, artifacts) => ({
+   *   ...state,
+   *   blocks: [...(state.blocks ?? []), ...(artifacts.blocks ?? [])],
+   * }),
+   */
+  finalizeArtifacts?: (state: TState, artifacts: TArtifacts) => TState;
+};
+//#endregion
+export { SupervisorConfig, SupervisorEventHandler, SupervisorEventHandlers };
+//# sourceMappingURL=supervisor-config.type.d.mts.map

package/esm/contracts/supervisor/supervisor-config.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;AAkBA;;KAAY,sBAAA,iBAAuC,kBAAA,KACjD,OAAA,EAAS,kBAAA,CAAmB,CAAA;AAAA,KAGlB,uBAAA,GAA0B,OAAA,eACxB,kBAAA,GAAqB,sBAAA,CAAuB,CAAA;;;;;;;;;AAJ1B;AAGhC;;;;;;;;;;;;;;;AAC2D;AAyC3D;;;;;;;;;;;;;KAAY,gBAAA,6BAED,OAAA,mBACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAAe,qBAAA,gBAC3D,MAAA;EA0FqB,sEAvFlC,IAAA;EA6Fc;;;;;;;;EAnFd,OAAA;EA0G8D;;;;;EAnG9D,YAAA,GAAe,oBAAA;EAkLC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA3IhB,IAAA,YAAgB,oBAAA;EAqC8B;;;;;;;;;;;;;;;;;;;EAhB9C,OAAA,GAAU,OAAA;EAoGV;;;;;;;;EA1FA,MAAA,GAAS,aAAA,YAAyB,WAAA,CAAY,MAAA;EA2K5C;;;;EArKF,KAAA,IAAS,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,IAAA,GAAO,OAAA,CAAQ,IAAA;EAgMnB;;;;;;;;AAwBiC;;EA5MpE,OAAA,EAAS,QAAA;;;;;;;;;;EAWT,QAAA,IAAY,GAAA,EAAK,eAAA,CAAgB,MAAA,MAAY,cAAA,GAAiB,OAAA,CAAQ,cAAA;;;;;;;;;;;;;;;;EAiBtE,KAAA,GAAQ,MAAA;;;;;EAMR,aAAA;;;;;EAMA,YAAA;;;;;;;;;;;EAYA,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;;;;;;;EAa1B,aAAA,GAAgB,WAAA;;;;;;EAOhB,EAAA,GAAK,uBAAA;;;;;;;;;;;;;;;;;EAkBL,GAAA,GAAM,SAAA,CAAU,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwChB,UAAA,GAAa,gBAAA,CAAiB,MAAA;;;;;;;;;;;;;;;;;;;;;;EAsB9B,aAAA;IACE,MAAA;IACA,MAAA;IACA,GAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;EAyBF,eAAA,GAAkB,gBAAA,CAAiB,UAAA;;;;;;;;;;;;;;;;;;;;;;;EAwBnC,iBAAA,IAAqB,KAAA,EAAO,MAAA,EAAQ,SAAA,EAAW,UAAA,KAAe,MAAA;AAAA"}