@warlock.js/ai 4.1.1

package/esm/contracts/sdk-adapter.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-adapter.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/sdk-adapter.contract.ts"],"mappings":";;;;;;;AAkBA;;;;;;;;;;;AAiBc;KAjBF,WAAA;EAkCuB,qEAhCjC,IAAA,UAqCc;EAnCd,WAAA,WA6CqC;EA3CrC,SAAA;EAsDmC;;;;;;;;EA7CnC,OAAA,GAAU,YAAY,EAkCF;EAAA,CAhCnB,GAAA;AAAA;;;;;AA2CkD;;;;;;;;;;UA1BpC,kBAAA;;;;;EAKf,KAAA,CAAM,MAAA,EAAQ,WAAA,GAAc,aAAA;;;;;;;;;EAU5B,KAAA,CAAM,IAAA,UAAc,KAAA,YAAiB,OAAA;;;;;;;;;;EAWrC,QAAA,EAAU,MAAA,EAAQ,cAAA,GAAiB,gBAAA;AAAA"}

package/esm/contracts/stream/stream-event.type.d.mts

@@ -0,0 +1,68 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { ToolCall } from "../result/tool-call.type.mjs";
+import { LLMTrip } from "../result/llm-trip.type.mjs";
+import { ToolEventMeta } from "../events/agent-events.type.mjs";
+import { EventIdentity } from "../events/event-identity.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/stream/stream-event.type.d.ts
+/**
+ * Discriminated union of all events emitted during a streaming execution.
+ * Iterate over a StreamContract to receive these events.
+ *
+ * Event `type` strings use the same dot-notation as `AgentEventMap` keys
+ * so filtering logic in subscribers reads the same whether they came
+ * through `.on(...)` or the async iterator.
+ *
+ * Every variant also carries `EventIdentity` (`runId` / `rootRunId`)
+ * via the `StreamEvent` intersection, so stream consumers can
+ * correlate to a run the same way `.on(...)` subscribers do.
+ *
+ * @example
+ * for await (const event of stream) {
+ *   if (event.type === "agent.trip.streaming") process.stdout.write(event.delta);
+ *   else if (event.type === "agent.tool.called") console.log("Tool:", event.toolCall.name);
+ *   else if (event.type === "agent.trip.completed") console.log("Trip done");
+ * }
+ */
+type StreamEventBody = {
+  type: "agent.starting";
+  input: string;
+} | {
+  type: "agent.trip.started";
+  tripIndex: number;
+  input: string;
+} | {
+  type: "agent.trip.streaming";
+  delta: string;
+  tripIndex: number;
+} | {
+  type: "agent.tool.calling";
+  tool: ToolEventMeta;
+  input: unknown;
+  tripIndex: number;
+} | {
+  type: "agent.tool.called";
+  toolCall: ToolCall;
+  tool: ToolEventMeta;
+} | {
+  type: "agent.tool.failed";
+  tool: ToolEventMeta;
+  error: AIError;
+  tripIndex: number;
+} | {
+  type: "agent.trip.completed";
+  trip: LLMTrip;
+} | {
+  type: "agent.completed";
+} | {
+  type: "agent.error";
+  error: AIError;
+};
+/**
+ * A `StreamEventBody` variant enriched with run identity. This is what
+ * `agent.stream()` consumers actually receive on each iteration.
+ */
+type StreamEvent = EventIdentity & StreamEventBody;
+//#endregion
+export { StreamEvent, StreamEventBody };
+//# sourceMappingURL=stream-event.type.d.mts.map

