@warlock.js/ai 4.3.0 → 4.5.0

package/esm/contracts/planner/planner-execute-options.type.d.mts

@@ -1,7 +1,29 @@
 import { Placeholders } from "../placeholders.type.mjs";
+import { PlannerPlan } from "./planner-plan.type.mjs";
+import { PlannerStepSnapshot } from "./planner-result.type.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region ../@warlock.js/ai/src/contracts/planner/planner-execute-options.type.d.ts
+/**
+ * Steering verdict returned by the {@link PlannerExecuteOptions.onStep}
+ * hook after a step settles.
+ *
+ * - `{ type: "continue" }` (or returning nothing) — proceed as normal.
+ * - `{ type: "abort" }` — stop the run; remaining steps are recorded
+ *   `skipped`, exactly as a step failure aborts today.
+ * - `{ type: "replan"; feedback }` — re-ask the planning agent for a
+ *   fresh plan over the REMAINING work, seeded with the executed-step
+ *   digest plus `feedback`. Bounded by `config.replan.maxReplans`; a
+ *   `replan` directive with no `replan` config is treated as `continue`.
+ */
+type PlannerStepDirective = {
+  type: "continue";
+} | {
+  type: "abort";
+} | {
+  type: "replan";
+  feedback: string;
+};
 /**
  * Options accepted by `planner.execute(goal, options?)`.
  *
@@ -37,7 +59,32 @@ type PlannerExecuteOptions<TOutput = unknown> = {
    * trace queries don't need to walk the tree.
    */
   sessionId?: string;
+  /**
+   * Approval gate. `"plan-only"` generates (and validates) the plan and
+   * returns WITHOUT executing — `report.status === "awaiting-approval"`
+   * and `result.plan` carries the generated plan. Pass that plan back via
+   * `approvedPlan` to execute it. Defaults to `"execute"`.
+   *
+   * **`mode: "plan-only"` with `approvedPlan` is contradictory** —
+   * `approvedPlan` wins (the plan is executed).
+   */
+  mode?: "execute" | "plan-only";
+  /**
+   * Execute this exact plan, skipping plan generation entirely. Pairs
+   * with a prior `mode: "plan-only"` call's `result.plan`. The plan is
+   * still validated against the live capabilities, so a stale plan
+   * naming a capability the planner no longer has surfaces a typed
+   * `PlannerPlanInvalidError`.
+   */
+  approvedPlan?: PlannerPlan;
+  /**
+   * Per-step hook fired after each step settles (both the sequential and
+   * the DAG path). Return a {@link PlannerStepDirective} to steer the
+   * run: continue (default), abort, or replan the remainder with
+   * feedback. May be async.
+   */
+  onStep?: (snapshot: PlannerStepSnapshot, plan: PlannerPlan) => void | PlannerStepDirective | Promise<void | PlannerStepDirective>;
 };
 //#endregion
-export { PlannerExecuteOptions };
+export { PlannerExecuteOptions, PlannerStepDirective };
 //# sourceMappingURL=planner-execute-options.type.d.mts.map

package/esm/contracts/planner/planner-execute-options.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"planner-execute-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-execute-options.type.ts"],"mappings":";;;;;;AASA;;;;KAAY,qBAAA;EAaD,+DAXT,KAAA;EAoBoB;;;;EAfpB,YAAA,GAAe,YAAA;EAAA;;;;;EAMf,MAAA,GAAS,gBAAA,CAAiB,OAAA;EAgB1B;;AAAS;;;;;;EAPT,MAAA,GAAS,WAAA;;;;;;;EAOT,SAAA;AAAA"}
+{"version":3,"file":"planner-execute-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-execute-options.type.ts"],"mappings":";;;;;;;;AAiBA;;;;;;;;;AAG8B;KAHlB,oBAAA;EACN,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;EAAgB,QAAA;AAAA;;;;;;;KAQV,qBAAA;EAAsB,+DAEhC,KAAA;EAKA;;;;EAAA,YAAA,GAAe,YAAA;EAef;;;;;EATA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EAyC1B;;;;;;;;EAhCA,MAAA,GAAS,WAAA;EAmC6D;;;;;;EA5BtE,SAAA;;;;;;;;;;EAUA,IAAA;;;;;;;;EAQA,YAAA,GAAe,WAAA;;;;;;;EAOf,MAAA,IACE,QAAA,EAAU,mBAAA,EACV,IAAA,EAAM,WAAA,YACI,oBAAA,GAAuB,OAAA,QAAe,oBAAA;AAAA"}

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

