@warlock.js/ai 4.3.0 → 4.5.0

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";

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

@@ -0,0 +1,127 @@
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { FlowObserveOption } from "../../observe/resolve-observers.mjs";
+import { SnapshotStore } from "../orchestrator/snapshot-store.contract.mjs";
+import { WorkflowInstance } from "../workflow/workflow.contract.mjs";
+import { SystemPromptContract } from "../system-prompt.contract.mjs";
+import { RouterEntry } from "../supervisor/router-entry.type.mjs";
+import { SupervisorConfig, SupervisorEventHandlers } from "../supervisor/supervisor-config.type.mjs";
+import { EvaluateContext, EvaluateResult } from "../supervisor/evaluate-context.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../@warlock.js/ai/src/contracts/team/team-config.type.d.ts
+/**
+ * A role member — an agent or a workflow. The same shorthand the
+ * supervisor accepts on each `intents` value, narrowed to the two
+ * dispatchable unit shapes `team()` forwards verbatim. (Callback /
+ * full-entry intent shapes still work when forwarded — this alias is
+ * the documented, autocomplete-friendly subset for the common case.)
+ */
+type TeamMemberValue = AgentContract<unknown> | WorkflowInstance<unknown, unknown>;
+/**
+ * The built-in quality-gate strategies. Each desugars to a concrete
+ * {@link SupervisorConfig.evaluate} callback — no new loop or
+ * termination code; both lean entirely on the already-shipped
+ * {@link EvaluateResult} semantics (`satisfied` terminates,
+ * `reassignTo` re-dispatches the fixer, `feedback` threads forward).
+ *
+ * - `"quality"` — review-then-fix loop. After members settle, read the
+ *   reviewer's verdict slice (`state.approved` by default); if not
+ *   approved, `reassignTo` the fixer with the reviewer feedback
+ *   (`state.notes`) threaded forward. Terminates on approval.
+ * - `"verify"` — test-then-fix loop. Same shape but keyed on the
+ *   tester's pass/fail slice (`state.passed` by default) instead of a
+ *   subjective reviewer score.
+ */
+type TeamGate = "quality" | "verify";
+/**
+ * Fully-custom gate — an escape hatch identical to
+ * {@link SupervisorConfig.evaluate}. Supplying a function instead of a
+ * {@link TeamGate} string opts out of the sugar entirely while keeping
+ * the rest of `team()`'s wiring. Forwarded straight through as
+ * `evaluate` with zero wrapping.
+ */
+type TeamGateFn<TState> = (ctx: EvaluateContext<TState>) => EvaluateResult | Promise<EvaluateResult>;
+/**
+ * Config for `ai.team(config)` — thin, transparent sugar over
+ * {@link SupervisorConfig}. `team()` builds a `SupervisorConfig` from
+ * these fields and calls `supervisor(...)`, returning the **unchanged**
+ * `SupervisorContract<TOutput>`. It owns no loop: the manager becomes
+ * `route`/`router`, the members become `intents`, and the gate becomes
+ * `evaluate`. Everything else passes through 1:1.
+ *
+ * @example
+ * const codeTeam = ai.team({
+ *   name: "code-team",
+ *   goal: "Ship a tested module that passes review.",
+ *   manager: techLeadRouter,
+ *   members: { builder, reviewer, fixer },
+ *   gate: "quality",
+ *   output: v.object({ code: v.string() }),
+ *   maxIterations: 6,
+ * });
+ */
+type TeamConfig<TOutput = unknown, TState = TOutput, TMembers extends Record<string, TeamMemberValue> = Record<string, TeamMemberValue>> = {
+  /** Stable identifier — forwarded verbatim to `SupervisorConfig.name`. */name: string; /** Optional dev-curated version string — forwarded to `SupervisorConfig.version`. */
+  version?: string;
+  /**
+   * The manager. Drives dispatch each iteration. Two forms:
+   * - an `AgentContract` / `RouterEntry` → becomes `SupervisorConfig.router`
+   *   (LLM-driven manager).
+   * - `{ route }` → becomes `SupervisorConfig.route` (deterministic manager).
+   * Exactly one is forwarded; mutually exclusive (mirrors the
+   * supervisor's own `router` XOR `route` rule).
+   */
+  manager: AgentContract<unknown> | RouterEntry<TState> | {
+    route: NonNullable<SupervisorConfig<TOutput, TState>["route"]>;
+  };
+  /**
+   * Role members keyed by role name (e.g. `builder`, `reviewer`,
+   * `tester`, `fixer`). Forwarded verbatim as `SupervisorConfig.intents`.
+   * The keys are the role names the manager routes to AND the keys
+   * `ctx.intents.<role>` exposes (escape hatch preserved).
+   */
+  members: TMembers;
+  /**
+   * The quality gate. A {@link TeamGate} string selects a pre-built
+   * `evaluate` strategy; a function is forwarded straight to
+   * `SupervisorConfig.evaluate` (full escape hatch). Required — a team
+   * without a gate is just a supervisor.
+   */
+  gate: TeamGate | TeamGateFn<TState>;
+  /**
+   * Role-name mapping for the built-in string gates. Only consulted
+   * when `gate` is a {@link TeamGate} string. Defaults:
+   * `{ reviewer: "reviewer", fixer: "fixer", tester: "tester" }`.
+   * Override when your `members` keys differ from the canonical role
+   * names.
+   */
+  roles?: {
+    reviewer?: keyof TMembers & string;
+    fixer?: keyof TMembers & string;
+    tester?: keyof TMembers & string;
+  };
+  /**
+   * State key the gate reads to decide satisfaction. Defaults to
+   * `"approved"` for `gate: "quality"` and `"passed"` for
+   * `gate: "verify"`. The named member's `output` schema must write a
+   * boolean into this key.
+   */
+  gateKey?: string; /** Natural-language objective — forwarded verbatim to `SupervisorConfig.goal`. */
+  goal?: string | SystemPromptContract; /** Final-state schema — forwarded verbatim to `SupervisorConfig.output`. */
+  output?: StandardSchemaV1<TOutput>; /** Initial state seed — forwarded verbatim to `SupervisorConfig.state`. */
+  state?: TState; /** Hard iteration cap — forwarded verbatim; defaults to the supervisor's `10`. */
+  maxIterations?: number; /** Durable snapshot store — forwarded verbatim to `SupervisorConfig.snapshotStore`. */
+  snapshotStore?: SnapshotStore; /** Definition-level event handlers — forwarded verbatim to `SupervisorConfig.on`. */
+  on?: SupervisorEventHandlers;
+  /**
+   * Observability for this team — forwarded verbatim to
+   * `SupervisorConfig.observe`, so the underlying supervisor routes its
+   * completed report through the same generic `Observer` seam every
+   * other flow uses. Additive and gated; see `SupervisorConfig.observe`
+   * for the value semantics (`true` / `false` / a flow-local `Observer`).
+   */
+  observe?: FlowObserveOption;
+};
+//#endregion
+export { TeamConfig, TeamGate, TeamGateFn, TeamMemberValue };
+//# sourceMappingURL=team-config.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"team-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/team/team-config.type.ts"],"mappings":";;;;;;;;;;;;;AAiBA;;;;AAEoB;KAFR,eAAA,GACR,aAAA,YACA,gBAAgB;;;;AAiBA;AASpB;;;;;;;;;;;KATY,QAAA;;;;;;;AAWgC;KAFhC,UAAA,YACV,GAAA,EAAK,eAAA,CAAgB,MAAA,MAClB,cAAA,GAAiB,OAAA,CAAQ,cAAA;;;;;;;;;;;;;;;;;;;;KAqBlB,UAAA,6BAED,OAAA,mBACQ,MAAA,SAAe,eAAA,IAAmB,MAAA,SAAe,eAAA;EA+CjD,yEA5CjB,IAAA,UA6D0B;EA1D1B,OAAA;EA6DQ;;;;;;;;EAnDR,OAAA,EACI,aAAA,YACA,WAAA,CAAY,MAAA;IACV,KAAA,EAAO,WAAA,CAAY,gBAAA,CAAiB,OAAA,EAAS,MAAA;EAAA;EAnBnB;;;;;;EA2BhC,OAAA,EAAS,QAAA;EATL;;;;;;EAiBJ,IAAA,EAAM,QAAA,GAAW,UAAA,CAAW,MAAA;EAR5B;;;;;;;EAiBA,KAAA;IACE,QAAA,SAAiB,QAAA;IACjB,KAAA,SAAc,QAAA;IACd,MAAA,SAAe,QAAA;EAAA;EAAA;;;;;;EASjB,OAAA,WAWA;EANA,IAAA,YAAgB,oBAAA,EAShB;EANA,MAAA,GAAS,gBAAA,CAAiB,OAAA,GASV;EANhB,KAAA,GAAQ,MAAA,EASH;EANL,aAAA,WAeU;EAZV,aAAA,GAAgB,aAAA,EAYW;EAT3B,EAAA,GAAK,uBAAA;;;;;;;;EASL,OAAA,GAAU,iBAAA;AAAA"}

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