package/esm/contracts/stream/stream-event.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-event.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/stream/stream-event.type.ts"],"mappings":";;;;;;;;;AAyBA;;;;;;;;;;;;;;;;;KAAY,eAAA;EACN,IAAA;EAAwB,KAAA;AAAA;EACxB,IAAA;EAA4B,SAAA;EAAmB,KAAA;AAAA;EAC/C,IAAA;EAA8B,KAAA;EAAe,SAAA;AAAA;EAE7C,IAAA;EACA,IAAA,EAAM,aAAA;EACN,KAAA;EACA,SAAA;AAAA;EAEA,IAAA;EAA2B,QAAA,EAAU,QAAA;EAAU,IAAA,EAAM,aAAA;AAAA;EAErD,IAAA;EACA,IAAA,EAAM,aAAA;EACN,KAAA,EAAO,OAAA;EACP,SAAA;AAAA;EAEA,IAAA;EAA8B,IAAA,EAAM,OAAA;AAAA;EACpC,IAAA;AAAA;EACA,IAAA;EAAqB,KAAA,EAAO,OAAA;AAAA;;;;;KAMtB,WAAA,GAAc,aAAA,GAAgB,eAAe"}

package/esm/contracts/stream/stream.contract.d.mts

@@ -0,0 +1,61 @@
+import { StreamEvent } from "./stream-event.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/stream/stream.contract.d.ts
+/**
+ * An async iterable stream that also exposes a result promise.
+ * Returned by every primitive's `stream()` method.
+ *
+ * Parameterized by **`TResult`** (the value `result` resolves to —
+ * `AgentResult`, `WorkflowResult`, `SupervisorResult`, etc.) and
+ * **`TEvent`** (the discriminated union iterated over). `TEvent`
+ * defaults to the agent's `StreamEvent` so existing agent consumers
+ * keep working unchanged; primitives whose event surface differs
+ * (e.g. `SupervisorStreamEvent` in `supervisor.stream()`) parameterize
+ * the second slot to surface their own events to consumers.
+ *
+ * @example
+ * // Agent stream — TEvent defaults to StreamEvent
+ * const stream = agent.stream("Explain quantum computing");
+ * for await (const event of stream) {
+ *   if (event.type === "agent.trip.streaming") process.stdout.write(event.delta);
+ * }
+ *
+ * @example
+ * // Supervisor stream — TEvent narrowed to SupervisorStreamEvent
+ * const stream = supportBot.stream(message);
+ * for await (const event of stream) {
+ *   if (event.type === "supervisor.agent.streaming") process.stdout.write(event.delta);
+ * }
+ *
+ * @example
+ * // Or await just the final result
+ * const result = await stream.result;
+ * console.log(result.usage.total, "tokens used");
+ *
+ * @example
+ * // Attach named handlers instead of iterating
+ * const stream = agent.stream("Write a poem");
+ * stream
+ *   .on({ "agent.trip.streaming": ({ delta }) => process.stdout.write(delta) })
+ *   .on({ "agent.completed": () => console.log("Done!") });
+ * const result = await stream.result;
+ */
+interface StreamContract<TResult, TEvent extends {
+  type: string;
+} = StreamEvent> extends AsyncIterable<TEvent> {
+  /**
+   * Promise that resolves to the full execution result once streaming completes.
+   * Rejects if the execution fails.
+   */
+  result: Promise<TResult>;
+  /**
+   * Attach event handlers by event type. Returns `this` for chaining.
+   * Handlers registered here fire in addition to iteration.
+   */
+  on(handlers: Partial<{ [K in TEvent["type"]]: (event: Extract<TEvent, {
+    type: K;
+  }>) => void }>): this;
+}
+//#endregion
+export { StreamContract };
+//# sourceMappingURL=stream.contract.d.mts.map

package/esm/contracts/stream/stream.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/stream/stream.contract.ts"],"mappings":";;;;;AAyCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBM;;UAjBW,cAAA;EAEE,IAAA;AAAA,IAAiB,WAAA,UAC1B,aAAA,CAAc,MAAA;;;;;EAKtB,MAAA,EAAQ,OAAA,CAAQ,OAAA;;;;;EAMhB,EAAA,CACE,QAAA,EAAU,OAAA,SACF,MAAA,YAAkB,KAAA,EAAO,OAAA,CAAQ,MAAA;IAAU,IAAA,EAAM,CAAA;EAAA;AAAA"}

package/esm/contracts/streaming-tool-guard-config.type.d.mts