@@ -8,9 +8,15 @@ import { PlannerPlan, PlannerStep } from "./planner-plan.type.mjs";
 /**
  * Discriminator literal the planner stamps onto its report's `type`
  * field. A member of the shared
- * {@link import("../result/base-report.type").ReportType} closed union,
- * so {@link PlannerReport} narrows `type` against the shared union
- * directly rather than overriding it.
+ * {@link import("../result/base-report.type").ReportType} closed union.
+ *
+ * {@link PlannerReport} re-declares `type` as this literal by *overriding*
+ * it (`Omit<BaseReport, "type"> & { type: PlannerReportType }`) rather than
+ * intersecting (`BaseReport & { type: "planner" }`). Intersecting a single
+ * literal against `BaseReport.type` (the whole `ReportType` union) lets a
+ * strict TypeScript collapse the entire report to `never` ("property `type`
+ * has conflicting types in some constituents"); the `Omit` override sidesteps
+ * that while still producing the same `type: "planner"` for consumers.
  */
 type PlannerReportType = "planner";
 /**
@@ -45,7 +51,7 @@ type PlannerStepSnapshot = {
  * per-step record (one entry per step the planner attempted), and
  * `plan` is the verbatim LLM output before any step ran.
  */
-type PlannerReport = BaseReport & {
+type PlannerReport = Omit<BaseReport, "type"> & {
   type: PlannerReportType; /** Structural fingerprint — same value exposed on the planner instance. */
   signature: string; /** The full plan the planner's LLM generated before execution began. */
   plan?: PlannerPlan; /** Per-step forensic records, in execution order. */
@@ -73,9 +79,17 @@ type PlannerReport = BaseReport & {
  *
  * console.log(report.plan?.summary, usage.total);
  */
-type PlannerResult<TOutput = unknown> = ExecuteResult<TOutput> & {
+type PlannerResult<TOutput = unknown> = Omit<ExecuteResult<TOutput>, "report"> & {
   /** Discriminant for narrowing a heterogeneous result union. */type: "planner";
   report: PlannerReport;
+  /**
+   * The generated plan, surfaced WITHOUT execution when the run was
+   * invoked with `mode: "plan-only"` (`report.status ===
+   * "awaiting-approval"`). Pass it back as `approvedPlan` on a follow-up
+   * `execute()` to run it. Absent on a normal execute run — the executed
+   * plan lives on `report.plan`.
+   */
+  plan?: PlannerPlan;
 };
 //#endregion
 export { PlannerReport, PlannerReportType, PlannerResult, PlannerStepSnapshot };

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

@@ -1 +1 @@
-{"version":3,"file":"planner-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-result.type.ts"],"mappings":";;;;;;;;;AAaA;;;;AAA6B;KAAjB,iBAAA;;;;;;;;;;KAWA,mBAAA;EAIJ,0DAFN,KAAA,UAMA;EAJA,IAAA,EAAM,WAAA,EAME;EAJR,MAAA,sCAMA;EAJA,MAAA,YAMA;EAJA,KAAA,GAAQ,OAAA;EACR,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA,EAgBG;EAdV,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;KAcJ,aAAA,GAAgB,UAAA;EAC1B,IAAA,EAAM,iBAAA,EAMS;EAJf,SAAA,UAMW;EAJX,IAAA,GAAO,WAAA,EA4BG;EA1BV,aAAA,EAAe,mBAAA,IA0BQ;EAxBvB,WAAA;AAAA;;;;;;;;;;;AA2BqB;;;;;;;;;;;KAHX,aAAA,sBAAmC,aAAA,CAAc,OAAA;iEAE3D,IAAA;EACA,MAAA,EAAQ,aAAA;AAAA"}
+{"version":3,"file":"planner-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-result.type.ts"],"mappings":";;;;;;;;;AAmBA;;;;AAA6B;AAW7B;;;;;;KAXY,iBAAA;;;;;;;;;;KAWA,mBAAA;EAYV,0DAVA,KAAA,UAYA;EAVA,IAAA,EAAM,WAAA,EAYN;EAVA,MAAA,sCAUwB;EARxB,MAAA,YAsBU;EApBV,KAAA,GAAQ,OAAA;EACR,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA,EAqBA;EAnBP,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;KAcJ,aAAA,GAAgB,IAAA,CAAK,UAAA;EAC/B,IAAA,EAAM,iBAAA,EAgCI;EA9BV,SAAA,UA8BuB;EA5BvB,IAAA,GAAO,WAAA,EA4B2C;EA1BlD,aAAA,EAAe,mBAAA,IA6BP;EA3BR,WAAA;AAAA;;;;;;;;;;;;AAmCkB;;;;;;;;;;KAXR,aAAA,sBAAmC,IAAA,CAAK,aAAA,CAAc,OAAA;iEAEhE,IAAA;EACA,MAAA,EAAQ,aAAA;;;;;;;;EAQR,IAAA,GAAO,WAAA;AAAA"}

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

@@ -1,6 +1,6 @@
 import { ExecutableContract } from "../executable.contract.mjs";
-import { PlannerExecuteOptions } from "./planner-execute-options.type.mjs";
 import { PlannerResult } from "./planner-result.type.mjs";
+import { PlannerExecuteOptions } from "./planner-execute-options.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/planner/planner.contract.d.ts
 /**

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

@@ -7,10 +7,12 @@ import { AgentReport } from "./execution-report.type.mjs";
  *
  * **Canonical destructuring:** `const { data, text, report, usage, error }`.
  *
- * `report.trips` / `report.toolCalls` / `report.duration` hold
- * everything the old top-level fields did — moving them under
- * `report` leaves the root clean for the four things callers reach
- * for constantly (`data`, `text`, `usage`, `error`).
+ * `report.trips` / `report.children` / `report.duration` hold
+ * everything the old top-level fields did — tool dispatches live as
+ * child nodes on `report.children` (filter `type === "tool"`), and
+ * moving these under `report` leaves the root clean for the four
+ * things callers reach for constantly (`data`, `text`, `usage`,
+ * `error`).
  *
  * @example
  * const { data, error, report, usage } = await agent.execute(input);

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

@@ -1 +1 @@
-{"version":3,"file":"agent-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/agent-result.type.ts"],"mappings":";;;;;;AAuBA;;;;;;;;;;;;;;;;;AAQqB;KART,WAAA,sBAAiC,UAAA;wEAE3C,IAAA;EAEA,IAAA,GAAO,OAAA;EAEP,IAAA;EAEA,MAAA,EAAQ,WAAA;AAAA"}
+{"version":3,"file":"agent-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/agent-result.type.ts"],"mappings":";;;;;;AAyBA;;;;;;;;;;;;;;;;;AAQqB;;;KART,WAAA,sBAAiC,UAAA;wEAE3C,IAAA;EAEA,IAAA,GAAO,OAAA;EAEP,IAAA;EAEA,MAAA,EAAQ,WAAA;AAAA"}

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

@@ -1,3 +1,4 @@
+import { AIError } from "../../errors/ai-error.mjs";
 import { Usage } from "./usage.type.mjs";
 import { AttemptEntry } from "./attempt-entry.type.mjs";
 
@@ -19,7 +20,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" | "orchestrator" | "batch" | "planner";
+type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor" | "team" | "orchestrator" | "batch" | "planner";
 /**
  * Terminal status every executable primitive reports. Unified across
  * tools, agents, workflows, and supervisors so dashboards and
@@ -39,8 +40,13 @@ type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor" | "o
  *   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.
+ * - `"awaiting-approval"` — planner-specific NON-terminal status: a
+ *   `mode: "plan-only"` run generated and validated a plan but executed
+ *   nothing, pending sign-off (the plan rides on `result.plan`). Mirrors
+ *   `"awaiting-input"` at the plan boundary. Harmless on non-planner
+ *   reports.
  */
-type ReportStatus = "completed" | "failed" | "cancelled" | "max-iterations" | "awaiting-input";
+type ReportStatus = "completed" | "failed" | "cancelled" | "max-iterations" | "awaiting-input" | "awaiting-approval";
 /**
  * Universal execution report shared by every primitive. Per-primitive
  * report types extend this with their own domain-specific fields
@@ -108,7 +114,19 @@ type BaseReport = {
    */
   sessionId?: string; /** Discriminator for the kind of executable that produced this report. */
   type: ReportType; /** Terminal status of this execution. */
-  status: ReportStatus; /** ISO-8601 wall-clock timestamp when execution began. */
+  status: ReportStatus;
+  /**
+   * Terminal error stamped on a `failed` / `cancelled` node so the typed
+   * cause travels WITH the report tree — not only on the result envelope.
+   * Essential for the observe path: an {@link import("../../observe/observer.contract").Observer}
+   * receives `collect(report)` with no envelope, so a failed root would
+   * otherwise expose `status` with no error type/message. Child tool nodes
+   * already carry their error this way (`ToolCall.error`); root primitives
+   * (agent / workflow / supervisor / orchestrator / planner) stamp it here
+   * too. Absent on a `completed` node. Panoptic normalizes it to a JSON-safe
+   * span error during projection — the raw `AIError` never has to serialize.
+   */
+  error?: AIError; /** ISO-8601 wall-clock timestamp when execution began. */
   startedAt: string; /** ISO-8601 wall-clock timestamp when execution finished. */
   endedAt: string; /** Monotonic duration in milliseconds — `performance.now()` delta. */
   duration: number; /** Rolled-up usage: own cost + sum of `children[].usage`. */

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;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"}
+{"version":3,"file":"base-report.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"mappings":";;;;;;;AAeA;;;;AAAkC;AAOlC;;;;cAPa,qBAAA;AA2Cb;;;;AAAwB;AAAxB,KApCY,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KAoCA,YAAA;;;;;;;;AA0HS;;;;;;;;;;;;;;;;;KA1FT,UAAA;sFAEV,KAAA;;;;;;;;;;EAUA,WAAA;;;;;;;EAOA,SAAA;EAEA,IAAA;;;;;;;;;;;;EAYA,OAAA;;;;;;;;;;EAUA,SAAA;EAEA,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;;;;;;;;;;;;EAYR,KAAA,GAAQ,OAAA;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  | \"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"}
+{"version":3,"file":"base-report.type.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"sourcesContent":["import type { AIError } from \"../../errors/ai-error\";\nimport 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  | \"team\"\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 * - `\"awaiting-approval\"` — planner-specific NON-terminal status: a\n *   `mode: \"plan-only\"` run generated and validated a plan but executed\n *   nothing, pending sign-off (the plan rides on `result.plan`). Mirrors\n *   `\"awaiting-input\"` at the plan boundary. Harmless on non-planner\n *   reports.\n */\nexport type ReportStatus =\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"max-iterations\"\n  | \"awaiting-input\"\n  | \"awaiting-approval\";\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  /**\n   * Terminal error stamped on a `failed` / `cancelled` node so the typed\n   * cause travels WITH the report tree — not only on the result envelope.\n   * Essential for the observe path: an {@link import(\"../../observe/observer.contract\").Observer}\n   * receives `collect(report)` with no envelope, so a failed root would\n   * otherwise expose `status` with no error type/message. Child tool nodes\n   * already carry their error this way (`ToolCall.error`); root primitives\n   * (agent / workflow / supervisor / orchestrator / planner) stamp it here\n   * too. Absent on a `completed` node. Panoptic normalizes it to a JSON-safe\n   * span error during projection — the raw `AIError` never has to serialize.\n   */\n  error?: AIError;\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":";;;;;;;;;;;;AAeA,MAAa,wBAAwB"}

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

@@ -1,7 +1,25 @@
+import { ModelToolCallRequest } from "../model-tool-call-request.type.mjs";
 import { BaseReport, ReportStatus } from "./base-report.type.mjs";
 import { LLMTrip } from "./llm-trip.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/result/execution-report.type.d.ts
+/**
+ * One normalized turn of an agent's assembled conversation, captured
+ * onto {@link AgentReport.messages} when `captureMessages` is enabled.
+ *
+ * A faithful, JSON-safe projection of the runtime `Message`: the `tool`
+ * role returns a tool's output; an `assistant` turn that requested tools
+ * carries `toolCalls`; a `tool` turn carries the `toolCallId` it answers.
+ * `content` is always a string here (the runtime stringifies tool
+ * results and flattens text), so the captured array survives JSON
+ * serialization and downstream exporters forward it verbatim.
+ */
+type CapturedMessage = {
+  /** Who produced this turn. */role: "system" | "user" | "assistant" | "tool"; /** The turn's text content (tool results are stringified JSON). */
+  content: string; /** Tool calls the assistant requested — present only on assistant turns that triggered tools. */
+  toolCalls?: ModelToolCallRequest[]; /** Provider tool-call id this turn answers — present only on tool-result turns. */
+  toolCallId?: string;
+};
 /**
  * Terminal status alias retained for backwards-compatibility with
  * existing imports. Use {@link ReportStatus} directly for new code —
@@ -44,7 +62,41 @@ type AgentReport = BaseReport & {
     provider: string;
   }; /** Every LLM round-trip that happened during execution. */
   trips: LLMTrip[];
+  /**
+   * The resolved system-prompt text sent as the `role: "system"` message
+   * (persona + instructions + any auto-appended structured-output
+   * instruction). Captured for observability; absent when the agent ran
+   * without a system prompt. Note `LLMTrip.input` holds only the user
+   * message — the system prompt is recorded here.
+   */
+  systemPrompt?: string;
+  /**
+   * Registry name of the named `SystemPromptContract` this run resolved —
+   * its `meta.name`, addressable in `ai.prompts`. Present ONLY when the agent
+   * ran against a *named* prompt; absent for a raw-string prompt, an anonymous
+   * contract, or no prompt at all. Together with {@link AgentReport.promptVersion}
+   * it links a run to the exact prompt version that produced it, so downstream
+   * consumers (Panoptic) can group / filter runs by `promptName@promptVersion`.
+   */
+  promptName?: string;
+  /**
+   * Registry version label of the named prompt this run resolved — its
+   * `meta.version` (defaulting to `"1"` when the prompt is named but carries
+   * no explicit version, mirroring the `ai.prompts` registry default). Present
+   * ONLY alongside {@link AgentReport.promptName}.
+   */
+  promptVersion?: string;
+  /**
+   * The full assembled multi-turn conversation — every role
+   * (system / user / assistant / tool), every trip — captured as a
+   * {@link CapturedMessage}[]. Present ONLY when the agent's
+   * `captureMessages` option was set; absent otherwise (byte-for-byte
+   * as before). Opt-in because messages can be large and sensitive.
+   * Unlike `trips[].input` (which stubs non-first trips with
+   * `"[tool results]"`), this preserves the real turn array.
+   */
+  messages?: CapturedMessage[];
 };
 //#endregion
-export { AgentReport, ExecutionReport, ExecutionStatus };
+export { AgentReport, CapturedMessage, ExecutionReport, ExecutionStatus };
 //# sourceMappingURL=execution-report.type.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"execution-report.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/execution-report.type.ts"],"mappings":";;;;;;AAQA;;;KAAY,eAAA,GAAkB,YAAY;AAAA;AAM1C;;;AAN0C,KAM9B,eAAA,GAAkB,UAAU;AAAA;AAoBxC;;;;;;;;;;;AAUgB;;;;;;AA9BwB,KAoB5B,WAAA,GAAc,UAAA;;;;;;;;EAQxB,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA;EAEvB,KAAA,EAAO,OAAO;AAAA"}
+{"version":3,"file":"execution-report.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/execution-report.type.ts"],"mappings":";;;;;;;AAeA;;;;;;;;;KAAY,eAAA;EAQA,8BANV,IAAA,4CAcyB;EAZzB,OAAA,UAYwC;EAVxC,SAAA,GAAY,oBAAoB,IAgBtB;EAdV,UAAA;AAAA;;AAcsC;AAoBxC;;;KA1BY,eAAA,GAAkB,YAAY;;;;;KAM9B,eAAA,GAAkB,UAAU;;;;;;;;;;;;AAgEZ;;;;;;;KA5ChB,WAAA,GAAc,UAAA;;;;;;;;EAQxB,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA;EAEvB,KAAA,EAAO,OAAA;;;;;;;;EAQP,YAAA;;;;;;;;;EASA,UAAA;;;;;;;EAOA,aAAA;;;;;;;;;;EAUA,QAAA,GAAW,eAAA;AAAA"}

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

