@warlock.js/ai 4.2.10 → 4.3.0

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

@@ -0,0 +1,60 @@
+import { ExecutableContract } from "../executable.contract.mjs";
+import { PlannerExecuteOptions } from "./planner-execute-options.type.mjs";
+import { PlannerResult } from "./planner-result.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/planner/planner.contract.d.ts
+/**
+ * Runtime handle returned by `ai.planner(config)`.
+ *
+ * Implements {@link ExecutableContract} alongside `AgentContract`,
+ * `WorkflowInstance`, and `SupervisorContract`, so a planner can be
+ * dispatched anywhere the framework dispatches an executable — composed
+ * as a supervisor intent, an orchestrator capability, or wrapped as a
+ * tool for an outer agent.
+ *
+ * **What it does.** At `execute(goal)` it asks an LLM to GENERATE an
+ * ordered plan over the registered capabilities, then executes that
+ * plan step-by-step through each capability's own `execute()`,
+ * returning the unified `{ data, report, usage, error }` envelope with
+ * `report.type === "planner"`. Never throws on runtime failure — errors
+ * surface via `result.error`. Authoring-time misconfiguration throws at
+ * factory call, not here.
+ *
+ * @example
+ * const research = ai.planner({
+ *   name: "research-assistant",
+ *   model: ai.openai.model({ name: "gpt-4o" }),
+ *   capabilities: [
+ *     { name: "search", description: "Search the web", executable: searchAgent },
+ *     { name: "write", description: "Draft a summary", executable: writerAgent },
+ *   ],
+ * });
+ *
+ * const { data, report, usage, error } = await research.execute(
+ *   "Summarize the latest on TypeScript 6",
+ * );
+ *
+ * console.log(report.plan?.summary);
+ * for (const executed of report.executedSteps) {
+ *   console.log(executed.step.capability, executed.status);
+ * }
+ */
+interface PlannerContract<TOutput = unknown> extends ExecutableContract<string, PlannerExecuteOptions<TOutput>, PlannerResult<TOutput>> {
+  /** Stable identifier — mirrors the config's `name`. */
+  readonly name: string;
+  /**
+   * Structural fingerprint of the planner definition — name + ordered
+   * capability names. Stamped on every report node this planner
+   * produces.
+   */
+  readonly signature: string;
+  /**
+   * Generate a plan over the configured capabilities and execute it
+   * end-to-end. Returns the uniform `{ data, report, usage, error }`
+   * shape; runtime failures surface on `result.error`.
+   */
+  execute(goal: string, options?: PlannerExecuteOptions<TOutput>): Promise<PlannerResult<TOutput>>;
+}
+//#endregion
+export { PlannerContract };
+//# sourceMappingURL=planner.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner.contract.ts"],"mappings":";;;;;;;AAwCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsBkC;;UAtBjB,eAAA,4BAA2C,kBAAA,SAE1D,qBAAA,CAAsB,OAAA,GACtB,aAAA,CAAc,OAAA;;WAGL,IAAA;;;;;;WAMA,SAAA;;;;;;EAOT,OAAA,CACE,IAAA,UACA,OAAA,GAAU,qBAAA,CAAsB,OAAA,IAC/B,OAAA,CAAQ,aAAA,CAAc,OAAA;AAAA"}

package/esm/contracts/result/base-report.type.d.mts

@@ -19,7 +19,7 @@ declare const REPORT_SCHEMA_VERSION = 1;
  * {@link BaseReport}. Forms a closed union so consumers can narrow on
  * the tree without string-matching on `name`.
  */
-type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor";
+type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor" | "orchestrator" | "batch" | "planner";
 /**
  * Terminal status every executable primitive reports. Unified across
  * tools, agents, workflows, and supervisors so dashboards and
@@ -34,8 +34,13 @@ type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor";
  *   iteration cap was hit without an explicit `END` / `satisfied`.
  *   Harmless on non-supervisor reports; keeping it on the shared
  *   union lets consumers write one `switch` for every status.
+ * - `"awaiting-input"` — orchestrator-specific NON-terminal status: the
+ *   session is paused waiting for the next user turn (§15.6). The only
+ *   non-terminal member of this union; consumers branching on
+ *   `status === "completed"` must treat it as a session-continues path,
+ *   not a failure. Harmless on non-orchestrator reports.
  */
