@warlock.js/ai 4.4.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

@@ -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.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/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/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"}

package/esm/contracts/system-prompt.contract.d.mts

@@ -1,4 +1,5 @@
 import { Placeholders } from "./placeholders.type.mjs";
+import { PromptValidationResult, PromptsValidateOptions } from "../prompts/prompts-manager.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/system-prompt.contract.d.ts
 /**
@@ -53,6 +54,53 @@ interface PersonaContract extends SystemPromptBlockContract {
 interface InstructionContract extends SystemPromptBlockContract {
   readonly type: "instruction";
 }
+/**
+ * Identity + provenance metadata attached to a `SystemPromptContract`.
+ *
+ * A prompt that carries a `name` becomes addressable in the `ai.prompts`
+ * registry (keyed by `name@version`); anonymous prompts (no `name`) are never
+ * registered and exist only for inline composition / display.
+ *
+ * `composedFrom` records the deterministic source labels a prompt was merged
+ * from (e.g. `["base@2", "global-instructions@1"]`) — provenance with no
+ * random suffixes, so the same merge always yields the same labels.
+ *
+ * @example
+ * const base = ai.systemPrompt("You are support.", {
+ *   name: "support",
+ *   version: "1",
+ *   description: "Tier-1 support persona.",
+ * });
+ */
+interface SystemPromptMeta {
+  /** Registry name. When present the prompt auto-registers in `ai.prompts`. */
+  readonly name?: string;
+  /** Registry version label. Defaults to the next integer when omitted. */
+  readonly version?: string;
+  /** Human-readable description of the prompt's purpose. */
+  readonly description?: string;
+  /** Deterministic source labels this prompt was composed from (e.g. `["base@2"]`). */
+  readonly composedFrom?: readonly string[];
+  /** Placeholder keys callers must supply when resolving this prompt. */
+  readonly required?: readonly string[];
+}
+/**
+ * Options for the registry-aware overload of {@link SystemPromptContract.merge}
+ * that folds in a named prompt resolved from `ai.prompts`.
+ */
+interface SystemPromptMergeOptions {
+  /**
+   * Which registered version to fold in when merging by name. Defaults to the
+   * latest registered version. Ignored when merging a contract instance.
+   */
+  readonly fromVersion?: string;
+}
+/**
+ * A source that {@link SystemPromptContract.merge} can fold in: a pre-built
+ * block, another prompt contract (its blocks are folded — persona replaces,
+ * instructions append), or a registered prompt name resolved from `ai.prompts`.
+ */
+type SystemPromptMergeSource = SystemPromptBlockContract | SystemPromptContract | string;
 /**
  * Immutable builder for composing a layered system prompt out of persona and
  * instruction blocks. Every mutating method returns a fresh builder — the
@@ -92,6 +140,29 @@ interface InstructionContract extends SystemPromptBlockContract {
 interface SystemPromptContract {
   /** All blocks in render order. Read-only snapshot — use `persona()` / `instruction()` to derive a new builder. */
   readonly blocks: readonly SystemPromptBlockContract[];
+  /**
+   * Identity + provenance metadata. Read it via the no-argument
+   * {@link SystemPromptContract.meta} accessor (`prompt.meta()`); it is
+   * present when the prompt was given a name (via `systemPrompt(input, meta)`
+   * or `.meta({ name })`) or acquired `composedFrom` provenance through a
+   * `merge`, and `undefined` for a bare anonymous prompt.
+   *
+   * Exposed as a method (not a bare field) because the same `meta` identifier
+   * also serves as the immutable updater — see the call signatures below.
+   */
+  /**
+   * No-argument form: read the current metadata snapshot (or `undefined` when
+   * the prompt is anonymous and carries no provenance).
+   */
+  meta(): SystemPromptMeta | undefined;
+  /**
+   * Updater form: return a new builder with `meta` merged onto the current
+   * metadata (shallow). Immutable — the original is untouched. Giving the
+   * result a `name` registers it in `ai.prompts` under `name@version`
+   * (version defaults to the next integer); renaming a forked prompt creates
+   * a new registry key while the original entry stays put.
+   */
+  meta(meta: SystemPromptMeta): SystemPromptContract;
   /**
    * Set (or replace) the persona block. Returns a new builder. If a persona
    * already exists it's replaced in place (preserving its position);
@@ -103,6 +174,30 @@ interface SystemPromptContract {
    * accumulate — instructions render in the order they were added.
    */
   instruction(instruction: InstructionContract | string): SystemPromptContract;
+  /**
+   * Merge N predefined blocks into the prompt in one call. Each block is
+   * folded in order through the same per-type rules as `persona()` /
+   * `instruction()`: a `persona` block sets/replaces the single, leading
+   * persona; every other block is appended in order. Accepts pre-built
+   * `ai.persona()` / `ai.instruction()` blocks (or any `SystemPromptBlockContract`)
+   * for reuse across prompts. Returns a new builder; the original is untouched.
+   */
+  merge(...blocks: readonly SystemPromptBlockContract[]): SystemPromptContract;
+  /**
+   * Fold in another prompt's blocks. A persona block replaces this prompt's
+   * persona; instruction (and any other) blocks append in order. The result's
+   * `meta.composedFrom` records the deterministic source labels of both this
+   * prompt and the folded one (e.g. `["base@2", "global-instructions@1"]`).
+   * Returns a new builder; the original is untouched.
+   */
+  merge(source: SystemPromptContract): SystemPromptContract;
+  /**
+   * Fold in a prompt resolved from the `ai.prompts` registry by name. Uses the
+   * latest registered version unless `options.fromVersion` selects another.
+   * Throws `InvalidRequestError` when the name (or requested version) is not
+   * registered. Provenance is recorded in `meta.composedFrom`.
+   */
+  merge(name: string, options?: SystemPromptMergeOptions): SystemPromptContract;
   /**
    * Resolve all placeholders across every block, producing the final system
    * prompt string. Blocks render in insertion order, separated by a blank line.
@@ -112,7 +207,14 @@ interface SystemPromptContract {
    * @param placeholders - Values to inject into `{{mustache}}` slots.
    */
   resolve(placeholders?: Placeholders): string;