@@ -0,0 +1,78 @@
+//#region ../../@warlock.js/ai/src/contracts/streaming-tool-guard-config.type.d.ts
+/**
+ * Configuration for the stream-time tool-call guard.
+ *
+ * **What the guard does.** Cheap/fast models occasionally emit the
+ * structured input for a registered tool as **literal text in the
+ * content stream** instead of as a structured tool-call. Without
+ * intervention, the customer watches raw JSON build up
+ * character-by-character on screen — every `delta` already shipped
+ * over the wire before anyone can react. The guard sits at the
+ * delta-processing seam inside the agent loop, scans incoming text
+ * for a JSON envelope that matches a registered tool's name + schema,
+ * and — when matched — synthesizes a real tool call while dropping
+ * the leaked JSON from visible text.
+ *
+ * **Opt-in by design.** Absent = off (faithful relay, no mutation).
+ * Empty object `{}` = on with defaults. Mutating the stream behind a
+ * developer's back violates least surprise — set this explicitly when
+ * the agent has tools that the model has been observed to leak.
+ *
+ * **What survives the guard.**
+ * - Legitimate prose streams verbatim; the guard only engages when a
+ *   `{` or ```` ```json ```` opener appears in the text channel.
+ * - A buffered JSON blob that does NOT match the named-envelope
+ *   pattern (envelope `{ name|tool, arguments|input }` whose tool is
+ *   registered AND whose args validate against the tool's schema) is
+ *   flushed back to the consumer as text — the developer's "give me
+ *   a JSON config" prompt is preserved.
+ *
+ * **Limitations.**
+ * - Named envelope only. Bare-object matching is unsafe while tool
+ *   input schemas can be permissive (a `v.record(v.any())` matches
+ *   any object); future tier, not in v1.
+ * - Recovery introduces a delay equal to "time to emit the suspect
+ *   JSON" — the customer sees prose up to the `{`, then waits while
+ *   the buffer fills, then either sees nothing (recovered) or the
+ *   JSON in one shot (flushed). Negligible in normal chat; visible
+ *   only when the agent's primary output IS a JSON blob the user
+ *   asked for.
+ *
+ * @example
+ * // Always on for this agent, defaults
+ * const talker = agent({
+ *   model,
+ *   tools: [suggestFollowupsTool],
+ *   streamingToolGuard: {},
+ * });
+ *
+ * @example
+ * // Per-call override — disable for a one-off JSON-extraction call
+ * await agent.execute(input, {
+ *   streamingToolGuard: undefined,
+ * });
+ *
+ * @example
+ * // Tighter buffer cap for cost-sensitive deployments
+ * const talker = agent({
+ *   model,
+ *   tools,
+ *   streamingToolGuard: { maxBufferBytes: 2048 },
+ * });
+ */
+type StreamingToolGuardConfig = {
+  /**
+   * Hard cap on the bytes the guard will accumulate before deciding
+   * a suspect buffer is not envelope-shaped after all. When the cap
+   * is hit, the buffer flushes to the consumer as text and the guard
+   * resets to pass-through.
+   *
+   * Defaults to `4096`. Real envelope payloads observed in production
+   * leaks have been under 1 KB; the cap is a safety valve against an
+   * adversarial / runaway buffer growing without bound.
+   */
+  maxBufferBytes?: number;
+};
+//#endregion
+export { StreamingToolGuardConfig };
+//# sourceMappingURL=streaming-tool-guard-config.type.d.mts.map

package/esm/contracts/streaming-tool-guard-config.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-tool-guard-config.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/streaming-tool-guard-config.type.ts"],"mappings":";;AA6DA;;;;AAWgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAXJ,wBAAA;;;;;;;;;;;EAWV,cAAc;AAAA"}

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