@@ -121,8 +121,10 @@ interface ToolConfig<TInput = unknown, TOutput = unknown> {
    *
    * Two forms:
    * - **string** — static, used as-is.
-   * - **function** — receives the validated input and returns a
-   *   string, so callers can include input data
+   * - **function** — receives the model's **raw, pre-validation**
+   *   input (resolved at the dispatch boundary, before `execute`'s
+   *   schema validation runs) and returns a string, so callers can
+   *   include input data
    *   (`(input) => \`Searching for "${input.query}"\``).
    *
    * Resolved at the framework boundary; consumers receive a

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

@@ -1 +1 @@
-{"version":3,"file":"tool.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/tool.contract.ts"],"mappings":";;;;;AAQA;;;;KAAY,QAAA,GAAW,MAAM;AAoC7B;;;;AAAoB;AAmCpB;;;;;;;;;;;;;;;AASsB;AAiBtB;;;;;;;;;;;;;AA7DA,KAAY,QAAA;;;;;;;;;;;;;;;;;;;;;;;;AAmHgD;;;;;;;;;;KAhFhD,WAAA,cAAyB,MAAA;;;;;;;EAOnC,SAAA,EAAW,UAAA;EAEX,MAAA,GAAS,WAAA;AAAA;;;;;;;;;;;;;;;UAiBM,UAAA;;EAEf,IAAA;;EAEA,WAAA;;;;;;;;EAQA,OAAA;;;;;;;;;;;;;;;;EAgBA,MAAA,cAAoB,KAAA,EAAO,MAAA;;EAE3B,IAAA,GAAO,QAAA;;;;;;;EAOP,IAAA,GAAO,QAAA;;;;;;EAMP,KAAA,GAAQ,gBAAA,CAAiB,MAAA;;;;;;;;;;;EAWzB,OAAA,CAAQ,KAAA,EAAO,MAAA,EAAQ,GAAA,GAAM,WAAA,GAAc,OAAA,CAAQ,OAAA;AAAA"}
+{"version":3,"file":"tool.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/tool.contract.ts"],"mappings":";;;;;AAQA;;;;KAAY,QAAA,GAAW,MAAM;AAoC7B;;;;AAAoB;AAmCpB;;;;;;;;;;;;;;;AASsB;AAiBtB;;;;;;;;;;;;;AA7DA,KAAY,QAAA;;;;;;;;;;;;;;;;;;;;;;;;AAqHgD;;;;;;;;;;KAlFhD,WAAA,cAAyB,MAAA;;;;;;;EAOnC,SAAA,EAAW,UAAA;EAEX,MAAA,GAAS,WAAA;AAAA;;;;;;;;;;;;;;;UAiBM,UAAA;;EAEf,IAAA;;EAEA,WAAA;;;;;;;;EAQA,OAAA;;;;;;;;;;;;;;;;;;EAkBA,MAAA,cAAoB,KAAA,EAAO,MAAA;;EAE3B,IAAA,GAAO,QAAA;;;;;;;EAOP,IAAA,GAAO,QAAA;;;;;;EAMP,KAAA,GAAQ,gBAAA,CAAiB,MAAA;;;;;;;;;;;EAWzB,OAAA,CAAQ,KAAA,EAAO,MAAA,EAAQ,GAAA,GAAM,WAAA,GAAc,OAAA,CAAQ,OAAA;AAAA"}