+  /**
+   * Sugar over `ai.prompts.validate(this, options)`. Runs the deterministic
+   * placeholder check (missing required `{{keys}}`) and, when `options.judge`
+   * is a model, the Nova-safe LLM-as-judge quality pass. The result's `ok`
+   * reflects the deterministic verdict alone; a flaky judge never flips it.
+   */
+  validate(options?: PromptsValidateOptions): Promise<PromptValidationResult>;
 }
 //#endregion
-export { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract };
+export { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract, SystemPromptMergeOptions, SystemPromptMergeSource, SystemPromptMeta };
 //# sourceMappingURL=system-prompt.contract.d.mts.map

package/esm/contracts/system-prompt.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/system-prompt.contract.ts"],"mappings":";;;;;AAiBA;;;;;;;;;;AAQqC;AAarC;;UArBiB,yBAAA;EAqBwB;EAAA,SAnB9B,IAAA;EAoCM;EAAA,SAjCN,IAAA;;EAGT,OAAA,CAAQ,YAAA,GAAe,YAAY;AAAA;AAsErC;;;;;;;;;;AAAA,UAzDiB,eAAA,SAAwB,yBAAyB;EAAA,SACvD,IAAI;AAAA;;;;;;;;;;;;;AAiFsB;UAjEpB,mBAAA,SAA4B,yBAAyB;EAAA,SAC3D,IAAI;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAuCE,oBAAA;;WAEN,MAAA,WAAiB,yBAAA;;;;;;EAO1B,OAAA,CAAQ,OAAA,EAAS,eAAA,YAA2B,oBAAA;;;;;EAM5C,WAAA,CAAY,WAAA,EAAa,mBAAA,YAA+B,oBAAA;;;;;;;;;EAUxD,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA"}
+{"version":3,"file":"system-prompt.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/system-prompt.contract.ts"],"mappings":";;;;;;AAqBA;;;;;;;;;;AAQqC;AAarC;;UArBiB,yBAAA;EAqBwB;EAAA,SAnB9B,IAAA;EAoCM;EAAA,SAjCN,IAAA;;EAGT,OAAA,CAAQ,YAAA,GAAe,YAAY;AAAA;AAoDrC;;;;;;;;;;AAAA,UAvCiB,eAAA,SAAwB,yBAAyB;EAAA,SACvD,IAAI;AAAA;;;AAgEO;AAQtB;;;;AAEwB;AAuCxB;;;;;UAjGiB,mBAAA,SAA4B,yBAAyB;EAAA,SAC3D,IAAI;AAAA;;;;;;;;;;;;;;;;;;;UAqBE,gBAAA;EAuGf;EAAA,SArGS,IAAA;EAqGJ;EAAA,SAlGI,OAAA;EAyGT;EAAA,SAtGS,WAAA;EAsGD;EAAA,SAnGC,YAAA;EAyGT;EAAA,SAtGS,QAAA;AAAA;;;;;UAOM,wBAAA;EAkHf;;;;EAAA,SA7GS,WAAW;AAAA;;;;;;KAQV,uBAAA,GACR,yBAAA,GACA,oBAAoB;;;;;;;AAgIoD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAzF3D,oBAAA;;WAEN,MAAA,WAAiB,yBAAA;;;;;;;;;;;;;;;EAiB1B,IAAA,IAAQ,gBAAA;;;;;;;;EASR,IAAA,CAAK,IAAA,EAAM,gBAAA,GAAmB,oBAAA;;;;;;EAO9B,OAAA,CAAQ,OAAA,EAAS,eAAA,YAA2B,oBAAA;;;;;EAM5C,WAAA,CAAY,WAAA,EAAa,mBAAA,YAA+B,oBAAA;;;;;;;;;EAUxD,KAAA,IAAS,MAAA,WAAiB,yBAAA,KAA8B,oBAAA;;;;;;;;EASxD,KAAA,CAAM,MAAA,EAAQ,oBAAA,GAAuB,oBAAA;;;;;;;EAQrC,KAAA,CACE,IAAA,UACA,OAAA,GAAU,wBAAA,GACT,oBAAA;;;;;;;;;EAUH,OAAA,CAAQ,YAAA,GAAe,YAAA;;;;;;;EAQvB,QAAA,CAAS,OAAA,GAAU,sBAAA,GAAyB,OAAA,CAAQ,sBAAA;AAAA"}

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

@@ -0,0 +1 @@
+import { TeamConfig, TeamGate, TeamGateFn, TeamMemberValue } from "./team-config.type.mjs";