@@ -0,0 +1,97 @@
+import { Message } from "../conversation-message.type.mjs";
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { RouteContext } from "./route-context.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/ack-entry.type.d.ts
+/**
+ * Receptionist callback — pure code that produces an acknowledgment
+ * slice. Bare-callback shorthand for `AckRunEntry`. Use when the ack
+ * doesn't need an LLM at all (templated greetings, deterministic
+ * hedges based on `ctx.input` keywords, etc.).
+ */
+type AckCallback<TState = Record<string, unknown>> = (ctx: RouteContext<TState>) => unknown | Promise<unknown>;
+/**
+ * Receptionist entry — LLM-driven form. Symmetric with `IntentEntry`,
+ * gated to ack-relevant fields:
+ *
+ * - `agent` — the receptionist agent. Typically a small/fast model
+ *   on a separate provider so its first-token latency genuinely
+ *   undercuts the slow path.
+ * - `placeholders` — values fed into the agent's `systemPrompt` template.
+ * - `input` — overrides what the agent receives as its user message.
+ * - `output` — Standard Schema; strip-validates the slice before merge.
+ */
+type AckEntry<TState = Record<string, unknown>> = {
+  agent: AgentContract<unknown>;
+  placeholders?: (ctx: RouteContext<TState>) => Record<string, unknown>;
+  input?: (ctx: RouteContext<TState>) => string;
+  output?: StandardSchemaV1<unknown>;
+  /**
+   * Custom history slicer for the ack agent. When supplied, REPLACES
+   * the default (which is empty — `historyWindow.ack` defaults to `0`,
+   * since receptionists rarely need scroll-back). Override this when
+   * the ack genuinely needs a turn or two of context.
+   *
+   * Precedence: entry `history` callback > `historyWindow.ack` >
+   * empty.
+   *
+   * @example
+   * ack: {
+   *   agent: ackAgent,
+   *   history: (ctx) => ctx.history.slice(-2),
+   * }
+   */
+  history?: (ctx: RouteContext<TState>) => Message[] | ReadonlyArray<Message>;
+};
+/**
+ * Receptionist entry — callback form. Same shape as `AckEntry` but
+ * with `run` instead of `agent` — pure code, no LLM call. Mirrors
+ * the `IntentRunEntry` / `IntentEntry` split on the intents map.
+ */
+type AckRunEntry<TState = Record<string, unknown>> = {
+  run: AckCallback<TState>;
+  output?: StandardSchemaV1<unknown>;
+};
+/**
+ * Union of accepted shapes for the supervisor's `ack` config field.
+ * Three forms in order of conciseness:
+ *
+ * 1. **`AckEntry`** — `{ agent, placeholders?, input?, output? }`.
+ *    LLM-driven receptionist (e.g. one that classifies the request
+ *    and weaves the category into the ack: "Looking into your *shipping*
+ *    question now"). Use a meaningfully faster model + provider than
+ *    the slow path the ack is masking — same model = same queue,
+ *    no win.
+ *
+ * 2. **`AckRunEntry`** — `{ run, output? }`. Pure-code callback that
+ *    returns the slice. Use for templated/deterministic acks that
+ *    don't need an LLM.
+ *
+ * 3. **`AckCallback`** — bare `(ctx) => slice`. Shorthand for the
+ *    pure-code form when no schema is declared.
+ *
+ * **Receptionist mental model.** Whatever form, the ack acknowledges
+ * receipt and indicates direction; it does NOT make decisions or
+ * promise outcomes. The downstream specialists own the actual answer.
+ *
+ * **Runtime semantics:**
+ * - Fires only when `iteration === 0 && !resumeFrom`. Resumes don't
+ *   re-emit (the user already saw the original ack).
+ * - Runs concurrently with phase A (router/route decision).
+ * - Tokens stream via `supervisor.ack.streaming` (LLM form only —
+ *   pure-code acks settle synchronously and emit just `.completed`).
+ * - Output strip-merges into `state` BEFORE dispatched branches —
+ *   specialist outputs override the receptionist on key collision.
+ * - Loses gracefully — if ack hasn't settled by the time the
+ *   iteration is otherwise ready to finalize, the slice drops with
+ *   a warning log; the run completes regardless. Schema's
+ *   `.optional()` covers it. Non-blocking by design.
+ * - Failure surfaces on `report.ack.error` but never aborts the run.
+ * - Usage rolls up into the supervisor's total; the ack agent's full
+ *   report node lives in `result.report.children[]`.
+ */
+type AckConfig<TState = Record<string, unknown>> = AckEntry<TState> | AckRunEntry<TState> | AckCallback<TState>;
+//#endregion
+export { AckCallback, AckConfig, AckEntry, AckRunEntry };
+//# sourceMappingURL=ack-entry.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ack-entry.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/ack-entry.type.ts"],"mappings":";;;;;;;;AAWA;;;;KAAY,WAAA,UAAqB,MAAA,sBAC/B,GAAA,EAAK,YAAA,CAAa,MAAA,gBACL,OAAA;;;;;;;;;;;;KAaH,QAAA,UAAkB,MAAA;EAC5B,KAAA,EAAO,aAAA;EACP,YAAA,IAAgB,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,MAAA;EAC9C,KAAA,IAAS,GAAA,EAAK,YAAA,CAAa,MAAA;EAC3B,MAAA,GAAS,gBAAA;EAHF;;;;;;;;;;;;;;;EAmBP,OAAA,IAAW,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,OAAA,KAAY,aAAA,CAAc,OAAA;AAAA;;;;;;KAQzD,WAAA,UAAqB,MAAA;EAC/B,GAAA,EAAK,WAAA,CAAY,MAAA;EACjB,MAAA,GAAS,gBAAA;AAAA;;;;;;;;;;;;AAViE;AAQ5E;;;;;;;;;;;;;;;;;AAE2B;AAyC3B;;;;;;;;KAAY,SAAA,UAAmB,MAAA,qBAC3B,QAAA,CAAS,MAAA,IACT,WAAA,CAAY,MAAA,IACZ,WAAA,CAAY,MAAA"}

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