package/esm/contracts/workflow/step.contract.d.mts

@@ -169,13 +169,38 @@ type StepDefinition<TInput = unknown, TState = Record<string, unknown>, TContext
    */
   retry?: RetryConfig | false;
   /**
-   * Parallel children — run concurrently, share `ctx.state`
-   * (last-write-wins). Mutually exclusive with `run` and `agent`.
-   * The parent's snapshot is atomic: written only after every child
-   * settles. Children are addressable at both `ctx.steps.<child>` and
-   * `ctx.steps.<parent>.steps.<child>`.
+   * Parallel children — run concurrently, each starting from a snapshot
+   * of the parent `ctx.state`. After every child settles, their
+   * resulting states are merged back into the parent in **declaration
+   * order** (the order children appear in this array), so a key written
+   * by more than one child deterministically resolves to the
+   * **last-declared** child's value — regardless of which child finished
+   * first. Supply {@link mergeState} to customize conflict resolution
+   * (e.g. sum counters, concat arrays). Mutually exclusive with `run`
+   * and `agent`. The parent's snapshot is atomic: written only after
+   * every child settles. Children are addressable at both
+   * `ctx.steps.<child>` and `ctx.steps.<parent>.steps.<child>`.
    */
   parallel?: StepDefinition<TInput, TState, TContext>[];
