@warlock.js/ai 4.4.0 → 4.6.0

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

@@ -1,7 +1,10 @@
 import { AgentContract } from "../agent/agent.contract.mjs";
+import { FlowObserveOption } from "../../observe/resolve-observers.mjs";
+import { SnapshotStore } from "../orchestrator/snapshot-store.contract.mjs";
 import { ModelContract } from "../model.contract.mjs";
 import { SystemPromptContract } from "../system-prompt.contract.mjs";
 import { PlannerCapability } from "./planner-capability.type.mjs";
+import { PlannerSnapshot } from "./planner-snapshot.type.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region ../@warlock.js/ai/src/contracts/planner/planner-config.type.d.ts
@@ -35,6 +38,14 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
 type PlannerConfig<TOutput = unknown> = {
   /** Stable identifier — used in logs, events, signature, report `name`. */name: string; /** Dev-curated version string. Metadata only — never parsed. */
   version?: string;
+  /**
+   * Per-flow observability routing. `true` routes this planner's report to
+   * the globally-registered observers (even with observe-all off); `false`
+   * opts out; an `Observer` is a flow-local collector; omitted follows the
+   * global observe-all flag. Brings the planner to parity with
+   * agent/workflow/supervisor instead of only ever routing under observe-all.
+   */
+  observe?: FlowObserveOption;
   /**
    * Model used to build the internal planning agent that GENERATES the
    * plan. Mutually exclusive with `planner`.
@@ -72,6 +83,56 @@ type PlannerConfig<TOutput = unknown> = {
    * untyped.
    */
   output?: StandardSchemaV1<TOutput>;
+  /**
+   * Schedule independent steps in parallel off `dependsOn`. When true the
+   * planner builds a DAG from step `id` / `dependsOn`, runs each ready
+   * level concurrently, and feeds each step ONLY its dependencies'
+   * outputs. A cycle or a `dependsOn` that names an unknown step raises a
+   * typed {@link import("../../errors/planner-plan-invalid-error").PlannerPlanInvalidError}
+   * before any step runs. Default `false` ⇒ today's strict array-order
+   * loop, byte-for-byte unchanged.
+   */
+  dag?: boolean; /** Max concurrent steps when `dag` is true. Default 4. */
+  maxConcurrency?: number;
+  /**
+   * Adaptive re-planning. When set, a failed step (or a `replan` verdict
+   * from the `onStep` execute-option) revises the REMAINING plan instead
+   * of aborting — re-asking the planning agent for a fresh plan seeded
+   * with the executed-step digest plus the feedback. Bounded by
+   * `maxReplans`; on exhaustion the run ends with the last failure.
+   * Default off ⇒ a failure aborts exactly as today.
+   */
+  replan?: {
+    maxReplans: number;
+  };
+  /**
+   * Opt-in durable mid-run crash-resume. When set, the planner
+   * checkpoints its state to a {@link SnapshotStore} after every settled
+   * plan node, so a `planner.resume(runId)` after a crash re-hydrates the
+   * frozen plan + executed-node ledger + usage + child reports and
+   * continues scheduling only the unfinished frontier — never re-calling
+   * the planning LLM and never re-dispatching a completed node's
+   * capability.
+   *
+   * Absent ⇒ no persistence, zero behavior change: the planner runs
+   * byte-for-byte as today.
+   *
+   * - `store` — the snapshot store to persist to. Optional; falls back to
+   *   `ai.config({ defaultSnapshotStore })`. When neither is set, snapshot
+   *   writes silently skip and `resume()` throws.
+   * - `deleteOnComplete` — drop the snapshot once the run terminates
+   *   successfully. Default `false` (keep it for the completed-run
+   *   short-circuit + audit).
+   *
+   * **Idempotency caveat.** A crash mid-node re-runs that node's
+   * capability on resume; side-effectful capabilities must be idempotent —
+   * the same caller-responsibility boundary the supervisor and workflow
+   * primitives already document.
+   */
+  durable?: {
+    /** Snapshot store to persist to. Falls back to the global default. */store?: SnapshotStore<PlannerSnapshot>; /** Drop the snapshot on successful completion. Default `false`. */
+    deleteOnComplete?: boolean;
+  };
 };
 //#endregion
 export { PlannerConfig };

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