-type ReportStatus = "completed" | "failed" | "cancelled" | "max-iterations";
+type ReportStatus = "completed" | "failed" | "cancelled" | "max-iterations" | "awaiting-input";
 /**
  * Universal execution report shared by every primitive. Per-primitive
  * report types extend this with their own domain-specific fields

package/esm/contracts/result/base-report.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"base-report.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"mappings":";;;;;;AAcA;;;;AAAkC;AAOlC;;;;cAPa,qBAAA;AA6Bb;;;;AAAwB;AAAxB,KAtBY,UAAA;;;;;;;;;;;;;;;;KAsBA,YAAA;;;;;;;;;;;;;;;AA4GS;;;;;;;;;;KA9ET,UAAA;sFAEV,KAAA;;;;;;;;;;EAUA,WAAA;;;;;;;EAOA,SAAA;EAEA,IAAA;;;;;;;;;;;;EAYA,OAAA;;;;;;;;;;EAUA,SAAA;EAEA,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;EAER,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;;;;;;EAMP,QAAA,EAAU,UAAA;;;;;;;;EAQV,QAAA,GAAW,YAAA;;;;;;;;;EASX,mBAAA;AAAA"}
+{"version":3,"file":"base-report.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"mappings":";;;;;;AAcA;;;;AAAkC;AAOlC;;;;cAPa,qBAAA;AAqCb;;;;AAAwB;AAAxB,KA9BY,UAAA;;;;;;;;;;;;;;;;;;;;;KA8BA,YAAA;;;;;;;;;;AA6GS;;;;;;;;;;;;;;;KA9ET,UAAA;sFAEV,KAAA;;;;;;;;;;EAUA,WAAA;;;;;;;EAOA,SAAA;EAEA,IAAA;;;;;;;;;;;;EAYA,OAAA;;;;;;;;;;EAUA,SAAA;EAEA,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;EAER,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;;;;;;EAMP,QAAA,EAAU,UAAA;;;;;;;;EAQV,QAAA,GAAW,YAAA;;;;;;;;;EASX,mBAAA;AAAA"}

package/esm/contracts/result/base-report.type.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"base-report.type.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"sourcesContent":["import type { AttemptEntry } from \"./attempt-entry.type\";\nimport type { Usage } from \"./usage.type\";\n\n/**\n * Wire-format version stamped on every root `BaseReport`. Bumped only\n * when we make a BREAKING change to the report shape (field removed,\n * required-ness flipped, semantics changed). Additive changes (new\n * optional fields) do not bump.\n *\n * Panoptic and other downstream consumers branch on this to parse\n * old stored reports with their original-shape rules.\n *\n * Current: **1** — initial Panoptic-readiness shape.\n */\nexport const REPORT_SCHEMA_VERSION = 1;\n\n/**\n * Discriminator for the kind of executable that produced a given\n * {@link BaseReport}. Forms a closed union so consumers can narrow on\n * the tree without string-matching on `name`.\n */\nexport type ReportType =\n  | \"tool\"\n  | \"callback\"\n  | \"agent\"\n  | \"workflow\"\n  | \"supervisor\";\n\n/**\n * Terminal status every executable primitive reports. Unified across\n * tools, agents, workflows, and supervisors so dashboards and\n * generic traversal helpers don't special-case per primitive.\n *\n * - `\"completed\"` — ran to natural end with a usable result.\n * - `\"failed\"` — aborted mid-run or finished without a usable result\n *   (crash, schema failure, max-trips, etc.). The\n *   accompanying `error` on the envelope carries the typed cause.\n * - `\"cancelled\"` — caller aborted before completion via `AbortSignal`.\n * - `\"max-iterations\"` — supervisor-specific termination when the\n *   iteration cap was hit without an explicit `END` / `satisfied`.\n *   Harmless on non-supervisor reports; keeping it on the shared\n *   union lets consumers write one `switch` for every status.\n */\nexport type ReportStatus =\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"max-iterations\";\n\n/**\n * Universal execution report shared by every primitive. Per-primitive\n * report types extend this with their own domain-specific fields\n * (agent trips, workflow steps, supervisor iteration snapshots) while\n * keeping the root fields identical. Recursion happens through\n * {@link BaseReport.children} — any executable this node invoked\n * contributes its own full report here, producing a walkable tree of\n * the entire run.\n *\n * **Usage rollup.** `usage` at every node equals this node's own cost\n * plus the sum of each child's `usage`. Leaves (tools) contribute\n * zero own-cost; composites contribute their direct LLM spend only,\n * with children covering everything delegated.\n *\n * @example\n * function totalCost(report: BaseReport): number {\n *   return report.usage.total;\n * }\n *\n * function walk(report: BaseReport, depth = 0): void {\n *   console.log(`${\"  \".repeat(depth)}${report.type} \"${report.name}\" — ${report.status}`);\n *   for (const child of report.children) walk(child, depth + 1);\n * }\n */\nexport type BaseReport = {\n  /** Stable id for this execution node. Generated per `execute()`/`invoke()` call. */\n  runId: string;\n  /**\n   * Run-id of the immediate parent execution node, when this node was\n   * invoked as part of a larger run (e.g. a tool dispatched by an\n   * agent; an agent dispatched by a supervisor; an inner primitive\n   * wrapped via `asTool()`). Absent on root nodes.\n   *\n   * Lets Panoptic and other flat-row consumers reconstruct the tree\n   * without traversing `children[]` in memory.\n   */\n  parentRunId?: string;\n  /**\n   * Run-id of the top-level execution this node belongs to. Equals\n   * `runId` on the root node, and is propagated downward to every\n   * descendant. Used to slice flat report tables back into per-run\n   * groupings.\n   */\n  rootRunId: string;\n  /** Executable identity — the tool/agent/workflow/supervisor name. */\n  name: string;\n  /**\n   * Dev-curated version string mirrored from the primitive's config\n   * (`AgentConfig.version`, `ToolConfig.version`, etc.). Free-form —\n   * the framework neither parses nor compares it. Stored verbatim on\n   * every report so trip-archive queries can distinguish runs of\n   * \"agent X v2.1\" from \"agent X v2.2\" even when name + signature\n   * are identical.\n   *\n   * Stays `undefined` when the dev didn't declare one — never\n   * auto-defaulted.\n   */\n  version?: string;\n  /**\n   * Caller-supplied identifier that groups multiple `.execute()` calls\n   * into one conceptual user session / request. Propagated to every\n   * descendant report node so flat queries (\"total spend for session\n   * X today\") work without joining the tree.\n   *\n   * Threaded from `execute()` options on every primitive. Optional —\n   * absent when the caller didn't supply one.\n   */\n  sessionId?: string;\n  /** Discriminator for the kind of executable that produced this report. */\n  type: ReportType;\n  /** Terminal status of this execution. */\n  status: ReportStatus;\n  /** ISO-8601 wall-clock timestamp when execution began. */\n  startedAt: string;\n  /** ISO-8601 wall-clock timestamp when execution finished. */\n  endedAt: string;\n  /** Monotonic duration in milliseconds — `performance.now()` delta. */\n  duration: number;\n  /** Rolled-up usage: own cost + sum of `children[].usage`. */\n  usage: Usage;\n  /**\n   * Reports of every executable invoked by this node, in invocation\n   * order. Empty for leaves (pure tools) and for executables that\n   * didn't delegate work.\n   */\n  children: BaseReport[];\n  /**\n   * Retry history when middleware (or, for workflow steps, the engine\n   * itself) retried this node before it either succeeded or gave up.\n   * Absent when zero retries happened — keeps the common-case payload\n   * lean. The surviving (final) attempt is NOT duplicated here; its\n   * outcome is the report's own `status` / timing.\n   */\n  attempts?: AttemptEntry[];\n  /**\n   * Wire-format version of this report shape. Only present on root\n   * report nodes — implies the same version for the whole tree.\n   * Panoptic / archive consumers branch on this to parse old reports\n   * with their original-shape rules.\n   *\n   * Always equals {@link REPORT_SCHEMA_VERSION} at write time.\n   */\n  reportSchemaVersion?: number;\n};\n"],"mappings":";;;;;;;;;;;;AAcA,MAAa,wBAAwB"}
+{"version":3,"file":"base-report.type.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"sourcesContent":["import type { AttemptEntry } from \"./attempt-entry.type\";\nimport type { Usage } from \"./usage.type\";\n\n/**\n * Wire-format version stamped on every root `BaseReport`. Bumped only\n * when we make a BREAKING change to the report shape (field removed,\n * required-ness flipped, semantics changed). Additive changes (new\n * optional fields) do not bump.\n *\n * Panoptic and other downstream consumers branch on this to parse\n * old stored reports with their original-shape rules.\n *\n * Current: **1** — initial Panoptic-readiness shape.\n */\nexport const REPORT_SCHEMA_VERSION = 1;\n\n/**\n * Discriminator for the kind of executable that produced a given\n * {@link BaseReport}. Forms a closed union so consumers can narrow on\n * the tree without string-matching on `name`.\n */\nexport type ReportType =\n  | \"tool\"\n  | \"callback\"\n  | \"agent\"\n  | \"workflow\"\n  | \"supervisor\"\n  | \"orchestrator\"\n  | \"batch\"\n  | \"planner\";\n\n/**\n * Terminal status every executable primitive reports. Unified across\n * tools, agents, workflows, and supervisors so dashboards and\n * generic traversal helpers don't special-case per primitive.\n *\n * - `\"completed\"` — ran to natural end with a usable result.\n * - `\"failed\"` — aborted mid-run or finished without a usable result\n *   (crash, schema failure, max-trips, etc.). The\n *   accompanying `error` on the envelope carries the typed cause.\n * - `\"cancelled\"` — caller aborted before completion via `AbortSignal`.\n * - `\"max-iterations\"` — supervisor-specific termination when the\n *   iteration cap was hit without an explicit `END` / `satisfied`.\n *   Harmless on non-supervisor reports; keeping it on the shared\n *   union lets consumers write one `switch` for every status.\n * - `\"awaiting-input\"` — orchestrator-specific NON-terminal status: the\n *   session is paused waiting for the next user turn (§15.6). The only\n *   non-terminal member of this union; consumers branching on\n *   `status === \"completed\"` must treat it as a session-continues path,\n *   not a failure. Harmless on non-orchestrator reports.\n */\nexport type ReportStatus =\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"max-iterations\"\n  | \"awaiting-input\";\n\n/**\n * Universal execution report shared by every primitive. Per-primitive\n * report types extend this with their own domain-specific fields\n * (agent trips, workflow steps, supervisor iteration snapshots) while\n * keeping the root fields identical. Recursion happens through\n * {@link BaseReport.children} — any executable this node invoked\n * contributes its own full report here, producing a walkable tree of\n * the entire run.\n *\n * **Usage rollup.** `usage` at every node equals this node's own cost\n * plus the sum of each child's `usage`. Leaves (tools) contribute\n * zero own-cost; composites contribute their direct LLM spend only,\n * with children covering everything delegated.\n *\n * @example\n * function totalCost(report: BaseReport): number {\n *   return report.usage.total;\n * }\n *\n * function walk(report: BaseReport, depth = 0): void {\n *   console.log(`${\"  \".repeat(depth)}${report.type} \"${report.name}\" — ${report.status}`);\n *   for (const child of report.children) walk(child, depth + 1);\n * }\n */\nexport type BaseReport = {\n  /** Stable id for this execution node. Generated per `execute()`/`invoke()` call. */\n  runId: string;\n  /**\n   * Run-id of the immediate parent execution node, when this node was\n   * invoked as part of a larger run (e.g. a tool dispatched by an\n   * agent; an agent dispatched by a supervisor; an inner primitive\n   * wrapped via `asTool()`). Absent on root nodes.\n   *\n   * Lets Panoptic and other flat-row consumers reconstruct the tree\n   * without traversing `children[]` in memory.\n   */\n  parentRunId?: string;\n  /**\n   * Run-id of the top-level execution this node belongs to. Equals\n   * `runId` on the root node, and is propagated downward to every\n   * descendant. Used to slice flat report tables back into per-run\n   * groupings.\n   */\n  rootRunId: string;\n  /** Executable identity — the tool/agent/workflow/supervisor name. */\n  name: string;\n  /**\n   * Dev-curated version string mirrored from the primitive's config\n   * (`AgentConfig.version`, `ToolConfig.version`, etc.). Free-form —\n   * the framework neither parses nor compares it. Stored verbatim on\n   * every report so trip-archive queries can distinguish runs of\n   * \"agent X v2.1\" from \"agent X v2.2\" even when name + signature\n   * are identical.\n   *\n   * Stays `undefined` when the dev didn't declare one — never\n   * auto-defaulted.\n   */\n  version?: string;\n  /**\n   * Caller-supplied identifier that groups multiple `.execute()` calls\n   * into one conceptual user session / request. Propagated to every\n   * descendant report node so flat queries (\"total spend for session\n   * X today\") work without joining the tree.\n   *\n   * Threaded from `execute()` options on every primitive. Optional —\n   * absent when the caller didn't supply one.\n   */\n  sessionId?: string;\n  /** Discriminator for the kind of executable that produced this report. */\n  type: ReportType;\n  /** Terminal status of this execution. */\n  status: ReportStatus;\n  /** ISO-8601 wall-clock timestamp when execution began. */\n  startedAt: string;\n  /** ISO-8601 wall-clock timestamp when execution finished. */\n  endedAt: string;\n  /** Monotonic duration in milliseconds — `performance.now()` delta. */\n  duration: number;\n  /** Rolled-up usage: own cost + sum of `children[].usage`. */\n  usage: Usage;\n  /**\n   * Reports of every executable invoked by this node, in invocation\n   * order. Empty for leaves (pure tools) and for executables that\n   * didn't delegate work.\n   */\n  children: BaseReport[];\n  /**\n   * Retry history when middleware (or, for workflow steps, the engine\n   * itself) retried this node before it either succeeded or gave up.\n   * Absent when zero retries happened — keeps the common-case payload\n   * lean. The surviving (final) attempt is NOT duplicated here; its\n   * outcome is the report's own `status` / timing.\n   */\n  attempts?: AttemptEntry[];\n  /**\n   * Wire-format version of this report shape. Only present on root\n   * report nodes — implies the same version for the whole tree.\n   * Panoptic / archive consumers branch on this to parse old reports\n   * with their original-shape rules.\n   *\n   * Always equals {@link REPORT_SCHEMA_VERSION} at write time.\n   */\n  reportSchemaVersion?: number;\n};\n"],"mappings":";;;;;;;;;;;;AAcA,MAAa,wBAAwB"}

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