+  /**
+   * Conflict resolver for {@link parallel} children that write the same
+   * `ctx.state` keys. Called once per child, in **declaration order**,
+   * with the accumulator (the parent state being built up), that child's
+   * resolved state, and the child's name. Mutate `acc` in place.
+   *
+   * Omit it to keep the deterministic default (last-declared child wins
+   * per key — a plain `Object.assign` in declaration order). Supply it
+   * for advanced merges:
+   *
+   * ```ts
+   * mergeState: (acc, childState) => {
+   *   acc.total = (acc.total ?? 0) + (childState.total ?? 0); // sum
+   * }
+   * ```
+   *
+   * Only consulted for parallel steps; ignored otherwise.
+   */
+  mergeState?: (acc: TState, childState: TState, childName: string) => void;
   /**
    * Per-step event handlers — fires alongside the workflow-level
    * `workflow.step.*` events. Scope is step-local (no `workflow.`

package/esm/contracts/workflow/step.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"step.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/workflow/step.contract.ts"],"mappings":";;;;;;;;;;;;AAaA;;KAAY,eAAA;EAAe,yEAEzB,QAAA;IAAY,IAAA;EAAA,GAGV;EADF,QAAA;IACE,IAAA;IACA,OAAA;IACA,aAAA;IACA,SAAA;EAAA,GAGsC;EAAxC,MAAA;IAAU,IAAA;IAAc,KAAA;IAAgB,QAAA;EAAA,GAEY;EAApD,SAAA;IAAa,IAAA;IAAc,MAAA;IAAiB,QAAA;EAAA;AAAA;;;;;;KAQlC,cAAA,GAAiB,mBAAmB;EAqBvC,8DAnBP,MAAM;AAAA;;;;;;;;;;KAYI,cAAA,+CAGD,MAAA;EAGT,OAAA,GACE,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,OAAA,GAAU,OAAA,CAAQ,OAAA;EACvB,MAAA,GAAS,gBAAA,CAAiB,OAAA;AAAA;;;;;;;;;;;AAAO;AAoBnC;;;;;;KAAY,cAAA,4BAED,MAAA;EAkBI;;;;;;EATb,IAAA;EAwB4B;;;;;;;EAf5B,IAAA,IAAQ,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,gBAAwB,OAAA;EAgCvD;;;;;;EAxBd,MAAA,IAAU,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EA+B3D;;;;;EAxBT,GAAA,IAAO,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA;EA4CX;;;;;;;EAnCjC,KAAA,GAAQ,aAAA;EAoDuB;;;;;;EA5C/B,KAAA,IAAS,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAAc,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAsDpD;;;;;EA/CjC,MAAA,GAAS,cAAA,UAAwB,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAgEvB;;;;;;EAxD1B,KAAA,IAAS,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EAgE9D;;;;;;;;;;EApDL,QAAA,IAAY,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAAc,cAAA,GAAiB,OAAA,CAAQ,cAAA;EA3DnD;;;;;;;;;;;;;;EA2ErC,SAAA,IACE,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,GACrC,KAAA,EAAO,OAAA,KACJ,cAAA,GAAiB,OAAA,CAAQ,cAAA;EA/Dc;;;;;;EAuE5C,QAAA,IAAY,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EAtDhC;;;;;;EA8DtC,KAAA,GAAQ,WAAA;EAvDC;;;;;;;EAgET,QAAA,GAAW,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAxDI;;;;;;EAgE9C,EAAA,GAAK,OAAA,eACS,eAAA,IAAmB,OAAA,EAAS,eAAA,CAAgB,CAAA;AAAA"}
+{"version":3,"file":"step.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/workflow/step.contract.ts"],"mappings":";;;;;;;;;;;;AAaA;;KAAY,eAAA;EAAe,yEAEzB,QAAA;IAAY,IAAA;EAAA,GAGV;EADF,QAAA;IACE,IAAA;IACA,OAAA;IACA,aAAA;IACA,SAAA;EAAA,GAGsC;EAAxC,MAAA;IAAU,IAAA;IAAc,KAAA;IAAgB,QAAA;EAAA,GAEY;EAApD,SAAA;IAAa,IAAA;IAAc,MAAA;IAAiB,QAAA;EAAA;AAAA;;;;;;KAQlC,cAAA,GAAiB,mBAAmB;EAqBvC,8DAnBP,MAAM;AAAA;;;;;;;;;;KAYI,cAAA,+CAGD,MAAA;EAGT,OAAA,GACE,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,OAAA,GAAU,OAAA,CAAQ,OAAA;EACvB,MAAA,GAAS,gBAAA,CAAiB,OAAA;AAAA;;;;;;;;;;;AAAO;AAoBnC;;;;;;KAAY,cAAA,4BAED,MAAA;EAkBI;;;;;;EATb,IAAA;EAwB4B;;;;;;;EAf5B,IAAA,IAAQ,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,gBAAwB,OAAA;EAgCvD;;;;;;EAxBd,MAAA,IAAU,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EA+B3D;;;;;EAxBT,GAAA,IAAO,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA;EA4CX;;;;;;;EAnCjC,KAAA,GAAQ,aAAA;EAoDuB;;;;;;EA5C/B,KAAA,IAAS,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAAc,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAsDpD;;;;;EA/CjC,MAAA,GAAS,cAAA,UAAwB,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAsEvB;;;;;;EA9D1B,KAAA,IAAS,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EA2FzB;;;;;;;;;;EA/E1C,QAAA,IAAY,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAAc,cAAA,GAAiB,OAAA,CAAQ,cAAA;EA3D3E;;;;;;;;;;;;;;EA2Eb,SAAA,IACE,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,GACrC,KAAA,EAAO,OAAA,KACJ,cAAA,GAAiB,OAAA,CAAQ,cAAA;EA/DF;;;;;;EAuE5B,QAAA,IAAY,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EAtDxD;;;;;;EA8Dd,KAAA,GAAQ,WAAA;EA9D6E;;;;;;;;;;;;;EA6ErF,QAAA,GAAW,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAlDzB;;;;;;;;;;;;;;;;;;EAsEjB,UAAA,IAAc,GAAA,EAAK,MAAA,EAAQ,UAAA,EAAY,MAAA,EAAQ,SAAA;EA3C/C;;;;;;EAmDA,EAAA,GAAK,OAAA,eACS,eAAA,IAAmB,OAAA,EAAS,eAAA,CAAgB,CAAA;AAAA"}

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

@@ -1,6 +1,7 @@
 import { ExecutableContract } from "../executable.contract.mjs";
 import { WorkflowResult } from "../result/workflow-result.type.mjs";
 import { ToolContract } from "../../tool/tool.mjs";
+import { FlowObserveOption } from "../../observe/resolve-observers.mjs";
 import { SnapshotStore } from "../orchestrator/snapshot-store.contract.mjs";
 import { NextStepResult } from "./next-step-result.type.mjs";
 import { RetryConfig } from "./retry-config.type.mjs";
@@ -99,6 +100,21 @@ type WorkflowDefinition<TInput = unknown, TOutput = unknown, TState = Record<str
   nextStep?: (stepName: string, ctx: WorkflowContext<TInput, TState, TContext>) => NextStepResult | Promise<NextStepResult>;
   output?: StepOutputSpec<TOutput, TInput, TState, TContext>;
   on?: WorkflowEventHandlers;
+  /**
+   * Observability for this workflow. Additive and gated — when omitted,
+   * the workflow 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 workflow out entirely, even when observe-all is on.
+   * - an `Observer` object → a flow-local collector receiving only this
+   *   workflow'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.
+   */
+  observe?: FlowObserveOption;
 };
 /**
  * Runtime handle returned by `ai.workflow(def)`. Implements the

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

@@ -1 +1 @@
-{"version":3,"file":"workflow.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/workflow/workflow.contract.ts"],"mappings":";;;;;;;;;;;;;KAYY,oBAAA,iBAAqC,gBAAA,KAC/C,OAAA,EAAS,gBAAA,CAAiB,CAAA;AAAA,KAGhB,qBAAA,GAAwB,OAAA,eACtB,gBAAA,GAAmB,oBAAA,CAAqB,CAAA;;;;;KAO1C,kBAAA;EAXiB,sEAa3B,KAAA,WAd+C;EAgB/C,MAAA,GAAS,WAAA,EAfiB;EAiB1B,EAAA,GAAK,qBAAA;EAjBuB;AAAA;AAG9B;;;;;EAsBE,OAAA,GAAU,QAAA;EAtBwB;;;;;;;EA8BlC,SAAA;AAAA;AA7BqD;AAOvD;;;;AAPuD,KAqC3C,sBAAA,yCAGR,kBAAA,CAAmB,QAAA;EACrB,KAAA,EAAO,MAAA;AAAA;AAAA,KAGG,qBAAA,uBACV,kBAAkB,CAAC,QAAA;EAtCU;;EAyC3B,KAAA;AAAA;AAAA,KAGQ,kBAAA,+CAGD,MAAA;EAGT,IAAA;EApCA;;;;AAQS;EAkCT,WAAA;EA1BgC;;;;;;;;;;EAqChC,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAC/B,OAAA;EACA,KAAA,EAAO,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAnCzB;AAAA;AAGf;;;;;;;;;EA4CE,aAAA,GAAgB,aAAA,CAAc,gBAAA;EArCpB;;;;;;;;;EA+CV,YAAA,GAAe,WAAA;EACf,QAAA;EACA,aAAA;EACA,QAAA,IACE,QAAA,UACA,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAC9B,MAAA,GAAS,cAAA,CAAe,OAAA,EAAS,MAAA,EAAQ,MAAA,EAAQ,QAAA;EACjD,EAAA,GAAK,qBAAA;AAAA;;;;;;;UASU,gBAAA,+CAGN,MAAA,+CAED,kBAAA,CACR,MAAA,EACA,kBAAA,CAAmB,QAAA,GACnB,cAAA,CAAe,OAAA;EAAA,SAEN,IAAA;EAAA,SACA,WAAA;EApBJ;;;;;;EAAA,SA2BI,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAAA,SAC/B,SAAA;EAAA,SACA,OAAA;EAxET;;;;;;;;;;;;;;EAwFA,OAAA,CACE,KAAA,EAAO,MAAA,EACP,OAAA,GAAU,kBAAA,CAAmB,QAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAC1B,OAAA,CACE,OAAA,EAAS,sBAAA,CAAuB,MAAA,EAAQ,QAAA,IACvC,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,MAAA,CACE,KAAA,UACA,OAAA,GAAU,qBAAA,CAAsB,QAAA,IAC/B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,EAAA,iBAAmB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EAC7E,GAAA,iBAAoB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EA9DvE;;;;;;;;;;;;;;;;EAgFP,MAAA,cAAoB,MAAA,EAAQ,OAAA;IAC1B,WAAA;IACA,WAAA,EAAa,gBAAA,CAAiB,UAAA;EAAA,IAC5B,YAAA,CAAa,UAAA,EAAY,OAAA;AAAA"}
+{"version":3,"file":"workflow.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/workflow/workflow.contract.ts"],"mappings":";;;;;;;;;;;;;;KAaY,oBAAA,iBAAqC,gBAAA,KAC/C,OAAA,EAAS,gBAAA,CAAiB,CAAA;AAAA,KAGhB,qBAAA,GAAwB,OAAA,eACtB,gBAAA,GAAmB,oBAAA,CAAqB,CAAA;;;;;KAO1C,kBAAA;EAXiB,sEAa3B,KAAA,WAd+C;EAgB/C,MAAA,GAAS,WAAA,EAfiB;EAiB1B,EAAA,GAAK,qBAAA;EAjBuB;AAAA;AAG9B;;;;;EAsBE,OAAA,GAAU,QAAA;EAtBwB;;;;;;;EA8BlC,SAAA;AAAA;AA7BqD;AAOvD;;;;AAPuD,KAqC3C,sBAAA,yCAGR,kBAAA,CAAmB,QAAA;EACrB,KAAA,EAAO,MAAA;AAAA;AAAA,KAGG,qBAAA,uBACV,kBAAkB,CAAC,QAAA;EAtCU;;EAyC3B,KAAA;AAAA;AAAA,KAGQ,kBAAA,+CAGD,MAAA;EAGT,IAAA;EApCA;;;;AAQS;EAkCT,WAAA;EA1BgC;;;;;;;;;;EAqChC,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAC/B,OAAA;EACA,KAAA,EAAO,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAnCzB;AAAA;AAGf;;;;;;;;;EA4CE,aAAA,GAAgB,aAAA,CAAc,gBAAA;EArCpB;;;;;;;;;EA+CV,YAAA,GAAe,WAAA;EACf,QAAA;EACA,aAAA;EACA,QAAA,IACE,QAAA,UACA,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAC9B,MAAA,GAAS,cAAA,CAAe,OAAA,EAAS,MAAA,EAAQ,MAAA,EAAQ,QAAA;EACjD,EAAA,GAAK,qBAAA;EAHkC;;;;;;;;;;;;;;EAkBvC,OAAA,GAAU,iBAAA;AAAA;;;;;;;UASK,gBAAA,+CAGN,MAAA,+CAED,kBAAA,CACR,MAAA,EACA,kBAAA,CAAmB,QAAA,GACnB,cAAA,CAAe,OAAA;EAAA,SAEN,IAAA;EAAA,SACA,WAAA;EAjET;;;;;;EAAA,SAwES,WAAA,GAAc,gBAAA,CAAiB,MAAA;EAAA,SAC/B,SAAA;EAAA,SACA,OAAA;EApDM;;;;;;;;;;;;;;EAoEf,OAAA,CACE,KAAA,EAAO,MAAA,EACP,OAAA,GAAU,kBAAA,CAAmB,QAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAC1B,OAAA,CACE,OAAA,EAAS,sBAAA,CAAuB,MAAA,EAAQ,QAAA,IACvC,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,MAAA,CACE,KAAA,UACA,OAAA,GAAU,qBAAA,CAAsB,QAAA,IAC/B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,EAAA,iBAAmB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EAC7E,GAAA,iBAAoB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EA1E9E;;;;;AAe2B;AAS7B;;;;;;;;;;EAoEE,MAAA,cAAoB,MAAA,EAAQ,OAAA;IAC1B,WAAA;IACA,WAAA,EAAa,gBAAA,CAAiB,UAAA;EAAA,IAC5B,YAAA,CAAa,UAAA,EAAY,OAAA;AAAA"}

package/esm/errors/error-code.type.d.mts

@@ -13,7 +13,7 @@
  *   return agent.execute(input);
  * }
  */