@@ -1 +1 @@
-{"version":3,"file":"planner-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-config.type.ts"],"mappings":";;;;;;;;;AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,aAAA;EAyCuB,0EAvCjC,IAAA;EAEA,OAAA;;;;;EAKA,KAAA,GAAQ,aAAA;;;;;;EAMR,OAAA,GAAU,aAAA;;;;;;EAMV,YAAA,GAAe,oBAAA;;;;;;EAMf,YAAA,EAAc,iBAAA;;;;;;;EAOd,QAAA;;;;;;;EAOA,MAAA,GAAS,gBAAA,CAAiB,OAAA;AAAA"}
+{"version":3,"file":"planner-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-config.type.ts"],"mappings":";;;;;;;;;;;;AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,aAAA;EAmCI,0EAjCd,IAAA,UA+CA;EA7CA,OAAA;EA6C0B;;;;;;;EArC1B,OAAA,GAAU,iBAAA;EAqFc;;;AAEN;EAlFlB,KAAA,GAAQ,aAAA;;;;;;EAMR,OAAA,GAAU,aAAA;;;;;;EAMV,YAAA,GAAe,oBAAA;;;;;;EAMf,YAAA,EAAc,iBAAA;;;;;;;EAOd,QAAA;;;;;;;EAOA,MAAA,GAAS,gBAAA,CAAiB,OAAA;;;;;;;;;;EAU1B,GAAA;EAEA,cAAA;;;;;;;;;EASA,MAAA;IAAW,UAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;EAyBX,OAAA;0EAEE,KAAA,GAAQ,aAAA,CAAc,eAAA;IAEtB,gBAAA;EAAA;AAAA"}

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,44 @@ 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>;
+};
+/**
+ * Options accepted by `planner.resume(runId, options?)`.
+ *
+ * `force: true` bypasses the signature drift check — use only when you
+ * have verified the definition change is safe for the in-flight
+ * snapshot. `PlannerDriftError` is otherwise thrown without executing
+ * anything. Everything else mirrors {@link PlannerExecuteOptions} (e.g.
+ * re-supply a `signal` to keep the resumed run cancellable).
+ */
+type PlannerResumeOptions<TOutput = unknown> = PlannerExecuteOptions<TOutput> & {
+  /** Bypass the drift check and resume against the changed definition. */force?: boolean;
 };
 //#endregion