@@ -8,7 +8,8 @@ import { LLMTrip } from "./llm-trip.type.mjs";
 import { AgentReport, ExecutionReport, ExecutionStatus } from "./execution-report.type.mjs";
 import { AgentResult } from "./agent-result.type.mjs";
 import { ExecuteResult } from "./execute-result.type.mjs";
+import { SupervisorReport, SupervisorResult, SupervisorTerminatedBy } from "./supervisor-result.type.mjs";
 import { StepSnapshot } from "./step-result.type.mjs";
 import { WorkflowReport, WorkflowResult } from "./workflow-result.type.mjs";
-import { SupervisorReport, SupervisorResult, SupervisorTerminatedBy } from "./supervisor-result.type.mjs";
+import { CompactionResult, OrchestratorAwaitingStatus, OrchestratorReport, OrchestratorReportStatus, OrchestratorReportType, OrchestratorResult, TurnSnapshot } from "./orchestrator-result.type.mjs";
 import { SessionSendResult } from "./session-send-result.type.mjs";

package/esm/contracts/result/model-pricing.type.d.mts

@@ -45,6 +45,16 @@ type ModelPricing = {
    * does not. Falls back to `output` when undefined.
    */
   cachedOutput?: number;
+  /**
+   * USD per 1M reasoning/thinking tokens (`Usage.reasoningTokens`), for
+   * providers that price reasoning above the standard output rate.
+   * Falls back to `output` when undefined — the common case, since most
+   * providers bill reasoning tokens at the output rate.
+   *
+   * @example
+   * const pricing: ModelPricing = { input: 0.15, output: 0.6, reasoning: 0.6 };
+   */
+  reasoning?: number;
 };
 //#endregion
 export { ModelPricing };