-type AIErrorCode = "AGENT_EXEC_FAILED" | "AGENT_CANCELLED" | "AGENT_MAX_TRIPS" | "SCHEMA_VALIDATION_FAILED" | "TOOL_EXEC_FAILED" | "PROVIDER_ERROR" | "PROVIDER_RATE_LIMIT" | "PROVIDER_QUOTA_EXCEEDED" | "PROVIDER_TIMEOUT" | "CONTEXT_LENGTH_EXCEEDED" | "CONTENT_FILTER" | "PROVIDER_INVALID_REQUEST" | "PROVIDER_AUTH" | "BUDGET_EXCEEDED" | "GUARDRAIL_VIOLATION" | "WORKFLOW_ERROR" | "STEP_FAILED" | "WORKFLOW_DRIFT" | "WORKFLOW_CANCELLED" | "WORKFLOW_MAX_STEPS" | "WORKFLOW_INVALID_GOTO" | "SUPERVISOR_FAILED" | "SUPERVISOR_MAX_ITERATIONS" | "SUPERVISOR_INVALID_ROUTE" | "SUPERVISOR_CANCELLED" | "SUPERVISOR_DRIFT" | "SUPERVISOR_INTENT_DESCRIPTION_REQUIRED" | "SUPERVISOR_INTENT_MIXED_DISPATCH" | "SUPERVISOR_INTENT_STREAM_AND_OUTPUT" | "SUPERVISOR_INTENT_STREAM_TO_REQUIRED" | "SUPERVISOR_INTENT_STREAM_ON_WORKFLOW" | "SUPERVISOR_DISPATCH_CYCLE" | "ORCHESTRATOR_FAILED" | "ORCHESTRATOR_DRIFT" | "ORCHESTRATOR_CONFIG" | "ORCHESTRATOR_CANCELLED" | "PLANNER_FAILED" | "PLANNER_PLAN_INVALID" | "PLANNER_CANCELLED";
+type AIErrorCode = "AGENT_EXEC_FAILED" | "AGENT_CANCELLED" | "AGENT_MAX_TRIPS" | "SCHEMA_VALIDATION_FAILED" | "TOOL_EXEC_FAILED" | "PROVIDER_ERROR" | "PROVIDER_RATE_LIMIT" | "PROVIDER_QUOTA_EXCEEDED" | "PROVIDER_TIMEOUT" | "CONTEXT_LENGTH_EXCEEDED" | "CONTENT_FILTER" | "PROVIDER_INVALID_REQUEST" | "PROVIDER_AUTH" | "BUDGET_EXCEEDED" | "GUARDRAIL_VIOLATION" | "WORKFLOW_ERROR" | "STEP_FAILED" | "WORKFLOW_DRIFT" | "WORKFLOW_CANCELLED" | "WORKFLOW_MAX_STEPS" | "WORKFLOW_INVALID_GOTO" | "SUPERVISOR_FAILED" | "SUPERVISOR_MAX_ITERATIONS" | "SUPERVISOR_INVALID_ROUTE" | "SUPERVISOR_CANCELLED" | "SUPERVISOR_DRIFT" | "SUPERVISOR_INTENT_DESCRIPTION_REQUIRED" | "SUPERVISOR_INTENT_MIXED_DISPATCH" | "SUPERVISOR_INTENT_STREAM_AND_OUTPUT" | "SUPERVISOR_INTENT_STREAM_TO_REQUIRED" | "SUPERVISOR_INTENT_STREAM_ON_WORKFLOW" | "SUPERVISOR_DISPATCH_CYCLE" | "ORCHESTRATOR_FAILED" | "ORCHESTRATOR_DRIFT" | "ORCHESTRATOR_CONFIG" | "ORCHESTRATOR_CANCELLED" | "PLANNER_FAILED" | "PLANNER_PLAN_INVALID" | "PLANNER_CANCELLED" | "VCR_CASSETTE_MISS" | "OUTBOUND_POLICY_BLOCKED";
 //#endregion
 export { AIErrorCode };
 //# sourceMappingURL=error-code.type.d.mts.map