@@ -0,0 +1,189 @@
+import { Message } from "../conversation-message.type.mjs";
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "../result/usage.type.mjs";
+import { StreamContract } from "../stream/stream.contract.mjs";
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { EndSentinel } from "../end.type.mjs";
+import { SupervisorInput } from "./supervisor-input.type.mjs";
+import { StreamableExecutable, SupervisableExecutable, SupervisableExecuteOptions, SupervisableResult } from "./dispatch-context.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/supervisor/classifier-context.type.d.ts
+/**
+ * Locked output shape every classifier must produce — agent or callback
+ * form. `intent` is required and must match a key in the supervisor's
+ * `intents` map; `reasoning` and `confidence` are optional universal
+ * telemetry fields.
+ *
+ * Devs may extend this with arbitrary additional fields by declaring
+ * a richer output schema on their classifier agent — those fields
+ * strip-merge into supervisor state per the supervisor's `output`
+ * schema. The framework only reserves the three fields below.
+ *
+ * **Confidence caveat.** LLM-reported `confidence` values are
+ * notoriously poorly calibrated — a model that says `0.95` is wrong
+ * roughly as often as one that says `0.85`. Use it as a soft signal
+ * (alongside reasoning inspection, prior state, deterministic checks)
+ * rather than as a hard threshold for control flow.
+ *
+ * @example
+ * // Output schema for a customer-support classifier:
+ * v.object({
+ *   intent: v.enum(["billing", "shipping", "smalltalk"]),
+ *   reasoning: v.string().optional(),
+ *   confidence: v.number().optional(),
+ *   // Domain-specific extension — strip-merges into state alongside.
+ *   language: v.string().optional(),
+ * })
+ */
+type ClassifierOutput = {
+  /** Required — must match a key in the supervisor's `intents` map. */intent: string; /** Optional reasoning trail — telemetry / refine signal. */
+  reasoning?: string;
+  /**
+   * Optional self-reported confidence (0–1). See "Confidence caveat"
+   * above — LLM-reported values are not well calibrated.
+   */
+  confidence?: number;
+};
+/**
+ * Result of a `classifier.refine` callback (Phase 7 / decisions §37).
+ * Lets the dev intercept the classifier's output and either (a) accept
+ * it as-is, (b) override the dispatched intent, (c) merge additional
+ * state, or (d) halt the run before any dispatch.
+ *
+ * - `undefined` → use classifier output unchanged.
+ * - `END` (bare sentinel) → terminate the run; no dispatch, no slice
+ *   merged from refine. The run completes with
+ *   `terminatedBy: "classifier"`.
+ * - `{ intent: "name", ...slice }` → override intent + shallow-merge
+ *   slice into state. `intent` must match a registered intents key
+ *   or runtime throws `SUPERVISOR_INVALID_ROUTE`.
+ * - `{ intent: END, ...slice }` → terminate AFTER merging slice into
+ *   state. Useful for "halt with reason" patterns where the dev
+ *   wants the rejection reason to surface in `result.data`.
+ * - `{ ...slice }` (no `intent` key) → keep classifier's intent;
+ *   shallow-merge slice into state.
+ */
+type ClassifierRefineResult = undefined | EndSentinel | (Record<string, unknown> & {
+  intent?: string | EndSentinel;
+});
+/**
+ * Read-only context passed to a classifier callback or to a
+ * classifier agent's per-call resolvers (`placeholders`, `input`,
+ * `history`). Phase 7 / decisions §37.
+ *
+ * Mirrors `RouteContext` for the iter-0 prelude with one critical
+ * exclusion: dispatch helpers (`intents.X.execute()` / `run` /
+ * `stream`) are NOT exposed at classifier time — registered intents
+ * have not dispatched yet; pre-running them from the classifier
+ * would be confusing. The refine hook gets `run` / `stream` so the
+ * "secondary classifier" pattern works (call another agent inline
+ * to validate or override the primary classification).
+ */
+type ClassifierContext<TState = Record<string, unknown>> = {
+  /** Always `0` — classifier runs as the iter-0 prelude. */iteration: 0; /** The supervisor's original `execute(input)` value. */
+  input: SupervisorInput; /** Empty `{}` at classifier time — no intent has dispatched yet. */
+  state: TState; /** Read-only request-scoped bag from `execute(input, { context })`. */
+  context: Readonly<Record<string, unknown>>; /** Prior conversation messages from `execute(input, { history })`. */
+  history: ReadonlyArray<Message>; /** Cancellation signal — propagated from the `execute()` caller. */
+  signal: AbortSignal; /** Resolved natural-language objective from `SupervisorConfig.goal`. */
+  goal?: string;
+};
+/**
+ * Context passed to `classifier.refine`. Same surface as
+ * {@link ClassifierContext} plus the just-resolved classifier output
+ * on `result.data`, plus `run` / `stream` (Phase 6 inline supervised
+ * execution) so refine can spin up a secondary classifier or
+ * validator without leaving the supervised flow.
+ */
+type ClassifierRefineContext<TState = Record<string, unknown>> = ClassifierContext<TState> & {
+  /** The classifier's just-resolved output, ready to refine. */result: {
+    data: ClassifierOutput;
+  }; /** Inline execute under supervision — see Phase 6 / decisions §36. */
+  run: (executable: SupervisableExecutable, input: unknown, options?: SupervisableExecuteOptions) => Promise<SupervisableResult>; /** Inline stream under supervision — see Phase 6 / decisions §36. */
+  stream: (executable: StreamableExecutable, input: unknown, options?: SupervisableExecuteOptions) => StreamContract<SupervisableResult>;
+};
+/**
+ * Object form of a classifier entry — agent variant. Use when you
+ * need to override per-call `placeholders`, `input`, or `history`,
+ * or attach a `refine` post-process hook.
+ */
+type ClassifierAgentEntry<TState = Record<string, unknown>> = {
+  agent: AgentContract<unknown>; /** Per-call placeholders for the agent's systemPrompt template. */
+  placeholders?: (ctx: ClassifierContext<TState>) => Record<string, unknown>; /** Per-call input override; defaults to the supervisor's `ctx.input`. */
+  input?: (ctx: ClassifierContext<TState>) => string;
+  /**
+   * Per-call history slicer. Defaults to the supervisor's
+   * `historyWindow.agents` slice when omitted.
+   */
+  history?: (ctx: ClassifierContext<TState>) => Message[] | ReadonlyArray<Message>;
+  /**
+   * Optional post-classify hook. Receives the classifier's output on
+   * `ctx.result.data`; can override intent, merge state, or halt
+   * via `END`.
+   */
+  refine?: (ctx: ClassifierRefineContext<TState>) => Promise<ClassifierRefineResult> | ClassifierRefineResult;
+};
+/**
+ * Object form of a classifier entry — pure-code callback variant.
+ * Use when classification is deterministic (regex, keyword match,
+ * prior-state inspection) and an LLM call would be wasteful.
+ */
+type ClassifierRunEntry<TState = Record<string, unknown>> = {
+  run: (ctx: ClassifierContext<TState>) => Promise<ClassifierOutput> | ClassifierOutput;
+  refine?: (ctx: ClassifierRefineContext<TState>) => Promise<ClassifierRefineResult> | ClassifierRefineResult;
+};
+/**
+ * Bare-callback shorthand — when classification is a pure function
+ * with no need for a `refine` hook or other entry-form fields.
+ */
+type ClassifierCallback<TState = Record<string, unknown>> = (ctx: ClassifierContext<TState>) => Promise<ClassifierOutput> | ClassifierOutput;
+/**
+ * Accepted shapes for `SupervisorConfig.classifier` (Phase 7 /
+ * decisions §37). Mirrors the same flexibility as `intents` and
+ * `router`:
+ *
+ * - `AgentContract` — bare agent shorthand. Output is parsed via
+ *   the agent's own typed output schema.
+ * - `ClassifierCallback` — bare function shorthand; deterministic
+ *   classification.
+ * - `ClassifierAgentEntry` — full object form for an agent
+ *   classifier with overrides + optional `refine`.
+ * - `ClassifierRunEntry` — full object form for a callback
+ *   classifier with optional `refine`.
+ *
+ * Mutually exclusive with `initialAgent` at the factory level —
+ * both answer "what runs first?" and coexistence is meaningless.
+ * Composes with `router`, `route`, `evaluate`, `ack`,
+ * `intent.next`, and Phases 5/6 features.
+ */
+type ClassifierConfig<TState = Record<string, unknown>> = AgentContract<unknown> | ClassifierCallback<TState> | ClassifierAgentEntry<TState> | ClassifierRunEntry<TState>;
+/**
+ * Forensic record of a classifier run, surfaced on
+ * `SupervisorReport.classifier` (Phase 7). Sibling of `report.ack` —
+ * complete forensic detail regardless of what strip-merged into state.
+ *
+ * `intent` here is the FINAL intent dispatched (post-refine override).
+ * `refined` indicates whether the refine hook changed something.
+ * Original classifier output is captured on `raw` for debugging.
+ */
+type ClassifierSnapshot = {
+  /** Final intent dispatched (post-refine), or absent when refine returned END before any dispatch. */intent?: string;
+  reasoning?: string;
+  confidence?: number; /** True when refine returned a non-undefined value that overrode or augmented the classifier output. */
+  refined: boolean; /** True when refine (or classifier-only mode) halted before any intent dispatched. */
+  halted: boolean; /** Original classifier output (pre-refine) — preserved for debugging. */
+  raw: ClassifierOutput;
+  startedAt: string;
+  endedAt: string;
+  duration: number;
+  usage: Usage;
+  /**
+   * Set when the classifier itself errored OR refine threw. Run is
+   * aborted in either case — the supervisor terminates with this
+   * error on `result.error`.
+   */
+  error?: AIError;
+};
+//#endregion
+export { ClassifierAgentEntry, ClassifierCallback, ClassifierConfig, ClassifierContext, ClassifierOutput, ClassifierRefineContext, ClassifierRefineResult, ClassifierRunEntry, ClassifierSnapshot };
+//# sourceMappingURL=classifier-context.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classifier-context.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/supervisor/classifier-context.type.ts"],"mappings":";;;;;;;;;;;;AAyCA;;;;;;;;AASY;AAsBZ;;;;;;;;;;;;;AAG8D;AAe9D;;KAjDY,gBAAA;EAiD2B,qEA/CrC,MAAA,UAqDO;EAnDP,SAAA;EAqDS;;;;EAhDT,UAAA;AAAA;;;;;;;;;;;;;;;;;;AAsDI;AAUN;KA1CY,sBAAA,eAER,WAAA,IACC,MAAA;EAA4B,MAAA,YAAkB,WAAA;AAAA;;;;;;;;;;;;;;KAevC,iBAAA,UAA2B,MAAA;EAwBM,0DAtB3C,SAAA,KAuBkB;EArBlB,KAAA,EAAO,eAAA,EAuBK;EArBZ,KAAA,EAAO,MAAA,EAuBL;EArBF,OAAA,EAAS,QAAA,CAAS,MAAA,oBAsBd;EApBJ,OAAA,EAAS,aAAA,CAAc,OAAA,GAsBT;EApBd,MAAA,EAAQ,WAAA,EAqBD;EAnBP,IAAA;AAAA;;;;;;;;KAUU,uBAAA,UAAiC,MAAA,qBAC3C,iBAAA,CAAkB,MAAA;EAcsB,8DAZtC,MAAA;IAAU,IAAA,EAAM,gBAAA;EAAA,GAoBsB;EAlBtC,GAAA,GACE,UAAA,EAAY,sBAAA,EACZ,KAAA,WACA,OAAA,GAAU,0BAAA,KACP,OAAA,CAAQ,kBAAA,GAiBwB;EAfrC,MAAA,GACE,UAAA,EAAY,oBAAA,EACZ,KAAA,WACA,OAAA,GAAU,0BAAA,KACP,cAAA,CAAe,kBAAA;AAAA;;;;;;KAQZ,oBAAA,UAA8B,MAAA;EACxC,KAAA,EAAO,aAAA,WAgBwB;EAd/B,YAAA,IAAgB,GAAA,EAAK,iBAAA,CAAkB,MAAA,MAAY,MAAA,mBAetC;EAbb,KAAA,IAAS,GAAA,EAAK,iBAAA,CAAkB,MAAA;EAaO;;;;EARvC,OAAA,IAAW,GAAA,EAAK,iBAAA,CAAkB,MAAA,MAAY,OAAA,KAAY,aAAA,CAAc,OAAA;EATxE;;;;;EAeA,MAAA,IACE,GAAA,EAAK,uBAAA,CAAwB,MAAA,MAC1B,OAAA,CAAQ,sBAAA,IAA0B,sBAAA;AAAA;;;;;;KAQ7B,kBAAA,UAA4B,MAAA;EACtC,GAAA,GACE,GAAA,EAAK,iBAAA,CAAkB,MAAA,MACpB,OAAA,CAAQ,gBAAA,IAAoB,gBAAA;EACjC,MAAA,IACE,GAAA,EAAK,uBAAA,CAAwB,MAAA,MAC1B,OAAA,CAAQ,sBAAA,IAA0B,sBAAA;AAAA;;;;;KAO7B,kBAAA,UAA4B,MAAA,sBACtC,GAAA,EAAK,iBAAA,CAAkB,MAAA,MACpB,OAAA,CAAQ,gBAAA,IAAoB,gBAAA;;;;;;AAvB8B;AAQ/D;;;;;;;;;;;;;KAoCY,gBAAA,UAA0B,MAAA,qBAClC,aAAA,YACA,kBAAA,CAAmB,MAAA,IACnB,oBAAA,CAAqB,MAAA,IACrB,kBAAA,CAAmB,MAAA;;;;;;;;;;KAWX,kBAAA;EAhDuB,qGAkDjC,MAAA;EACA,SAAA;EACA,UAAA,WAlDE;EAoDF,OAAA,WAnDa;EAqDb,MAAA,WArD6D;EAuD7D,GAAA,EAAK,gBAAA;EACL,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA;EAnDgB;;;;;EAyDvB,KAAA,GAAQ,OAAA;AAAA"}