package/esm/contracts/result/model-pricing.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"model-pricing.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/model-pricing.type.ts"],"mappings":";;AA+BA;;;;;;;;;AAgBc;;;;;;;;;;;;;;;;;;;;;KAhBF,YAAA;iCAEV,KAAA;EAEA,MAAA;;;;;;EAMA,WAAA;;;;;;EAMA,YAAA;AAAA"}
+{"version":3,"file":"model-pricing.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/model-pricing.type.ts"],"mappings":";;AA+BA;;;;;;;;;;AA0BW;;;;;;;;;;;;;;;;;;;;KA1BC,YAAA;iCAEV,KAAA;EAEA,MAAA;;;;;;EAMA,WAAA;;;;;;EAMA,YAAA;;;;;;;;;;EAUA,SAAA;AAAA"}

package/esm/contracts/result/orchestrator-result.type.d.mts

@@ -0,0 +1,139 @@
+import { Message } from "../conversation-message.type.mjs";
+import { Usage } from "./usage.type.mjs";
+import { BaseReport, ReportStatus } from "./base-report.type.mjs";
+import { ExecuteResult } from "./execute-result.type.mjs";
+import { SupervisorInput } from "../supervisor/supervisor-input.type.mjs";
+import { EvaluateResult } from "../supervisor/evaluate-context.type.mjs";
+import { AgentBranchSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/result/orchestrator-result.type.d.ts
+/**
+ * Discriminator literal the orchestrator stamps onto its report's
+ * `type` field (design §15.5). Now a member of the shared
+ * {@link ReportType} closed union in `base-report.type.ts`, so
+ * {@link OrchestratorReport} narrows `type` against the shared union
+ * directly rather than overriding it.
+ */
+type OrchestratorReportType = "orchestrator";
+/**
+ * Non-terminal status the orchestrator adds on top of the shared
+ * {@link ReportStatus} union — the session is paused waiting for the
+ * next user turn (design §15.6, Q9). This is the only non-terminal
+ * status across the unified result tree, and is now a member of the
+ * shared {@link ReportStatus} union in `base-report.type.ts`.
+ */
+type OrchestratorAwaitingStatus = "awaiting-input";
+/**
+ * Combined status surface for an orchestrator report — every terminal
+ * {@link ReportStatus} plus the non-terminal `"awaiting-input"`.
+ * Consumers branching on `status === "completed"` must explicitly
+ * handle `"awaiting-input"` as a session-continues path, not a failure
+ * (§15.6, §18.10).
+ */
+type OrchestratorReportStatus = ReportStatus | OrchestratorAwaitingStatus;
+/**
+ * The result of compacting (summarizing) a slice of session history
+ * (design §12, §15.5). Carries the replacement summary message plus the
+ * inclusive index range it replaces, so a dev-owned message store can
+ * apply the compaction deterministically.
+ *
+ * Structurally identical to `OrchestratorCommands["compact"]["result"]`
+ * — both are kept per the literal §11 / §15.5 spec shapes.
+ */
+type CompactionResult = {
+  /** The summary message that replaces the compacted range. */summary: Message; /** Inclusive start index (in the dev's history array) of the replaced range. */
+  replacesFromIndex: number; /** Inclusive end index of the replaced range. */
+  replacesToIndex: number;
+};
+/**
+ * One turn's forensic record on {@link OrchestratorReport.turns}.
+ * Mirrors the supervisor's `IterationSnapshot.result` shape so a turn
+ * reads uniformly whether it dispatched one agent (`iterate: false`) or
+ * delegated to an internal supervisor (`iterate: true`).
+ *
+ * Frozen (`Readonly`) so consumers can pass snapshots across async
+ * boundaries without defensive cloning. `state` is the post-merge,
+ * JSON-serializable session state at the end of the turn.
+ */
+type TurnSnapshot = Readonly<{
+  /** Zero-indexed turn number. */turn: number; /** The user input that opened this turn. */
+  input: SupervisorInput; /** Where the dispatch decision came from and its raw value. */
+  decision: {
+    source: "route" | "router" | "intent.next";
+    raw: unknown;
+    reasoning?: string;
+  }; /** Per-branch dispatch records keyed by intent (mirrors supervisor). */
+  result: Record<string, AgentBranchSnapshot>; /** Post-merge session state — JSON-serializable. */
+  state: unknown; /** Evaluate verdict, if `evaluate` ran this turn. */
+  evaluate?: EvaluateResult;
+  startedAt: string;
+  endedAt: string;
+  duration: number;
+  usage: Usage;
+  /**
+   * The dispatched primitive's full report tree — the internal
+   * supervisor's report when `iterate: true`, the direct agent's report
+   * when `iterate: false`.
+   */
+  childReport?: BaseReport;
+}>;
+/**
+ * Session-scoped execution report for a single orchestrator turn
+ * (design §15.5). Extends {@link BaseReport} with session identity, the
+ * turn index, the drift signature, and the per-turn history on
+ * `turns[]`.
+ *
+ * `children[]` carries ONLY the current turn's dispatched primitive
+ * reports (Q9). Full session history lives on `turns[]`; walkers that
+ * recurse via `children[]` will NOT reach prior turns — intentional.
+ *
+ * @remarks
+ * `type` and `status` narrow the shared {@link BaseReport} fields to
+ * the orchestrator-specific literals. Both `"orchestrator"` and
+ * `"awaiting-input"` are now members of the shared {@link ReportType} /
+ * {@link ReportStatus} unions, so this inherits {@link BaseReport}
+ * directly and re-declares the two fields as compatible narrowings.
+ */
+type OrchestratorReport = BaseReport & {
+  type: OrchestratorReportType;
+  status: OrchestratorReportStatus;
+  sessionId: string;
+  turnIndex: number; /** Orchestrator-scope drift signature (§10.1). */
+  signature: string;
+  version?: string; /** Current turn + (optionally) prior turns, bounded by `keepSnapshots`. */
+  turns: TurnSnapshot[];
+};
+/**
+ * Per-turn result returned by `orchestrator.execute()` and resolved by
+ * `orchestrator.stream().result` (design §15.5). Extends the unified
+ * {@link ExecuteResult} envelope with the session id, the turn index,
+ * an optional compaction record, and the orchestrator report.
+ *
+ * Narrow on `report.type` / `report.status` (not a top-level
+ * discriminant string) and read typed `data` for the turn's output.
+ *
+ * @example
+ * const result = await orchestrator.execute(message, { sessionId, history });
+ *
+ * if (result.error) {
+ *   logger.error(result.error.code, { sessionId: result.sessionId });
+ *   return;
+ * }
+ *
+ * if (result.report.status === "awaiting-input") {
+ *   // session continues — prompt the user for the next turn
+ * }
+ *
+ * if (result.compaction) {
+ *   await myMessageStore.applyCompaction(result.sessionId, result.compaction);
+ * }
+ */
+type OrchestratorResult<TOutput = unknown> = ExecuteResult<TOutput> & {
+  sessionId: string;
+  turnIndex: number;
+  compaction?: CompactionResult;
+  report: OrchestratorReport;
+};
+//#endregion
+export { CompactionResult, OrchestratorAwaitingStatus, OrchestratorReport, OrchestratorReportStatus, OrchestratorReportType, OrchestratorResult, TurnSnapshot };
+//# sourceMappingURL=orchestrator-result.type.d.mts.map

package/esm/contracts/result/orchestrator-result.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/orchestrator-result.type.ts"],"mappings":";;;;;;;;;;;AAeA;;;;AAAkC;KAAtB,sBAAA;;;;AAS0B;AAStC;;;KATY,0BAAA;AASoE;AAWhF;;;;;;AAXgF,KAApE,wBAAA,GAA2B,YAAA,GAAe,0BAA0B;;;AAiB/D;AAajB;;;;;;KAnBY,gBAAA;EAuCH,6DArCP,OAAA,EAAS,OAAO,EAiBS;EAfzB,iBAAA,UAeiC;EAbjC,eAAA;AAAA;;;;;;;;;;;KAaU,YAAA,GAAe,QAAA;EAgBd,gCAdX,IAAA,UAgBA;EAdA,KAAA,EAAO,eAAA,EAgBP;EAdA,QAAA;IACE,MAAA;IACA,GAAA;IACA,SAAA;EAAA,GAqCQ;EAlCV,MAAA,EAAQ,MAAA,SAAe,mBAAA;EAEvB,KAAA,WAiCM;EA/BN,QAAA,GAAW,cAAA;EACX,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA;EA2BP;;;;;EArBA,WAAA,GAAc,UAAA;AAAA;;;;;AA6BK;AA4BrB;;;;;;;;;;;;KArCY,kBAAA,GAAqB,UAAA;EAC/B,IAAA,EAAM,sBAAA;EACN,MAAA,EAAQ,wBAAA;EACR,SAAA;EACA,SAAA,UAqCQ;EAnCR,SAAA;EACA,OAAA;EAEA,KAAA,EAAO,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BG,kBAAA,sBAAwC,aAAA,CAAc,OAAA;EAChE,SAAA;EACA,SAAA;EACA,UAAA,GAAa,gBAAA;EACb,MAAA,EAAQ,kBAAA;AAAA"}

package/esm/contracts/result/session-send-result.type.d.mts

@@ -1,13 +1,22 @@
 import { AIError } from "../../errors/ai-error.mjs";
 import { Usage } from "./usage.type.mjs";
 import { AgentResult } from "./agent-result.type.mjs";
-import { WorkflowResult } from "./workflow-result.type.mjs";
 import { SupervisorResult } from "./supervisor-result.type.mjs";
+import { WorkflowResult } from "./workflow-result.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/result/session-send-result.type.d.ts
 /**
- * Result returned by SessionContract.send().
- * Narrows executionResult by checking the `type` discriminant.
+ * Result returned by `SessionContract.send()`.
+ * Narrows `executionResult` by checking the `type` discriminant.
+ *
+ * @deprecated Obsolete v2 forward-declaration. The locked v1
+ * orchestrator's per-turn result is `OrchestratorResult<TOutput>` — see
+ * `./orchestrator-result.type`. It extends the unified
+ * {@link ExecuteResult} envelope (`data` / `error` / `usage` / `report`)
+ * and adds `sessionId` / `turnIndex` / optional `compaction`, narrowing
+ * via `report.type` / `report.status` rather than the `response` /
+ * `done` / `executionResult` fields here. Retained unchanged for one
+ * minor for non-breaking compatibility; do not use in new code.
  *
  * @example
  * const result = await session.send("Analyze this dataset");

package/esm/contracts/result/session-send-result.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"session-send-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/session-send-result.type.ts"],"mappings":";;;;;;;;;AAkBA;;;;;;;;;;KAAY,iBAAA;EAIV,iDAFA,QAAA,UAIQ;EAFR,IAAA,WAKI;EAHJ,KAAA,GAAQ,OAAA,EAKJ;EAHJ,eAAA,EACI,WAAA,YACA,gBAAA,YACA,cAAA,WAEG;EAAP,KAAA,EAAO,KAAA;AAAA"}
+{"version":3,"file":"session-send-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/session-send-result.type.ts"],"mappings":";;;;;;;;;AA2BA;;;;;;;;;;;;;;;;;;;KAAY,iBAAA;EAaE,iDAXZ,QAAA;EAEA,IAAA;EAEA,KAAA,GAAQ,OAAA;EAER,eAAA,EACI,WAAA,YACA,gBAAA,YACA,cAAA;EAEJ,KAAA,EAAO,KAAA;AAAA"}

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

@@ -1,7 +1,7 @@
 import { BaseResult } from "./base-result.type.mjs";
 import { BaseReport } from "./base-report.type.mjs";
-import { AckSnapshot, IterationSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
 import { ClassifierSnapshot } from "../supervisor/classifier-context.type.mjs";
+import { AckSnapshot, IterationSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/result/supervisor-result.type.d.ts
 /**

package/esm/contracts/result/usage.type.d.mts

@@ -31,6 +31,30 @@ type Usage = {
    * providers that don't report cache hits leave this undefined.
    */
   cachedTokens?: number;
+  /**
+   * Subset of `output` the provider attributes to internal reasoning /
+   * thinking before the visible answer (OpenAI reasoning models'
+   * `completion_tokens_details.reasoning_tokens`, Anthropic
+   * extended-thinking tokens). Counted within `output` for billing
+   * unless the provider prices it separately (see
+   * `ModelPricing.reasoning`). Optional — undefined when the provider
+   * doesn't report a reasoning channel.
+   *
+   * @example
+   * const usage: Usage = { input: 150, output: 320, total: 470, reasoningTokens: 180 };
+   */
+  reasoningTokens?: number;
+  /**
+   * Number of input tokens WRITTEN to the provider's prompt cache on
+   * this call (Anthropic `cache_creation_input_tokens`). Distinct from
+   * `cachedTokens`, which counts read hits. Bills at
+   * `ModelPricing.cachedOutput` when set. Optional — undefined for
+   * providers/calls with no cache write.
+   *
+   * @example
+   * const usage: Usage = { input: 150, output: 320, total: 470, cacheWriteTokens: 64 };
+   */
+  cacheWriteTokens?: number;
   /**
    * Cost breakdown in USD, computed at emit time from `tokens × pricing[model]`
    * when the model adapter declared a `ModelPricing`. Same shape as

package/esm/contracts/result/usage.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/usage.type.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;AAgCqB;;;;;;;KAhCT,KAAA;wEAEV,KAAA;EAEA,MAAA;EAEA,KAAA;;;;;;EAMA,YAAA;;;;;;;;;;;;;;;;;;;;EAoBA,IAAA,GAAO,YAAY;AAAA"}
+{"version":3,"file":"usage.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/usage.type.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;;;AAwDqB;;;;;KAxDT,KAAA;wEAEV,KAAA;EAEA,MAAA;EAEA,KAAA;;;;;;EAMA,YAAA;;;;;;;;;;;;;EAaA,eAAA;;;;;;;;;;;EAWA,gBAAA;;;;;;;;;;;;;;;;;;;;EAoBA,IAAA,GAAO,YAAY;AAAA"}

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

@@ -1,6 +1,6 @@
 import { ModelPricing } from "./result/model-pricing.type.mjs";
-import { EmbedderConfig, EmbedderContract } from "./embedder.contract.mjs";
 import { ModelContract } from "./model.contract.mjs";
+import { EmbedderConfig, EmbedderContract } from "./embedder.contract.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/sdk-adapter.contract.d.ts
 /**

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

@@ -2,14 +2,14 @@ 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 { SupervisorResult } from "../result/supervisor-result.type.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 { SupervisorIntentValue } from "./intent-entry.type.mjs";
 import { SupervisorContract } from "./supervisor.contract.mjs";
 import { ClassifierSnapshot } from "./classifier-context.type.mjs";
-import { SupervisorResult } from "../result/supervisor-result.type.mjs";
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
 import { AgentExecuteOptions } from "../agent/agent-options.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/supervisor/dispatch-context.type.d.ts

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

@@ -1,9 +1,9 @@
 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";
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/supervisor/evaluate-context.type.d.ts
 /**

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

@@ -1,16 +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 { SupervisorSnapshot, SupervisorSnapshotStatus } from "./supervisor-snapshot.type.mjs";
+import { SupervisorExecuteOptions, SupervisorResumeOptions } from "./supervisor-execute-options.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 { Next } from "./next.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";
+import { EvaluateBranchResult, EvaluateContext, EvaluateResult } from "./evaluate-context.type.mjs";
+import { AckSnapshot, AgentBranchSnapshot, DecisionSource, IterationDecision, IterationSnapshot } from "./iteration-snapshot.type.mjs";

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

@@ -1,8 +1,8 @@
 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";
+import { EvaluateResult } from "./evaluate-context.type.mjs";
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/supervisor/route-context.type.d.ts
 /**

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

@@ -1,16 +1,18 @@
 import { Message } from "../conversation-message.type.mjs";
 import { AgentContract } from "../agent/agent.contract.mjs";
+import { SupervisorInput } from "./supervisor-input.type.mjs";
+import { SnapshotStore } from "../orchestrator/snapshot-store.contract.mjs";
+import { AgentMiddleware } from "../middleware/middleware.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 { Next } from "./next.type.mjs";
 import { RouterEntry } from "./router-entry.type.mjs";
 import { ClassifierConfig } from "./classifier-context.type.mjs";
+import { EvaluateContext, EvaluateResult } from "./evaluate-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
 /**
@@ -54,7 +56,7 @@ type SupervisorEventHandlers = Partial<{ [K in keyof SupervisorEventMap]: Superv
  *     ctx.state.response ? { satisfied: true } : undefined,
  *   maxIterations: 6,
  *   output: v.object({ response: v.string(), refund: v.boolean() }),
- *   snapshotStore: cache.driver("redis", { client }),
+ *   snapshotStore: ai.snapshot.redis({ client }),
  * });
  */
 type SupervisorConfig<TOutput = unknown, TState = TOutput, TIntents extends Record<string, SupervisorIntentValue> = Record<string, SupervisorIntentValue>, TArtifacts = Record<string, unknown>> = {
@@ -68,6 +70,18 @@ type SupervisorConfig<TOutput = unknown, TState = TOutput, TIntents extends Reco
    * independent.
    */
   version?: string;
+  /**
+   * Opt-in Standard Schema describing this supervisor's input. Purely
+   * additive — when set, the supervisor can be dropped straight into an
+   * agent's `tools: []` array WITHOUT calling `.asTool()`: the runtime
+   * derives the LLM tool manifest from `name` + the resolved
+   * description + this schema and dispatches through `execute()`. Omit
+   * it and `.asTool()` (which takes its own `inputSchema`) remains the
+   * way to expose the supervisor as a tool. Not enforced by the
+   * supervisor runtime itself — `execute()` still accepts the raw
+   * `SupervisorInput` union.
+   */
+  inputSchema?: StandardSchemaV1<SupervisorInput>;
   /**
    * Prepended to the router agent's own system prompt (router mode
    * only). Does not touch child agents' system prompts — they stay
@@ -205,17 +219,18 @@ type SupervisorConfig<TOutput = unknown, TState = TOutput, TIntents extends Reco
    */
   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
+   * Optional durable {@link SnapshotStore} enabling
+   * `supervisor.resume(runId)`. Snapshots are written after every
+   * iteration settles plus once more at final completion / cancel /
+   * fail. Construct with `ai.snapshot.{memory,pg,redis}()` —
+   * `ai.snapshot.memory()` for dev/tests, `ai.snapshot.redis()` /
+   * `ai.snapshot.pg()` for production.
+   *
+   * Falls back to `ai.config({ defaultSnapshotStore })` when omitted.
+   * When neither is set, `resume()` throws and snapshot writes silently
    * skip (current behavior preserved).
    */
-  snapshotStore?: CacheDriver<any, any>;
+  snapshotStore?: SnapshotStore;
   /**
    * Definition-level event handlers — tier 1 of the 3-tier model.
    * Fire on every run of this supervisor, before instance and
@@ -327,6 +342,33 @@ type SupervisorConfig<TOutput = unknown, TState = TOutput, TIntents extends Reco
    * }),
    */
   artifactsSchema?: StandardSchemaV1<TArtifacts>;
+  /**
+   * Supervisor-level middleware — fires the optional `supervisor` hook
+   * map (`before` / `after` / `onError`) of each `AgentMiddleware`
+   * once around the entire `execute()` / `stream()` / `resume()` run,
+   * the supervisor-level peer of an agent's `execute`-level middleware.
+   *
+   * Same onion semantics as the agent pipeline: `before` runs top-down
+   * (return a `SupervisorResult` to short-circuit the whole run, throw
+   * to abort it), `after` / `onError` run bottom-up (return a
+   * `SupervisorResult` to replace / recover). A middleware without a
+   * `supervisor` hook map is skipped — so the same builtin objects
+   * (budget, guardrail, …) can be registered here and on agents,
+   * declaring whichever level applies.
+   *
+   * Each middleware needs a unique `name` (the `ctx.state` namespace);
+   * the supervisor does not re-validate the array — register the same
+   * objects you validated for the agents.
+   *
+   * @example
+   * ai.supervisor({
+   *   name: "support",
+   *   router,
+   *   intents: { ... },
+   *   middleware: [auditTrail],
+   * });
+   */
+  middleware?: AgentMiddleware[];
   /**
    * Per-iteration merger for the artifacts bag (Phase 5 /
    * decisions §35). When omitted the framework auto-spreads:

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

@@ -1 +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"}
+{"version":3,"file":"supervisor-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;AAoBA;;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;EAuGJ,sEApGT,IAAA;EAoGkC;;;;;;;;EA1FlC,OAAA;EAuH6C;;;;;;;;;;;EA1G7C,WAAA,GAAc,gBAAA,CAAiB,eAAA;EAoRI;;;;;EA7QnC,YAAA,GAAe,oBAAA;EAiUqD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA1RpE,IAAA,YAAgB,oBAAA;EA4DiB;;;;;;;;;;;;;;;;;;;EAvCjC,OAAA,GAAU,OAAA;EA+JG;;;;;;;;EArJb,MAAA,GAAS,aAAA,YAAyB,WAAA,CAAY,MAAA;EAmO9C;;;;EA7NA,KAAA,IAAS,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,IAAA,GAAO,OAAA,CAAQ,IAAA;EAqPP;;;;AAAqB;;;;;;EAzOpE,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;;;;;;;;;;;;;EAc1B,aAAA,GAAgB,aAAA;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BnC,UAAA,GAAa,eAAA;;;;;;;;;;;;;;;;;;;;;;;EAwBb,iBAAA,IAAqB,KAAA,EAAO,MAAA,EAAQ,SAAA,EAAW,UAAA,KAAe,MAAA;AAAA"}

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

@@ -1,5 +1,5 @@
-import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
 import { SupervisorInput } from "./supervisor-input.type.mjs";
+import { IterationSnapshot } from "./iteration-snapshot.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/supervisor/supervisor-snapshot.type.d.ts
 /**

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

@@ -1,11 +1,11 @@
 import { ExecutableContract } from "../executable.contract.mjs";
 import { StreamContract } from "../stream/stream.contract.mjs";
+import { SupervisorResult } from "../result/supervisor-result.type.mjs";
 import { ToolContract } from "../../tool/tool.mjs";
 import { SupervisorInput } from "./supervisor-input.type.mjs";
-import { SupervisorEventHandler } from "./supervisor-config.type.mjs";
 import { SupervisorExecuteOptions, SupervisorResumeOptions } from "./supervisor-execute-options.type.mjs";
+import { SupervisorEventHandler } from "./supervisor-config.type.mjs";
 import { SupervisorStreamEvent } from "./supervisor-stream-event.type.mjs";
-import { SupervisorResult } from "../result/supervisor-result.type.mjs";
 import { SupervisorEventMap } from "../events/event-map.type.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
@@ -68,6 +68,13 @@ type SupervisorAsToolOptions<TToolInput> = {
 interface SupervisorContract<TOutput = unknown> extends ExecutableContract<SupervisorInput, SupervisorExecuteOptions, SupervisorResult<TOutput>> {
   /** Stable identifier — mirrors the config's `name`. */
   readonly name: string;
+  /**
+   * Mirrors {@link SupervisorConfig.inputSchema} when set — lets the
+   * agent tool-collection path auto-adapt this supervisor into a
+   * `ToolContract` (manifest derived from name + this schema) when it
+   * appears in `tools: []` without `.asTool()`.
+   */
+  readonly inputSchema?: StandardSchemaV1<SupervisorInput>;
   /**
    * Structural fingerprint of the supervisor definition — agent
    * keys + their resolved descriptions + router identity (if set) +