package/esm/errors/index.d.mts

@@ -18,6 +18,7 @@ import { OrchestratorFailedError } from "./orchestrator-failed-error.mjs";
 import { OrchestratorCancelledError, OrchestratorCancelledErrorOptions } from "./orchestrator-cancelled-error.mjs";
 import { OrchestratorConfigError } from "./orchestrator-config-error.mjs";
 import { OrchestratorDriftError, OrchestratorDriftErrorOptions } from "./orchestrator-drift-error.mjs";
+import { OutboundPolicyError } from "./outbound-policy-error.mjs";
 import { PlannerFailedError } from "./planner-failed-error.mjs";
 import { PlannerCancelledError, PlannerCancelledErrorOptions } from "./planner-cancelled-error.mjs";
 import { PlannerPlanInvalidError } from "./planner-plan-invalid-error.mjs";

package/esm/errors/index.mjs

@@ -16,6 +16,7 @@ import { OrchestratorFailedError } from "./orchestrator-failed-error.mjs";
 import { OrchestratorCancelledError } from "./orchestrator-cancelled-error.mjs";
 import { OrchestratorConfigError } from "./orchestrator-config-error.mjs";
 import { OrchestratorDriftError } from "./orchestrator-drift-error.mjs";
+import { OutboundPolicyError } from "./outbound-policy-error.mjs";
 import { PlannerFailedError } from "./planner-failed-error.mjs";
 import { PlannerCancelledError } from "./planner-cancelled-error.mjs";
 import { PlannerPlanInvalidError } from "./planner-plan-invalid-error.mjs";