-export { PlannerExecuteOptions };
+export { PlannerExecuteOptions, PlannerResumeOptions, 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;AAYxE;;;;;EAxCE,SAAA;EAwC0E;;;AAErE;;;;;;EAhCL,IAAA;;;;;;;;EAQA,YAAA,GAAe,WAAA;;;;;;;EAOf,MAAA,IACE,QAAA,EAAU,mBAAA,EACV,IAAA,EAAM,WAAA,YACI,oBAAA,GAAuB,OAAA,QAAe,oBAAA;AAAA;;;;;;;;;;KAYxC,oBAAA,sBAA0C,qBAAqB,CAAC,OAAA;0EAE1E,KAAA;AAAA"}

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

@@ -82,6 +82,14 @@ type PlannerReport = Omit<BaseReport, "type"> & {
 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":";;;;;;;;;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;;;;;;;;;AA2BqB;;;;;;;;;;;;;KAHX,aAAA,sBAAmC,IAAA,CAAK,aAAA,CAAc,OAAA;iEAEhE,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-snapshot.type.d.mts

@@ -0,0 +1,77 @@
+import { Usage } from "../result/usage.type.mjs";
+import { BaseReport } from "../result/base-report.type.mjs";
+import { PlannerPlan } from "./planner-plan.type.mjs";
+import { PlannerStepSnapshot } from "./planner-result.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/planner/planner-snapshot.type.d.ts
+/**
+ * Lifecycle status of a durable planner run, recorded on the persisted
+ * snapshot so `resume()` can decide whether a run is still in flight.
+ *
+ * - `"running"` — the execution loop is active; a resume is legitimate
+ *   if the process crashed between node boundaries.
+ * - `"completed"` — the planner terminated successfully; resume is a
+ *   no-op and re-returns the final result rebuilt from the snapshot.
+ * - `"cancelled"` — aborted via `AbortSignal`; resume is allowed.
+ * - `"failed"` — terminated with an error; resume after the fix.
+ */
+type PlannerSnapshotStatus = "running" | "completed" | "cancelled" | "failed";
+/**
+ * Persisted shape written to the configured {@link
+ * import("../orchestrator/snapshot-store.contract").SnapshotStore} after
+ * every plan node settles. Exists so `planner.resume(runId)` can
+ * re-hydrate the frozen plan + per-node ledger + rolled-up usage +
+ * child reports and continue scheduling the unfinished DAG / sequential
+ * tail.
+ *
+ * **Checkpoint granularity is per-node.** The snapshot is written at the
+ * end of `executeStep`, after the step's `PlannerStepSnapshot` is pushed
+ * and its usage + child report folded in. A completed node's capability
+ * dispatch is never re-invoked on resume — the sequential skip-guard /
+ * DAG re-seed derive the completed-node set from `executedSteps`.
+ *
+ * `signature` is the same structural fingerprint exposed on the planner
+ * instance (`computeSignature(name, capabilities)`). `resume()` compares
+ * it against the current definition; a mismatch throws `PlannerDriftError`
+ * (bypassable with `{ force: true }`). A mid-run re-plan is NOT drift —
+ * the plan changed, not the definition; `replanCount` is persisted so the
+ * replan budget is honored across a resume.
+ *
+ * Every field is JSON-serializable — `PlannerPlan`, `PlannerStepSnapshot`,
+ * `Usage`, and `BaseReport` are the same plain-data shapes already
+ * persisted on reports.
+ *
+ * @example
+ * const snapshot: PlannerSnapshot | undefined = await store.load(runId);
+ * if (snapshot?.status === "running") {
+ *   await planner.resume(runId);
+ * }
+ */
+type PlannerSnapshot = {
+  /** The store key — stable across the whole run. */runId: string; /** Planner name, for the resume error message + attribution. */
+  plannerName: string; /** Structural drift fingerprint — `computeSignature(name, capabilities)`. */
+  signature: string; /** `PlannerConfig.version` — metadata only, never compared. */
+  version?: string; /** The original `execute(goal)` value — needed to rebuild prompts on replan. */
+  goal: string;
+  /**
+   * The frozen plan generated on the first run. Resume must NOT re-call
+   * the planning LLM — re-asking would burn tokens and risk a different
+   * plan that no longer matches the executed-node ledger.
+   */
+  plan: PlannerPlan;
+  /**
+   * Per-node ledger (completed / failed / skipped). This IS the
+   * completed-node set — the sequential skip-guard and DAG re-seed both
+   * reconstruct "what ran" from it.
+   */
+  executedSteps: PlannerStepSnapshot[]; /** Rolled-up usage across executed nodes — never double-counted on resume. */
+  usage: Usage; /** Child reports accumulated across executed nodes. */
+  children: BaseReport[]; /** Replan budget consumed so far, so a resume can't exceed `maxReplans`. */
+  replanCount: number;
+  status: PlannerSnapshotStatus;
+  startedAt: string;
+  savedAt: string;
+};
+//#endregion
+export { PlannerSnapshot, PlannerSnapshotStatus };
+//# sourceMappingURL=planner-snapshot.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-snapshot.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-snapshot.type.ts"],"mappings":";;;;;;;;AAgBA;;;;AAAiC;AAqCjC;;;;KArCY,qBAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAoEH;;;;;;;KA/BG,eAAA;qDAEV,KAAA;EAEA,WAAA;EAEA,SAAA;EAEA,OAAA;EAEA,IAAA;;;;;;EAMA,IAAA,EAAM,WAAA;;;;;;EAMN,aAAA,EAAe,mBAAA;EAEf,KAAA,EAAO,KAAA;EAEP,QAAA,EAAU,UAAA;EAEV,WAAA;EACA,MAAA,EAAQ,qBAAA;EACR,SAAA;EACA,OAAA;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, PlannerResumeOptions } from "./planner-execute-options.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/planner/planner.contract.d.ts
 /**
@@ -54,6 +54,26 @@ interface PlannerContract<TOutput = unknown> extends ExecutableContract<string,
    * shape; runtime failures surface on `result.error`.
    */
   execute(goal: string, options?: PlannerExecuteOptions<TOutput>): Promise<PlannerResult<TOutput>>;
+  /**
+   * Resume a durable run after a crash. Loads the snapshot persisted
+   * under `runId` (requires `durable` on the config, or a global
+   * `defaultSnapshotStore`), re-hydrates the frozen plan + executed-node
+   * ledger + usage, and continues scheduling only the unfinished frontier
+   * — never re-calling the planning LLM and never re-dispatching a
+   * completed node's capability. A resume of an already-settled run
+   * re-returns the stored result without running anything.
+   *
+   * Refuses to continue when the current definition has structurally
+   * drifted from the snapshot (`PlannerDriftError`), unless
+   * `{ force: true }` is passed. Throws `PlannerFailedError` when no store
+   * is configured or no snapshot exists for `runId`.
+   *
+   * @example
+   * const result = await research.execute("compare A vs B", { runId: "plan-7" });
+   * // ...process crashes mid-run...
+   * const recovered = await research.resume("plan-7");
+   */
+  resume(runId: string, options?: PlannerResumeOptions<TOutput>): Promise<PlannerResult<TOutput>>;
 }
 //#endregion
 export { PlannerContract };

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

@@ -1 +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"}
+{"version":3,"file":"planner.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner.contract.ts"],"mappings":";;;;;;;AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,eAAA,4BAA2C,kBAAA,SAE1D,qBAAA,CAAsB,OAAA,GACtB,aAAA,CAAc,OAAA;EAmBW;EAAA,SAhBhB,IAAA;EAsCP;;;;;EAAA,SAhCO,SAAA;EAkCgB;;AAAO;;;EA3BhC,OAAA,CACE,IAAA,UACA,OAAA,GAAU,qBAAA,CAAsB,OAAA,IAC/B,OAAA,CAAQ,aAAA,CAAc,OAAA;;;;;;;;;;;;;;;;;;;;EAqBzB,MAAA,CACE,KAAA,UACA,OAAA,GAAU,oBAAA,CAAqB,OAAA,IAC9B,OAAA,CAAQ,aAAA,CAAc,OAAA;AAAA"}

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" | "image" | "speech" | "transcription" | "video" | "realtime";
 /**
  * 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;AAgDb;;;;AAAwB;AAAxB,KAzCY,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KAyCA,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  | \"image\"\n  | \"speech\"\n  | \"transcription\"\n  | \"video\"\n  | \"realtime\";\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/supervisor-result.type.d.mts

@@ -24,7 +24,14 @@ type SupervisorTerminatedBy = "router" | "route" | "classifier" | "evaluate" | "
  * on {@link BaseReport.children}, which duplicates nothing: it's the
  * reports of the child agents/workflows dispatched across iterations.
  */