@@ -9,10 +9,14 @@ 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` field (design §15.5). A member of the shared
+ * {@link ReportType} closed union in `base-report.type.ts`.
+ *
+ * {@link OrchestratorReport} re-declares `type` as this literal by
+ * *overriding* it (`Omit<BaseReport, "type"> & { type: ... }`) rather than
+ * intersecting `BaseReport` with it: intersecting a single literal against
+ * `BaseReport.type` (the whole `ReportType` union) lets a strict TypeScript
+ * collapse the report to `never` ("conflicting types in some constituents").
  */
 type OrchestratorReportType = "orchestrator";
 /**
@@ -88,13 +92,13 @@ type TurnSnapshot = Readonly<{
  * 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` and `status` are the orchestrator-specific literals — both
+ * `"orchestrator"` and `"awaiting-input"` are members of the shared
+ * {@link ReportType} / {@link ReportStatus} unions. `type` is OVERRIDDEN
+ * via `Omit<BaseReport, "type">` (not intersected) so a strict TypeScript
+ * can't collapse the report to `never`; `status` is re-declared compatibly.
  */
-type OrchestratorReport = BaseReport & {
+type OrchestratorReport = Omit<BaseReport, "type"> & {
   type: OrchestratorReportType;
   status: OrchestratorReportStatus;
   sessionId: string;
@@ -128,7 +132,7 @@ type OrchestratorReport = BaseReport & {
  *   await myMessageStore.applyCompaction(result.sessionId, result.compaction);
  * }
  */
-type OrchestratorResult<TOutput = unknown> = ExecuteResult<TOutput> & {
+type OrchestratorResult<TOutput = unknown> = Omit<ExecuteResult<TOutput>, "report"> & {
   sessionId: string;
   turnIndex: number;
   compaction?: CompactionResult;

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

@@ -1 +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"}
+{"version":3,"file":"orchestrator-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/orchestrator-result.type.ts"],"mappings":";;;;;;;;;;;AAmBA;;;;AAAkC;AASlC;;;;KATY,sBAAA;AAkBZ;;;;AAAgF;AAWhF;;AAXA,KATY,0BAAA;;;;;;;AA0BK;KAjBL,wBAAA,GAA2B,YAAA,GAAe,0BAA0B;;;;;;;;;;KAWpE,gBAAA;EAmBuB,6DAjBjC,OAAA,EAAS,OAAO,EAmBhB;EAjBA,iBAAA,UAmBO;EAjBP,eAAA;AAAA;;;;;;;;;;;KAaU,YAAA,GAAe,QAAA;EAoBzB,gCAlBA,IAAA,UAwBA;EAtBA,KAAA,EAAO,eAAA,EAsBiB;EApBxB,QAAA;IACE,MAAA;IACA,GAAA;IACA,SAAA;EAAA,GAqC6B;EAlC/B,MAAA,EAAQ,MAAA,SAAe,mBAAA,GAoCf;EAlCR,KAAA,WAyCmB;EAvCnB,QAAA,GAAW,cAAA;EACX,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA;EA4BP;;;;;EAtBA,WAAA,GAAc,UAAA;AAAA;;;AA6BK;AA4BrB;;;;;;;;;;;;;;KArCY,kBAAA,GAAqB,IAAA,CAAK,UAAA;EACpC,IAAA,EAAM,sBAAA;EACN,MAAA,EAAQ,wBAAA;EACR,SAAA;EACA,SAAA,UAqCQ;EAnCR,SAAA;EACA,OAAA;EAEA,KAAA,EAAO,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BG,kBAAA,sBAAwC,IAAA,CAAK,aAAA,CAAc,OAAA;EACrE,SAAA;EACA,SAAA;EACA,UAAA,GAAa,gBAAA;EACb,MAAA,EAAQ,kBAAA;AAAA"}

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

@@ -25,6 +25,13 @@ type SupervisorTerminatedBy = "router" | "route" | "classifier" | "evaluate" | "
  * reports of the child agents/workflows dispatched across iterations.
  */
 type SupervisorReport = BaseReport & {
+  /**
+   * Discriminator for the supervisor engine. `"team"` when produced by
+   * `ai.team` (thin sugar over the same engine) so team runs are
+   * distinguishable on the wire — group/filter as their own type — while
+   * sharing this report shape; `"supervisor"` for a plain `ai.supervisor`.
+   */
+  type: "supervisor" | "team";
   supervisorName: string; /** Structural fingerprint — same value exposed on the instance. */
   signature: string;
   terminatedBy: SupervisorTerminatedBy; /** How many iterations ran (including the terminal one). */
@@ -77,7 +84,12 @@ type SupervisorReport = BaseReport & {
  * return { answer: data, cost: usage.total, turns: report.iterations };
  */
 type SupervisorResult<TOutput = unknown> = BaseResult & {
-  /** Discriminant for narrowing `SessionSendResult.executionResult`. */type: "supervisor";
+  /**
+   * Discriminant for narrowing `SessionSendResult.executionResult`.
+   * `"team"` for `ai.team` runs (sugar over the same engine), else
+   * `"supervisor"` — matches the report's discriminator.
+   */
+  type: "supervisor" | "team";
   data?: TOutput;
   report: SupervisorReport;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"supervisor-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/supervisor-result.type.ts"],"mappings":";;;;;;;;AAWA;;;;KAAY,sBAAA;AAsBZ;;;;;;;;;;;;;AAAA,KAAY,gBAAA,GAAmB,UAAA;EAC7B,cAAA,UAKA;EAHA,SAAA;EACA,YAAA,EAAc,sBAAA,EAKH;EAHX,UAAA,UAUM;EARN,WAAA;EACA,SAAA,EAAW,iBAAA;EAgBoB;AAAA;AA+BjC;;;;EAxCE,GAAA,GAAM,WAAA;EA4CE;;;;;;;;EAnCR,UAAA,GAAa,kBAAA;AAAA;;AAmCW;;;;;;;;;;;;;;;;;;;;;;;;;;;KAJd,gBAAA,sBAAsC,UAAA;wEAEhD,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,gBAAA;AAAA"}
+{"version":3,"file":"supervisor-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/supervisor-result.type.ts"],"mappings":";;;;;;;;AAWA;;;;KAAY,sBAAA;AAsBZ;;;;;;;;;;;;;AAAA,KAAY,gBAAA,GAAmB,UAAA;EAW7B;;;;;;EAJA,IAAA;EACA,cAAA,UAwBA;EAtBA,SAAA;EACA,YAAA,EAAc,sBAAA,EAqBiB;EAnB/B,UAAA,UAkD0B;EAhD1B,WAAA;EACA,SAAA,EAAW,iBAAA;EAsDJ;;;;;;EA/CP,GAAA,GAAM,WAAA;EA+CN;;;;;AACwB;;;EAvCxB,UAAA,GAAa,kBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA+BH,gBAAA,sBAAsC,UAAA;;;;;;EAMhD,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,gBAAA;AAAA"}

package/esm/contracts/result/tool-call.type.d.mts

@@ -23,8 +23,8 @@ import { BaseReport } from "./base-report.type.mjs";
  *   console.log(call.name, call.tripIndex, call.input, call.output);
  * }
  */
-type ToolCall = BaseReport & {
-  /** Discriminator already fixed on BaseReport, narrowed to "tool" here. */type: "tool"; /** Which LLM trip triggered this tool call (0-indexed). */
+type ToolCall = Omit<BaseReport, "type"> & {
+  /** Discriminator overridden to "tool" via `Omit<BaseReport, "type">`. */type: "tool"; /** Which LLM trip triggered this tool call (0-indexed). */
   tripIndex: number; /** Input passed to the tool (validated args from the model's request). */
   input: unknown; /** Output returned by the tool (undefined if an error occurred). */
   output?: unknown; /** Typed AI error thrown during dispatch (validation or execute), if any. */

package/esm/contracts/result/tool-call.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-call.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/tool-call.type.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;AAmBe;;;;;;KAnBH,QAAA,GAAW,UAAA;4EAErB,IAAA;EAEA,SAAA;EAEA,KAAA;EAEA,MAAA;EAEA,KAAA,GAAQ,OAAO;;;;;;;;;EASf,aAAA;AAAA"}
+{"version":3,"file":"tool-call.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/tool-call.type.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;;;;;;AAmBe;KAnBH,QAAA,GAAW,IAAA,CAAK,UAAA;2EAE1B,IAAA;EAEA,SAAA;EAEA,KAAA;EAEA,MAAA;EAEA,KAAA,GAAQ,OAAA;;;;;;;;;EASR,aAAA;AAAA"}

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

@@ -15,6 +15,7 @@ import { StepSnapshot } from "./step-result.type.mjs";
  * the cross-cutting tree view shared with other primitives.
  */
 type WorkflowReport = BaseReport & {
+  /** Discriminator narrowed to the workflow primitive. */type: "workflow";
   workflowName: string; /** Structural fingerprint — same value exposed on the workflow instance. */
   signature: string; /** ISO-8601 timestamp when cancellation was observed, if any. */
   cancelledAt?: string; /** Per-step snapshots keyed by step name. */

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

@@ -1 +1 @@
-{"version":3,"file":"workflow-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/workflow-result.type.ts"],"mappings":";;;;;;;;AAeA;;;;;;;;KAAY,cAAA,GAAiB,UAAA;EAC3B,YAAA,UAD2B;EAG3B,SAAA;EAEA,WAAA,WAEA;EAAA,KAAA,EAAO,MAAA,SAAe,YAAA,GAAA;EAEtB,KAAA,EAAO,QAAA,CAAS,MAAA;AAAA;;;AAAM;AAgBxB;;;;;;;;;;KAAY,cAAA,sBAAoC,UAAA;EAC9C,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,cAAA;EACR,KAAA,GAAQ,OAAA;AAAA"}
+{"version":3,"file":"workflow-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/workflow-result.type.ts"],"mappings":";;;;;;;;AAeA;;;;;;;;KAAY,cAAA,GAAiB,UAAA;EAWZ,wDATf,IAAA;EACA,YAAA;EAEA,SAAA,UAEA;EAAA,WAAA,WAEO;EAAP,KAAA,EAAO,MAAA,SAAe,YAAA,GAEtB;EAAA,KAAA,EAAO,QAAA,CAAS,MAAA;AAAA;;AAAM;AAgBxB;;;;;;;;;;;KAAY,cAAA,sBAAoC,UAAA;EAC9C,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,cAAA;EACR,KAAA,GAAQ,OAAA;AAAA"}

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

@@ -1,5 +1,6 @@
 import { Message } from "../conversation-message.type.mjs";
 import { AgentContract } from "../agent/agent.contract.mjs";
+import { FlowObserveOption } from "../../observe/resolve-observers.mjs";
 import { SupervisorInput } from "./supervisor-input.type.mjs";
 import { SnapshotStore } from "../orchestrator/snapshot-store.contract.mjs";
 import { AgentMiddleware } from "../middleware/middleware.contract.mjs";
@@ -70,6 +71,15 @@ type SupervisorConfig<TOutput = unknown, TState = TOutput, TIntents extends Reco
    * independent.
    */
   version?: string;
+  /**
+   * INTERNAL — the report-type discriminator stamped on this run's root
+   * report + result envelope. Defaults to `"supervisor"`. `ai.team` sets
+   * `"team"` so its runs are distinguishable on the wire (group/filter as
+   * their own type) while reusing the supervisor engine wholesale. Not
+   * part of the public supervisor surface — plain `ai.supervisor` callers
+   * leave it unset.
+   */
+  reportType?: "supervisor" | "team";
   /**
    * Opt-in Standard Schema describing this supervisor's input. Purely
    * additive — when set, the supervisor can be dropped straight into an
@@ -392,6 +402,25 @@ type SupervisorConfig<TOutput = unknown, TState = TOutput, TIntents extends Reco
    * }),
    */
   finalizeArtifacts?: (state: TState, artifacts: TArtifacts) => TState;
+  /**
+   * Observability for this supervisor. Additive and gated — when
+   * omitted, the supervisor follows the global observe-all flag (off
+   * unless an observability tool turned it on), so behavior is unchanged
+   * by default.
+   *
+   * - `true` → route this run's completed report to the globally
+   *   registered observers, even when observe-all is off.
+   * - `false` → opt this supervisor out entirely, even when observe-all is on.
+   * - an `Observer` object → a flow-local collector receiving only this
+   *   supervisor's report. Typed as the structural `Observer` so core
+   *   stays panoptic-agnostic; a panoptic flow-local collector can be
+   *   passed directly. Observer errors are swallowed — they never break
+   *   the run.
+   *
+   * `ai.team(...)` forwards its `observe` here verbatim so a team
+   * inherits supervisor observability with no extra wiring.
+   */
+  observe?: FlowObserveOption;
 };
 //#endregion
 export { SupervisorConfig, SupervisorEventHandler, SupervisorEventHandlers };

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":";;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"supervisor-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/supervisor/supervisor-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA;;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;EAiHJ,sEA9GT,IAAA;EA8GkC;;;;;;;;EApGlC,OAAA;EAiI6C;;;;;;;;EAvH7C,UAAA;EAuMM;;;;;;;;;;;EA1LN,WAAA,GAAc,gBAAA,CAAiB,eAAA;EAvC/B;;;;;EA8CA,YAAA,GAAe,oBAAA;EA5C0C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmFzD,IAAA,YAAgB,oBAAA;EAmFhB;;;;;;;;;;;;;;;;;;;EA9DA,OAAA,GAAU,OAAA;EAiNQ;;;;;;;;EAvMlB,MAAA,GAAS,aAAA,YAAyB,WAAA,CAAY,MAAA;EA2PgB;;;;EArP9D,KAAA,IAAS,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,IAAA,GAAO,OAAA,CAAQ,IAAA;;;;;;;;;;;EAYtD,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;;;;;;;;;;;;;;;;;;;EAoB9D,OAAA,GAAU,iBAAA;AAAA"}