package/esm/errors/outbound-policy-error.d.mts

@@ -0,0 +1,27 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIError, AIErrorOptions } from "./ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/outbound-policy-error.d.ts
+/**
+ * A server-side outbound request (attachment fetch, URL skill manifest,
+ * RAG loader, …) was blocked by the shared `OutboundPolicy` before it
+ * left the process — a disallowed scheme, a host outside the allowlist, a
+ * private / loopback / link-local / cloud-metadata address resolved after
+ * DNS, an oversized body, or a timeout.
+ *
+ * This is the framework's SSRF / resource-exhaustion guard surfacing: the
+ * request was refused on purpose, not a provider failure. `context`
+ * carries the offending `url` / `host` / `reason` for logs.
+ *
+ * @example
+ * if (error instanceof OutboundPolicyError) {
+ *   logger.warn("blocked outbound fetch", { context: error.context });
+ * }
+ */
+declare class OutboundPolicyError extends AIError {
+  static readonly defaultCategory: ErrorCategory;
+  constructor(message: string, options?: AIErrorOptions);
+}
+//#endregion
+export { OutboundPolicyError };
+//# sourceMappingURL=outbound-policy-error.d.mts.map

package/esm/errors/outbound-policy-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-policy-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/outbound-policy-error.ts"],"mappings":";;;;;;AAmBA;;;;;;;;;;;;;;cAAa,mBAAA,SAA4B,OAAA;EAAA,gBAChB,eAAA,EAAiB,aAAA;cAErB,OAAA,UAAiB,OAAA,GAAU,cAAA;AAAA"}