-type SupervisorReport = Omit<BaseReport, "type"> & {
+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 = Omit<BaseReport, "type"> & {
  * 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,IAAA,CAAK,UAAA;EAClC,cAAA,UAGA;EADA,SAAA;EACA,YAAA,EAAc,sBAAA,EAId;EAFA,UAAA,UAGW;EADX,WAAA;EACA,SAAA,EAAW,iBAAA;EAgBX;;;AAA+B;AA+BjC;;EAxCE,GAAA,GAAM,WAAA;EAwC0C;;;;;;;;EA/BhD,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/workflow-result.type.d.mts

@@ -14,7 +14,8 @@ import { StepSnapshot } from "./step-result.type.mjs";
  * structure — one entry per defined step — while `children` gives
  * the cross-cutting tree view shared with other primitives.
  */
-type WorkflowReport = Omit<BaseReport, "type"> & {
+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,IAAA,CAAK,UAAA;EAChC,YAAA,UAQe;EANf,SAAA,UAHgC;EAKhC,WAAA,WAFA;EAIA,KAAA,EAAO,MAAA,SAAe,YAAA,GAAtB;EAEA,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/sdk-adapter.contract.d.mts

@@ -1,6 +1,9 @@
 import { ModelPricing } from "./result/model-pricing.type.mjs";
 import { ModelContract } from "./model.contract.mjs";
 import { EmbedderConfig, EmbedderContract } from "./embedder.contract.mjs";
+import { ImageModelConfig, ImageModelContract } from "./image-model.contract.mjs";
+import { SpeechModelConfig, SpeechModelContract } from "./speech-model.contract.mjs";
+import { TranscriptionModelConfig, TranscriptionModelContract } from "./transcription-model.contract.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/sdk-adapter.contract.d.ts
 /**
@@ -71,6 +74,40 @@ interface SDKAdapterContract {
    * const { vector } = await embedder.embed("Hello world");
    */
   embedder?(config: EmbedderConfig): EmbedderContract;
+  /**
+   * Create an image-generation model bound to this SDK's client.
+   * Optional — only providers with an image API expose it (OpenAI,
+   * Google today; Anthropic/Bedrock/Ollama do not). The structural
+   * absence of this method IS the capability guard: an adapter that
+   * can't generate images simply doesn't define it, so `ai.someSdk.image(...)`
+   * is a compile-time error rather than a silent runtime failure.
+   * Hand the returned model to `ai.image({ model, prompt })`.
+   *
+   * @example
+   * const model = openai.image({ name: "gpt-image-1" });
+   * const { data } = await ai.image({ model, prompt: "a red bicycle" });
+   */
+  image?(config: ImageModelConfig): ImageModelContract;
+  /**
+   * Create a text-to-speech model bound to this SDK's client, for use
+   * with `ai.speech({ model, text })`. Optional — only providers with a
+   * TTS API expose it. Structural absence is the capability guard.
+   *
+   * @example
+   * const tts = openai.speech({ name: "tts-1", voice: "alloy" });
+   * const { data } = await ai.speech({ model: tts, text: "Hello" });
+   */
+  speech?(config: SpeechModelConfig): SpeechModelContract;
+  /**
+   * Create a speech-to-text (transcription) model bound to this SDK's
+   * client, for use with `ai.transcribe({ model, audio })`. Optional —
+   * only providers with an STT API expose it.
+   *
+   * @example
+   * const stt = openai.transcribe({ name: "whisper-1" });
+   * const { data } = await ai.transcribe({ model: stt, audio });
+   */
+  transcribe?(config: TranscriptionModelConfig): TranscriptionModelContract;
 }
 //#endregion
 export { ModelConfig, SDKAdapterContract };

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

@@ -1 +1 @@
-{"version":3,"file":"sdk-adapter.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/sdk-adapter.contract.ts"],"mappings":";;;;;;;AAkBA;;;;;;;;;;;AAiBc;KAjBF,WAAA;EAkCuB,qEAhCjC,IAAA,UAqCc;EAnCd,WAAA,WA6CqC;EA3CrC,SAAA;EAsDmC;;;;;;;;EA7CnC,OAAA,GAAU,YAAY,EAkCF;EAAA,CAhCnB,GAAA;AAAA;;;;;AA2CkD;;;;;;;;;;UA1BpC,kBAAA;;;;;EAKf,KAAA,CAAM,MAAA,EAAQ,WAAA,GAAc,aAAA;;;;;;;;;EAU5B,KAAA,CAAM,IAAA,UAAc,KAAA,YAAiB,OAAA;;;;;;;;;;EAWrC,QAAA,EAAU,MAAA,EAAQ,cAAA,GAAiB,gBAAA;AAAA"}
+{"version":3,"file":"sdk-adapter.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/sdk-adapter.contract.ts"],"mappings":";;;;;;;;;;AAwBA;;;;;;;;;;;AAiBc;KAjBF,WAAA;EAkCuB,qEAhCjC,IAAA,UAqCc;EAnCd,WAAA,WA6CqC;EA3CrC,SAAA;EAsDmC;;;;;;;;EA7CnC,OAAA,GAAU,YAAY,EAwBtB;EAAA,CAtBC,GAAA;AAAA;;;;;;;;;;;;;;;UAiBc,kBAAA;EAoDP;;;;EA/CR,KAAA,CAAM,MAAA,EAAQ,WAAA,GAAc,aAAA;EA0DmB;;AAA0B;;;;;;EAhDzE,KAAA,CAAM,IAAA,UAAc,KAAA,YAAiB,OAAA;;;;;;;;;;EAWrC,QAAA,EAAU,MAAA,EAAQ,cAAA,GAAiB,gBAAA;;;;;;;;;;;;;;EAenC,KAAA,EAAO,MAAA,EAAQ,gBAAA,GAAmB,kBAAA;;;;;;;;;;EAWlC,MAAA,EAAQ,MAAA,EAAQ,iBAAA,GAAoB,mBAAA;;;;;;;;;;EAWpC,UAAA,EAAY,MAAA,EAAQ,wBAAA,GAA2B,0BAAA;AAAA"}