package/esm/errors/outbound-policy-error.mjs

@@ -0,0 +1,32 @@
+import { AIError } from "./ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/outbound-policy-error.ts
+/**
+* A server-side outbound request (attachment fetch, URL skill manifest,
+* RAG loader, …) was blocked by the shared `OutboundPolicy` before it
+* left the process — a disallowed scheme, a host outside the allowlist, a
+* private / loopback / link-local / cloud-metadata address resolved after
+* DNS, an oversized body, or a timeout.
+*
+* This is the framework's SSRF / resource-exhaustion guard surfacing: the
+* request was refused on purpose, not a provider failure. `context`
+* carries the offending `url` / `host` / `reason` for logs.
+*
+* @example
+* if (error instanceof OutboundPolicyError) {
+*   logger.warn("blocked outbound fetch", { context: error.context });
+* }
+*/
+var OutboundPolicyError = class extends AIError {
+	static {
+		this.defaultCategory = "validation";
+	}
+	constructor(message, options) {
+		super("OUTBOUND_POLICY_BLOCKED", message, options);
+		this.name = "OutboundPolicyError";
+	}
+};
+
+//#endregion
+export { OutboundPolicyError };
+//# sourceMappingURL=outbound-policy-error.mjs.map

package/esm/errors/outbound-policy-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-policy-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/outbound-policy-error.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\n\n/**\n * A server-side outbound request (attachment fetch, URL skill manifest,\n * RAG loader, …) was blocked by the shared `OutboundPolicy` before it\n * left the process — a disallowed scheme, a host outside the allowlist, a\n * private / loopback / link-local / cloud-metadata address resolved after\n * DNS, an oversized body, or a timeout.\n *\n * This is the framework's SSRF / resource-exhaustion guard surfacing: the\n * request was refused on purpose, not a provider failure. `context`\n * carries the offending `url` / `host` / `reason` for logs.\n *\n * @example\n * if (error instanceof OutboundPolicyError) {\n *   logger.warn(\"blocked outbound fetch\", { context: error.context });\n * }\n */\nexport class OutboundPolicyError extends AIError {\n  public static readonly defaultCategory: ErrorCategory = \"validation\";\n\n  public constructor(message: string, options?: AIErrorOptions) {\n    super(\"OUTBOUND_POLICY_BLOCKED\", message, options);\n    this.name = \"OutboundPolicyError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,IAAa,sBAAb,cAAyC,QAAQ;;yBACS;;CAExD,AAAO,YAAY,SAAiB,SAA0B;EAC5D,MAAM,2BAA2B,SAAS,OAAO;EACjD,KAAK,OAAO;CACd;AACF"}

package/esm/eval/dataset.d.mts

@@ -0,0 +1,28 @@
+import { DatasetContract, DatasetOptions } from "./dataset.type.mjs";
+
+//#region ../@warlock.js/ai/src/eval/dataset.d.ts
+/**
+ * Create an immutable evaluation dataset that feeds `agent.eval({ cases })`
+ * directly.
+ *
+ * **Role.** A taggable, filterable, shardable wrapper around a list of
+ * {@link DatasetEntry} rows. `agent.eval` accepts a `DatasetContract` in
+ * place of a raw `EvalCase[]`, reading `.cases` off it.
+ *
+ * Sources (combinable — file entries append after inline `cases`):
+ * - `cases` → inline entries.
+ * - `fromFile` → a JSONL file read once, synchronously, at construction
+ *   (one JSON object per line). A malformed line throws an
+ *   `InvalidRequestError` naming the 1-based line number.
+ *
+ * @example
+ * const ds = dataset({ name: "support", fromFile: "./eval/support.jsonl" });
+ * const smoke = ds.filter((entry) => entry.tags?.includes("smoke"));
+ * const shard = ds.shard(0, 4); // first of four parallel CI shards
+ *
+ * const report = await agent.eval({ cases: ds, scorers: [contains()] });
+ */
+declare function dataset<TOutput = unknown>(options: DatasetOptions<TOutput>): DatasetContract<TOutput>;
+//#endregion
+export { dataset };
+//# sourceMappingURL=dataset.d.mts.map

package/esm/eval/dataset.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/eval/dataset.ts"],"mappings":";;;;;AAkIA;;;;;;;;;;;;;;;;AAE0B;;;iBAFV,OAAA,oBACd,OAAA,EAAS,cAAA,CAAe,OAAA,IACvB,eAAA,CAAgB,OAAA"}