@warlock.js/ai 4.3.0 → 4.5.0

package/esm/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { CheckpointStore } from \"./contracts/orchestrator/checkpoint-store.contract\";\nimport type { SnapshotStore } from \"./contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n */\nexport type AIConfig = {\n  /**\n   * Default `@warlock.js/cache` driver for cache-backed consumers that\n   * didn't supply their own `store` — currently the `semanticCache`\n   * middleware's vector store. Declaring it once here removes the\n   * repetition across middleware declarations.\n   *\n   * NOT the snapshot-persistence fallback anymore. Supervisor /\n   * workflow / orchestrator resume snapshots resolve through\n   * {@link AIConfig.defaultSnapshotStore} (a {@link SnapshotStore}),\n   * never this driver.\n   *\n   * Per-declaration overrides (`semanticCache({ store })`) win when\n   * supplied. Set this once at app boot, *after* you've constructed\n   * your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n\n  /**\n   * Default {@link CheckpointStore} for every orchestrator that didn't\n   * supply its own `checkpointStore` (orchestrator.md §15.2). Holds\n   * durable session state — `state`, `turn_index`, drift `signature`,\n   * compaction locks. Per-orchestrator `checkpointStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultCheckpointStore: ai.checkpoint.memory() });\n   */\n  defaultCheckpointStore?: CheckpointStore;\n\n  /**\n   * Default {@link SnapshotStore} for every orchestrator that didn't\n   * supply its own `snapshotStore` (orchestrator.md §15.2). Holds the\n   * internal supervisor run state used to resume an interrupted\n   * `iterate: true` turn. Per-orchestrator `snapshotStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });\n   */\n  defaultSnapshotStore?: SnapshotStore;\n};\n\nconst aiConfig: AIConfig = {};\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  return { ...aiConfig };\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective `@warlock.js/cache` driver for a cache-backed\n * consumer that didn't receive an explicit one. Returns the global\n * `defaultStore` if set, otherwise `undefined`. The semantic-cache\n * middleware treats `undefined` as fatal and throws. Snapshot\n * persistence no longer consults this — it resolves through\n * {@link resolveDefaultSnapshotStore}.\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n\n/**\n * Resolve the global default {@link CheckpointStore} for an\n * orchestrator that didn't receive an explicit `checkpointStore`.\n * Returns `undefined` when none is configured — the orchestrator\n * factory decides whether that's fatal.\n */\nexport function resolveDefaultCheckpointStore(): CheckpointStore | undefined {\n  return aiConfig.defaultCheckpointStore;\n}\n\n/**\n * Resolve the global default {@link SnapshotStore} for an orchestrator\n * that didn't receive an explicit `snapshotStore`. Returns `undefined`\n * when none is configured — the orchestrator factory decides whether\n * that's fatal (it is, when `iterate: true`).\n */\nexport function resolveDefaultSnapshotStore(): SnapshotStore | undefined {\n  return aiConfig.defaultSnapshotStore;\n}\n"],"mappings":";AAgFA,MAAM,WAAqB,CAAC;;;;;;;;;;;;;;;;AAiB5B,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;AAOA,SAAgB,cAAwB;CACtC,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;;;;AAUA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,gCAA6D;CAC3E,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,8BAAyD;CACvE,OAAO,SAAS;AAClB"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/config.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { CheckpointStore } from \"./contracts/orchestrator/checkpoint-store.contract\";\nimport type { SnapshotStore } from \"./contracts/orchestrator/snapshot-store.contract\";\n\n/**\n * Process-wide `@warlock.js/ai` configuration. **Intentionally tiny.**\n * Lives here only for genuinely cross-cutting defaults that would\n * otherwise force users to wire the same value into every consumer.\n *\n * **What lives here.** A field earns a slot only when it satisfies\n * all three:\n * 1. Multiple unrelated consumers need the same value.\n * 2. The value is infrastructure (drivers, clients, pools), not\n *    behavior (kill-switches, mode flags).\n * 3. Per-call override doesn't make sense for the use case.\n *\n * **What does NOT live here.** Logger config (use\n * `@warlock.js/logger` directly). Per-primitive feature flags\n * (live on the relevant config type). Anything that's really one\n * consumer's concern (lives on that consumer).\n *\n * Phase 3.2 deliberately removed the previous `configureAI()` bag\n * because it was growing unbounded. Treat new fields here with the\n * same suspicion.\n *\n * **Augmentable.** Declared as an `interface` (not a `type` alias) so\n * observability/tooling packages can attach their own opaque config slot\n * via declaration merging WITHOUT core importing them — keeping core\n * dependency-free. For example `@warlock.js/ai-panoptic` adds a\n * `panoptic?` field:\n *\n * ```ts\n * declare module \"@warlock.js/ai\" {\n *   interface AIConfig {\n *     panoptic?: PanopticConfig;\n *   }\n * }\n * ```\n *\n * `setAIConfig` stores the whole object via `Object.assign`, so any\n * augmented field is preserved even though core never reads it.\n */\nexport interface AIConfig {\n  /**\n   * Default `@warlock.js/cache` driver for cache-backed consumers that\n   * didn't supply their own `store` — currently the `semanticCache`\n   * middleware's vector store. Declaring it once here removes the\n   * repetition across middleware declarations.\n   *\n   * NOT the snapshot-persistence fallback anymore. Supervisor /\n   * workflow / orchestrator resume snapshots resolve through\n   * {@link AIConfig.defaultSnapshotStore} (a {@link SnapshotStore}),\n   * never this driver.\n   *\n   * Per-declaration overrides (`semanticCache({ store })`) win when\n   * supplied. Set this once at app boot, *after* you've constructed\n   * your driver.\n   *\n   * @example\n   * import { cache } from \"@warlock.js/cache\";\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({\n   *   defaultStore: cache.driver(\"redis\", { client: redisClient }),\n   * });\n   */\n  defaultStore?: CacheDriver<any, any>;\n\n  /**\n   * Default {@link CheckpointStore} for every orchestrator that didn't\n   * supply its own `checkpointStore` (orchestrator.md §15.2). Holds\n   * durable session state — `state`, `turn_index`, drift `signature`,\n   * compaction locks. Per-orchestrator `checkpointStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultCheckpointStore: ai.checkpoint.memory() });\n   */\n  defaultCheckpointStore?: CheckpointStore;\n\n  /**\n   * Default {@link SnapshotStore} for every orchestrator that didn't\n   * supply its own `snapshotStore` (orchestrator.md §15.2). Holds the\n   * internal supervisor run state used to resume an interrupted\n   * `iterate: true` turn. Per-orchestrator `snapshotStore` wins when\n   * supplied. Set once at app boot.\n   *\n   * @example\n   * import { ai } from \"@warlock.js/ai\";\n   *\n   * ai.config({ defaultSnapshotStore: ai.snapshot.memory() });\n   */\n  defaultSnapshotStore?: SnapshotStore;\n};\n\nconst aiConfig: AIConfig = {};\n\n/** A listener notified after every `setAIConfig` merge. */\ntype ConfigListener = (config: AIConfig) => void;\n\nconst configListeners: ConfigListener[] = [];\n\n/**\n * Subscribe to config changes. The listener fires after every\n * {@link setAIConfig} merge with a fresh snapshot of the full config —\n * the seam observability/tooling packages use to react when their\n * augmented slot (e.g. `panoptic`) is set, WITHOUT core importing them.\n *\n * Mirrors the dependency-inversion of the `Observer` registry: core\n * exposes the structural hook; the tool subscribes on its side-effect\n * import. To also catch config that was applied *before* the subscription,\n * read {@link getAIConfig} once right after subscribing.\n *\n * @example\n * import { onConfigApplied, getAIConfig } from \"@warlock.js/ai\";\n * onConfigApplied((config) => applyPanopticConfig(config.panoptic));\n * applyPanopticConfig(getAIConfig().panoptic); // catch pre-set config\n */\nexport function onConfigApplied(listener: ConfigListener): void {\n  configListeners.push(listener);\n}\n\n/**\n * Set or extend process-wide AI configuration. Merges over existing\n * values — fields not present in `partial` keep whatever was set\n * before (or stay unset). Call once at app boot, before constructing\n * any agent / supervisor / middleware that should pick up the\n * defaults.\n *\n * Returns the merged config so callers can verify what landed.\n *\n * @example\n * import { cache } from \"@warlock.js/cache\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * ai.config({ defaultStore: cache.driver(\"redis\", { client }) });\n */\nexport function setAIConfig(partial: Partial<AIConfig>): AIConfig {\n  Object.assign(aiConfig, partial);\n  const snapshot = { ...aiConfig };\n\n  // Notify subscribers (e.g. panoptic) after the merge. Errors are\n  // swallowed so a misbehaving listener never breaks config application,\n  // mirroring the observer / onUsage swallow-on-throw discipline.\n  for (const listener of configListeners) {\n    try {\n      listener(snapshot);\n    } catch {\n      // intentionally ignored\n    }\n  }\n\n  return snapshot;\n}\n\n/**\n * Read the current AI config snapshot. Returns a shallow copy so\n * callers can't accidentally mutate the source of truth. Used\n * internally by consumers to resolve their `defaultStore` fallback.\n */\nexport function getAIConfig(): AIConfig {\n  return { ...aiConfig };\n}\n\n/**\n * Resolve the effective `@warlock.js/cache` driver for a cache-backed\n * consumer that didn't receive an explicit one. Returns the global\n * `defaultStore` if set, otherwise `undefined`. The semantic-cache\n * middleware treats `undefined` as fatal and throws. Snapshot\n * persistence no longer consults this — it resolves through\n * {@link resolveDefaultSnapshotStore}.\n */\nexport function resolveDefaultStore(): CacheDriver<any, any> | undefined {\n  return aiConfig.defaultStore;\n}\n\n/**\n * Resolve the global default {@link CheckpointStore} for an\n * orchestrator that didn't receive an explicit `checkpointStore`.\n * Returns `undefined` when none is configured — the orchestrator\n * factory decides whether that's fatal.\n */\nexport function resolveDefaultCheckpointStore(): CheckpointStore | undefined {\n  return aiConfig.defaultCheckpointStore;\n}\n\n/**\n * Resolve the global default {@link SnapshotStore} for an orchestrator\n * that didn't receive an explicit `snapshotStore`. Returns `undefined`\n * when none is configured — the orchestrator factory decides whether\n * that's fatal (it is, when `iterate: true`).\n */\nexport function resolveDefaultSnapshotStore(): SnapshotStore | undefined {\n  return aiConfig.defaultSnapshotStore;\n}\n"],"mappings":";AAiGA,MAAM,WAAqB,CAAC;AAK5B,MAAM,kBAAoC,CAAC;;;;;;;;;;;;;;;;;AAkB3C,SAAgB,gBAAgB,UAAgC;CAC9D,gBAAgB,KAAK,QAAQ;AAC/B;;;;;;;;;;;;;;;;AAiBA,SAAgB,YAAY,SAAsC;CAChE,OAAO,OAAO,UAAU,OAAO;CAC/B,MAAM,WAAW,EAAE,GAAG,SAAS;CAK/B,KAAK,MAAM,YAAY,iBACrB,IAAI;EACF,SAAS,QAAQ;CACnB,QAAQ,CAER;CAGF,OAAO;AACT;;;;;;AAOA,SAAgB,cAAwB;CACtC,OAAO,EAAE,GAAG,SAAS;AACvB;;;;;;;;;AAUA,SAAgB,sBAAyD;CACvE,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,gCAA6D;CAC3E,OAAO,SAAS;AAClB;;;;;;;AAQA,SAAgB,8BAAyD;CACvE,OAAO,SAAS;AAClB"}

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

@@ -1,3 +1,4 @@
+import { AttachmentPolicy } from "../attachment-policy.type.mjs";
 import { Attachment } from "../attachment.type.mjs";
 import { Message } from "../conversation-message.type.mjs";
 import { ToolContext } from "../tool.contract.mjs";
@@ -12,9 +13,9 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * Options passed to AgentContract.execute() to configure a single execution run.
  *
  * @example
- * const result = await agent.execute("Analyze this document", {
+ * const result = await agent.execute("Describe this image", {
  *   history: previousMessages,
- *   attachments: ["/path/to/doc.pdf"],
+ *   attachments: ["/path/to/screenshot.png"],
  *   placeholders: { language: "English" },
  *   output: z.object({ summary: z.string(), keyPoints: z.array(z.string()) }),
  *   on: {
@@ -25,7 +26,14 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  */
 type AgentExecuteOptions<TOutput = unknown> = {
   /** Prior conversation messages to prepend as context */history?: Message[]; /** Files or URLs to attach to the message */
-  attachments?: Attachment[]; /** Values to inject into {{mustache}} placeholders in prompts */
+  attachments?: Attachment[];
+  /**
+   * Trust-boundary policy for {@link attachments} (S1) — overrides
+   * `AgentConfig.attachmentPolicy` for this call. Governs remote-text
+   * fetch (default-deny), the outbound `OutboundPolicy`, and the local-
+   * file `allowedRoots` sandbox. Omit to inherit the factory policy.
+   */
+  attachmentPolicy?: AttachmentPolicy; /** Values to inject into {{mustache}} placeholders in prompts */
   placeholders?: Placeholders;
   /**
    * Standard Schema for structured output extraction.

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

@@ -1 +1 @@
-{"version":3,"file":"agent-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-options.type.ts"],"mappings":";;;;;;;;;;;;AAwBA;;;;;;;;;;;;;KAAY,mBAAA;EA2EL,wDAzEL,OAAA,GAAU,OAAA,IA+FW;EA7FrB,WAAA,GAAc,UAAA,IA6F+B;EA3F7C,YAAA,GAAe,YAAA;EAJf;;;;EASA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EALX;;;;;;;;;;;;;;;;;;;;;;;;EA8Bf,cAAA,GAAiB,MAAA;EA0ER;;;;;;;;;;;;;;;;;;;;EArDT,MAAA;8EAEE,WAAA;EAAA;EAGF,YAAA,GAAe,oBAAA;;;;;;;;;;;EAWf,MAAA,GAAS,WAAA;EAET,EAAA,GAAK,OAAA,eACS,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;EAatD,OAAA,GAAU,WAAA;;;;;;;;EAQV,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;EAarB,SAAA;AAAA"}
+{"version":3,"file":"agent-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-options.type.ts"],"mappings":";;;;;;;;;;;;;AAyBA;;;;;;;;;;;;;KAAY,mBAAA;EAmF4C,wDAjFtD,OAAA,GAAU,OAAA,IA8FA;EA5FV,WAAA,GAAc,UAAA;EAoG+B;;;;;;EA7F7C,gBAAA,GAAmB,gBAAA,EAAnB;EAEA,YAAA,GAAe,YAAA;EAAf;;;;EAKA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EAyB1B;;;;;;;;;;;;;;;;;;;;;AA0ES;;;EA1ET,cAAA,GAAiB,MAAA;;;;;;;;;;;;;;;;;;;;;EAqBjB,MAAA;8EAEE,WAAA;EAAA;EAGF,YAAA,GAAe,oBAAA;;;;;;;;;;;EAWf,MAAA,GAAS,WAAA;EAET,EAAA,GAAK,OAAA,eACS,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;EAatD,OAAA,GAAU,WAAA;;;;;;;;EAQV,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;EAarB,SAAA;AAAA"}

package/esm/contracts/agent/eval.type.d.mts

@@ -1,4 +1,5 @@
 import { AgentResult } from "../result/agent-result.type.mjs";
+import { DatasetContract } from "../../eval/dataset.type.mjs";
 import { AgentContract } from "./agent.contract.mjs";
 import { AgentExecuteOptions } from "./agent-options.type.mjs";
 
@@ -92,7 +93,12 @@ type EvalJudge = {
  * resolvable per case or the runner throws at author time.
  */
 type EvalOptions<TOutput = unknown> = {
-  /** The evaluation cases to run. */cases: EvalCase<TOutput>[]; /** Default scorers applied to every case without its own `scorers`. */
+  /**
+   * The evaluation cases to run. Either a raw `EvalCase[]` or a
+   * {@link DatasetContract} (from `ai.dataset(...)`) — the runner reads
+   * `.cases` off a dataset.
+   */
+  cases: EvalCase<TOutput>[] | DatasetContract<TOutput>; /** Default scorers applied to every case without its own `scorers`. */
   scorers?: EvalScorer<TOutput>[]; /** LLM-as-judge fallback for cases with no scorers. */
   judge?: EvalJudge;
   /**
@@ -108,6 +114,36 @@ type EvalOptions<TOutput = unknown> = {
    */
   onFailure?: (caseResult: EvalCaseResult<TOutput>) => void | Promise<void>; /** Execute-options applied to every case (merged under per-case `options`). */
   executeOptions?: AgentExecuteOptions<TOutput>;
+  /**
+   * A prior {@link EvalReport} to diff against. When set, the new report
+   * carries a `regression` block flagging cases whose score dropped more
+   * than `tolerance` below the baseline.
+   */
+  baseline?: EvalReport<TOutput>;
+  /**
+   * Maximum allowed per-case score drop vs baseline before it counts as a
+   * regression. Only consulted when `baseline` is set. Defaults to `0`
+   * (any drop is a regression).
+   */
+  tolerance?: number;
+};
+/**
+ * Regression verdict attached to an {@link EvalReport} when `agent.eval`
+ * is called with a `baseline`. Cases are joined by `name`.
+ */
+type EvalRegression = {
+  /**
+   * Cases whose score fell more than `tolerance` below the baseline,
+   * carrying the before/after scores.
+   */
+  regressed: Array<{
+    name: string;
+    before: number;
+    after: number;
+  }>; /** Case names present in the baseline but absent in the new report. */
+  removed: string[]; /** Case names present in the new report but absent in the baseline. */
+  added: string[]; /** `true` when `regressed` is empty — no case regressed beyond tolerance. */
+  passed: boolean;
 };
 /**
  * Per-case outcome in an {@link EvalReport}. Bundles the case, the
@@ -137,7 +173,12 @@ type EvalReport<TOutput = unknown> = {
   passed: boolean; /** Per-case results in suite order. */
   cases: EvalCaseResult<TOutput>[]; /** Total wall-clock duration of the whole suite in milliseconds. */
   duration: number;
+  /**
+   * Regression diff vs a baseline. Present only when `agent.eval` was
+   * called with a `baseline`.
+   */
+  regression?: EvalRegression;
 };
 //#endregion
-export { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalReport, EvalScore, EvalScorer, EvalScorerContext };
+export { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalRegression, EvalReport, EvalScore, EvalScorer, EvalScorerContext };
 //# sourceMappingURL=eval.type.d.mts.map

package/esm/contracts/agent/eval.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"eval.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/eval.type.ts"],"mappings":";;;;;;;AAWA;;;;;KAAY,SAAA;EASV,6CAPA,KAAA;EAOM;AASR;;;EAXE,MAAA,YAaM;EAXN,MAAA;AAAA;;;;;;;KASU,iBAAA;EAIV,uCAFA,IAAA,EAAM,QAAA,CAAS,OAAA,GAEK;EAApB,MAAA,EAAQ,WAAA,CAAY,OAAA,GAEX;EAAT,MAAA,GAAS,OAAA,EAEL;EAAJ,IAAA;AAAA;;;;;;;KASU,UAAA,uBACV,OAAA,EAAS,iBAAA,CAAkB,OAAA,MACxB,SAAA,GAAY,OAAA,CAAQ,SAAA;;;;;;;KAQb,QAAA;EARK,+DAUf,IAAA,UAVgC;EAYhC,KAAA;EAJU;;;;;EAUV,QAAA,YAIU;EAFV,OAAA,GAAU,UAAA,CAAW,OAAA,KAEQ;EAA7B,OAAA,GAAU,mBAAA,CAAoB,OAAA;AAAA;;;;;;;;;;AAAO;AAevC;;KAAY,SAAA;EAEU,+DAApB,KAAA,EAAO,aAAa;EAAb;;;;AAYM;EANb,MAAA;EAiBqB;;;;;EAXrB,aAAA;AAAA;;;;;;;;;KAWU,WAAA;EAEH,mCAAP,KAAA,EAAO,QAAA,CAAS,OAAA,KAEhB;EAAA,OAAA,GAAU,UAAA,CAAW,OAAA,KAAA;EAErB,KAAA,GAAQ,SAAA;EAAA;;;;EAKR,aAAA;EAOa;;;;;;EAAb,SAAA,IAAa,UAAA,EAAY,cAAA,CAAe,OAAA,aAAoB,OAAA,QAUlD;EARV,cAAA,GAAiB,mBAAA,CAAoB,OAAA;AAAA;;;;;;KAQ3B,cAAA;EAMO,0CAJjB,IAAA,EAAM,QAAA,CAAS,OAAA,GAAf;EAEA,MAAA,EAAQ,WAAA,CAAY,OAAA,GAFL;EAIf,MAAA,EAAQ,SAAA,IAFA;EAIR,KAAA,UAFA;EAIA,MAAA,WAFA;EAIA,QAAA;AAAA;;AAAQ;AAQV;;;KAAY,UAAA;EAAW,0CAErB,SAAA,UAEA;EAAA,KAAA,UAIA;EAFA,WAAA,UAMA;EAJA,WAAA,UAQA;EANA,QAAA,UAMsB;EAJtB,SAAA,UAMQ;EAJR,MAAA;EAEA,KAAA,EAAO,cAAc,CAAC,OAAA;EAEtB,QAAA;AAAA"}
+{"version":3,"file":"eval.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/eval.type.ts"],"mappings":";;;;;;;;AAYA;;;;;KAAY,SAAA;EASV,6CAPA,KAAA;EAOM;AASR;;;EAXE,MAAA,YAaM;EAXN,MAAA;AAAA;;;;;;;KASU,iBAAA;EAIV,uCAFA,IAAA,EAAM,QAAA,CAAS,OAAA,GAEK;EAApB,MAAA,EAAQ,WAAA,CAAY,OAAA,GAEX;EAAT,MAAA,GAAS,OAAA,EAEL;EAAJ,IAAA;AAAA;;;;;;;KASU,UAAA,uBACV,OAAA,EAAS,iBAAA,CAAkB,OAAA,MACxB,SAAA,GAAY,OAAA,CAAQ,SAAA;;;;;;;KAQb,QAAA;EARK,+DAUf,IAAA,UAVgC;EAYhC,KAAA;EAJU;;;;;EAUV,QAAA,YAIU;EAFV,OAAA,GAAU,UAAA,CAAW,OAAA,KAEQ;EAA7B,OAAA,GAAU,mBAAA,CAAoB,OAAA;AAAA;;;;;;;;;;AAAO;AAevC;;KAAY,SAAA;EAEU,+DAApB,KAAA,EAAO,aAAa;EAAb;;;;AAYM;EANb,MAAA;EAiBqB;;;;;EAXrB,aAAA;AAAA;;;;;;;;;KAWU,WAAA;EA8BW;;;;;EAxBrB,KAAA,EAAO,QAAA,CAAS,OAAA,MAAa,eAAA,CAAgB,OAAA,GAAhB;EAE7B,OAAA,GAAU,UAAA,CAAW,OAAA,KAArB;EAEA,KAAA,GAAQ,SAAA;EAFa;;;;EAOrB,aAAA;EAOyB;;;;;;EAAzB,SAAA,IAAa,UAAA,EAAY,cAAA,CAAe,OAAA,aAAoB,OAAA,QAQ5D;EANA,cAAA,GAAiB,mBAAA,CAAoB,OAAA;EAMf;;;AAMb;AAOX;EAbE,QAAA,GAAW,UAAA,CAAW,OAAA;;;;;;EAMtB,SAAA;AAAA;;;;;KAOU,cAAA;EAmBA;;;;EAdV,SAAA,EAAW,KAAK;IAAG,IAAA;IAAc,MAAA;IAAgB,KAAA;EAAA,IAoBhC;EAlBjB,OAAA,YAcA;EAZA,KAAA,YAYe;EAVf,MAAA;AAAA;;;;;;KAQU,cAAA;EAYF,0CAVR,IAAA,EAAM,QAAA,CAAS,OAAA,GAkBL;EAhBV,MAAA,EAAQ,WAAA,CAAY,OAAA,GAgBA;EAdpB,MAAA,EAAQ,SAAA,IA8BD;EA5BP,KAAA,UAmC2B;EAjC3B,MAAA,WAUqB;EARrB,QAAA;AAAA;;;;;;KAQU,UAAA;EAgBH,0CAdP,SAAA,UAgBA;EAdA,KAAA,UAmBa;EAjBb,WAAA,UAiB2B;EAf3B,WAAA;EAEA,QAAA;EAEA,SAAA;EAEA,MAAA;EAEA,KAAA,EAAO,cAAA,CAAe,OAAA;EAEtB,QAAA;;;;;EAKA,UAAA,GAAa,cAAA;AAAA"}

package/esm/contracts/attachment-policy.type.d.mts

@@ -0,0 +1,51 @@
+import { OutboundPolicy } from "../security/outbound-policy.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/attachment-policy.type.d.ts
+/**
+ * Trust-boundary policy for agent attachments (S1). Attachment references
+ * are frequently user-controlled (chat uploads, document-ingestion
+ * endpoints), so the framework treats server-side fetches and local reads
+ * as hostile by default.
+ *
+ * Supply it on `AgentConfig.attachmentPolicy` (factory default) or
+ * per-call `AgentExecuteOptions.attachmentPolicy` (overrides the factory
+ * one). Omitting it keeps the safe defaults: remote text fetch is denied,
+ * and bare-string local paths warn (staged deprecation).
+ */
+type AttachmentPolicy = {
+  /**
+   * Allow fetching a REMOTE TEXT attachment (an `http`/`https` URL given
+   * as a `{ type: "text" }` source). Default `false` — default-deny: such
+   * a fetch throws `OutboundPolicyError` unless this is enabled.
+   *
+   * URL *image* attachments are handed to the provider as a URL and are
+   * never fetched server-side, so they are unaffected by this flag.
+   */
+  allowRemoteFetch?: boolean;
+  /**
+   * {@link OutboundPolicy} applied to a permitted remote-text fetch
+   * (scheme + host allowlist, post-DNS private-IP deny, max bytes,
+   * timeout, injectable fetch). Defaults to the strict OutboundPolicy
+   * defaults (https-only, private-IP deny on, 5 MiB cap, 10s timeout).
+   */
+  outbound?: OutboundPolicy;
+  /**
+   * Sandbox roots for LOCAL file attachments. When set, a local path must
+   * resolve inside one of these absolute roots, else it is rejected with
+   * `OutboundPolicyError`. When omitted, local reads are not path-
+   * restricted (back-compat) — set this to confine reads to an uploads
+   * directory.
+   */
+  allowedRoots?: string[];
+  /**
+   * Allow bare-STRING local paths (e.g. `"./notes.txt"`, `"/etc/passwd"`).
+   * Staged deprecation: today bare-string local paths are allowed but warn
+   * once (outside tests). Set `false` to hard-deny them now — the typed
+   * `{ type, source: { absolutePath } }` StorageFile route stays supported
+   * (and is gated by {@link allowedRoots}).
+   */
+  allowBareLocalPaths?: boolean;
+};
+//#endregion
+export { AttachmentPolicy };
+//# sourceMappingURL=attachment-policy.type.d.mts.map

package/esm/contracts/attachment-policy.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-policy.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/attachment-policy.type.ts"],"mappings":";;;;;AAaA;;;;;;;;;KAAY,gBAAA;EAgCS;;;;;;;;EAvBnB,gBAAA;;;;;;;EAOA,QAAA,GAAW,cAAc;;;;;;;;EAQzB,YAAA;;;;;;;;EAQA,mBAAA;AAAA"}

package/esm/contracts/attachment.type.d.mts

@@ -20,8 +20,9 @@ type StorageFileShape = {
  *
  * - `string` — local file path or remote URL (auto-detected via the
  *   `https?://` prefix).
- * - `StorageFileShape` — a `@warlock.js/core` storage file; URL wins
- *   over path when both are present.
+ * - `StorageFileShape` — a `@warlock.js/core` storage file; `absolutePath`
+ *   wins over `url` when both are present (prefer the local file the app
+ *   already has over an extra remote hop).
  * - `{ base64, mediaType }` — raw inline bytes with an explicit IANA
  *   media type, useful for in-memory data that never touched disk.
  */
@@ -35,12 +36,14 @@ type AttachmentSource = string | StorageFileShape | {
  * Two forms:
  *
  * - **Tagged form** (preferred for non-image types and for explicit
- *   intent): `{ type: "image" | "text", source }`.
+ *   intent): `{ type: "image" | "text" | "pdf" | "audio", source }`.
  * - **Shorthand string / StorageFileShape**: the agent infers the
- *   media kind from the file extension. Recognized image extensions:
- *   `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`. Recognized text
- *   extension: `.txt`. Anything else throws — silent inference for
- *   ambiguous inputs causes silent bugs.
+ *   media kind from the file extension. Recognized: image
+ *   (`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`), text (`.txt`), pdf
+ *   (`.pdf`), audio (`.mp3`, `.wav`, `.m4a`, `.ogg`, `.weba`). Anything
+ *   else throws — silent inference for ambiguous inputs causes silent
+ *   bugs. The model must declare the matching capability
+ *   (`vision` / `pdf` / `audio`) or the agent rejects the attachment.
  *
  * @example
  * // Shorthand — extension-inferred image
@@ -69,6 +72,12 @@ type Attachment = string | StorageFileShape | {
 } | {
   type: "text";
   source: AttachmentSource;
+} | {
+  type: "pdf";
+  source: AttachmentSource;
+} | {
+  type: "audio";
+  source: AttachmentSource;
 };
 /**
  * A normalized attachment after source resolution — a tagged value the

package/esm/contracts/attachment.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"attachment.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/attachment.type.ts"],"mappings":";;AAUA;;;;AAIc;AAed;;;;KAnBY,gBAAA;EAsBN,6BApBJ,GAAA,WAoB6B;EAlB7B,YAAY;AAAA;;;;;;;;;;;;;KAeF,gBAAA,YAER,gBAAgB;EACd,MAAA;EAAgB,SAAA;AAAA;AAwDtB;;;;;;;;;;;;AAG8C;;;;;;;;;;;;;;;;;;;;;;AAH9C,KApBY,UAAA,YAER,gBAAA;EACE,IAAA;EAAe,MAAA,EAAQ,gBAAA;AAAA;EACvB,IAAA;EAAc,MAAA,EAAQ,gBAAA;AAAA;;;;;;;;;;;;;;;KAgBhB,kBAAA;EACN,IAAA;EAAa,KAAA;AAAA;EACb,IAAA;EAAc,KAAA;AAAA;EACd,IAAA;EAAgB,KAAA;EAAe,SAAA;AAAA"}
+{"version":3,"file":"attachment.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/attachment.type.ts"],"mappings":";;AAUA;;;;AAIc;AAgBd;;;;KApBY,gBAAA;EAuBN,6BArBJ,GAAA,WAqB6B;EAnB7B,YAAY;AAAA;;;;;;;;;;;;;;KAgBF,gBAAA,YAER,gBAAgB;EACd,MAAA;EAAgB,SAAA;AAAA;;;;;;;AA4CuB;AAgB7C;;;;;;;;;;;;AAG8C;;;;;;;;;;;;;;;;;KAzBlC,UAAA,YAER,gBAAA;EACE,IAAA;EAAe,MAAA,EAAQ,gBAAA;AAAA;EACvB,IAAA;EAAc,MAAA,EAAQ,gBAAA;AAAA;EACtB,IAAA;EAAa,MAAA,EAAQ,gBAAA;AAAA;EACrB,IAAA;EAAe,MAAA,EAAQ,gBAAA;AAAA;;;;;;;;;;;;;;;KAgBjB,kBAAA;EACN,IAAA;EAAa,KAAA;AAAA;EACb,IAAA;EAAc,KAAA;AAAA;EACd,IAAA;EAAgB,KAAA;EAAe,SAAA;AAAA"}

package/esm/contracts/content-part.type.d.mts

@@ -34,22 +34,31 @@ type ContentPart = {
 } | {
   type: "image";
   source: ImageSource;
+} | {
+  type: "pdf";
+  source: BinarySource;
+} | {
+  type: "audio";
+  source: BinarySource;
 };
 /**
- * Where an image's bytes live in a resolved `ContentPart`.
+ * Where binary media bytes live in a resolved `ContentPart`.
  *
  * - `{ url }` — remote URL the provider can fetch directly. Used for
  *   public URLs and StorageFile entries that already expose a URL.
  * - `{ base64, mediaType }` — inlined base64 bytes with an explicit
- *   IANA media type (e.g. `"image/png"`). Used for local file paths
- *   and StorageFile entries with only an absolute path.
+ *   IANA media type (e.g. `"image/png"`, `"application/pdf"`,
+ *   `"audio/mpeg"`). Used for local file paths and StorageFile entries
+ *   with only an absolute path.
  */
-type ImageSource = {
+type BinarySource = {
   url: string;
 } | {
   base64: string;
   mediaType: string;
 };
+/** Image bytes for an `{ type: "image" }` part. Alias of {@link BinarySource}. */
+type ImageSource = BinarySource;
 //#endregion
-export { ContentPart, ImageSource };
+export { BinarySource, ContentPart, ImageSource };
 //# sourceMappingURL=content-part.type.d.mts.map

package/esm/contracts/content-part.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"content-part.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/content-part.type.ts"],"mappings":";;AA6BA;;;;;;;;;;AAA+F;AAW/F;;;;;;;;AAAuE;;;;;;;;;KAX3D,WAAA;EAAgB,IAAA;EAAc,IAAA;AAAA;EAAmB,IAAA;EAAe,MAAA,EAAQ,WAAW;AAAA;;;;;;;;;;KAWnF,WAAA;EAAgB,GAAA;AAAA;EAAkB,MAAA;EAAgB,SAAA;AAAA"}
+{"version":3,"file":"content-part.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/content-part.type.ts"],"mappings":";;AA6BA;;;;;;;;;;;;;;;;;;;;AAIyC;AAYzC;;;;;;;KAhBY,WAAA;EACN,IAAA;EAAc,IAAA;AAAA;EACd,IAAA;EAAe,MAAA,EAAQ,WAAA;AAAA;EACvB,IAAA;EAAa,MAAA,EAAQ,YAAA;AAAA;EACrB,IAAA;EAAe,MAAA,EAAQ,YAAA;AAAA;;;;;;;;;;;KAYjB,YAAA;EAAiB,GAAA;AAAA;EAAkB,MAAA;EAAgB,SAAA;AAAA;;KAGnD,WAAA,GAAc,YAAY"}

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

@@ -1 +1 @@
-{"version":3,"file":"supervisor-events.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/events/supervisor-events.type.ts"],"mappings":";;;;;;;;;KAWY,yBAAA;EACV,cAAA;EACA,KAAA,EAAO,eAAe;AAAA;;KAIZ,kCAAA;EAAuC,SAAS;AAAA;;KAGhD,+BAAA;EAAoC,SAAS;AAAA;;KAG7C,8BAAA;EACV,SAAA;EACA,IAAA,EAAM,IAAI;EACV,SAAA;EACA,UAAA;AAAA;AAV0D;AAAA,KAchD,8BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA;AAAA;AAXF;;;;;AAAA,KAmBY,+BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA;AAAA;AAlBU;AAAA,KAsBA,+BAAA;EACV,SAAA;EACA,MAAA;EACA,MAAA;EACA,KAAA;IAAS,KAAA;IAAe,MAAA;IAAgB,KAAA;EAAA;EACxC,QAAA;AAAA;;;;;;KAQU,4BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA,EAAO,OAAO;AAAA;;;;;;KAQJ,mCAAA;EAAwC,SAAS;AAAA;;;AAnBnD;AAQV;;;;KAoBY,oCAAA;EACV,KAAK;AAAA;;;AAlBS;AAQhB;;;KAmBY,oCAAA;EACV,MAAA;IAAU,MAAA;IAAiB,SAAA;IAAoB,UAAA;EAAA;EAC/C,MAAA;EACA,OAAA;EACA,MAAA;EACA,QAAA;EACA,KAAA,GAAQ,KAAK;AAAA;;;;;;KAQH,iCAAA;EACV,KAAA,EAAO,OAAO;AAAA;;;AATD;AAQf;;;KAUY,6BAAA;EACV,KAAK;AAAA;;;;AAAA;AAQP;KAAY,6BAAA;EACV,MAAA;EACA,KAAA,GAAQ,KAAA;EACR,QAAA;EACA,KAAA,GAAQ,OAAO;AAAA;;KAIL,gCAAA;EACV,SAAA;EACA,OAAA,EAAS,cAAc;AAAA;AAFzB;;;;AAAA,KASY,mCAAA;EACV,SAAA;EACA,QAAA,EAAU,iBAAiB;AAAA;AATJ;AAAA,KAab,0BAAA;EACV,WAAA;EACA,MAAM;AAAA;;KAII,0BAAA;EACV,MAAA,EAAQ,gBAAgB,CAAC,OAAA;AAAA;AAXE;AAI7B;;;AAJ6B,KAkBjB,sBAAA;EAA2B,KAAA,EAAO,OAAO;AAAA"}
+{"version":3,"file":"supervisor-events.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/events/supervisor-events.type.ts"],"mappings":";;;;;;;;;KAWY,yBAAA;EACV,cAAA;EACA,KAAA,EAAO,eAAe;AAAA;;KAIZ,kCAAA;EAAuC,SAAS;AAAA;;KAGhD,+BAAA;EAAoC,SAAS;AAAA;;KAG7C,8BAAA;EACV,SAAA;EACA,IAAA,EAAM,IAAI;EACV,SAAA;EACA,UAAA;AAAA;AAPF;AAAA,KAWY,8BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA;AAAA;;;;;;KAQU,+BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA;AAAA;AAdF;AAAA,KAkBY,+BAAA;EACV,SAAA;EACA,MAAA;EACA,MAAA;EACA,KAAA;IAAS,KAAA;IAAe,MAAA;IAAgB,KAAA;EAAA;EACxC,QAAA;AAAA;;;;;;KAQU,4BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA,EAAO,OAAO;AAAA;;;;;;KAQJ,mCAAA;EAAwC,SAAS;AAAA;;AAnBnD;AAQV;;;;;KAoBY,oCAAA;EACV,KAAK;AAAA;;AAlBS;AAQhB;;;;KAmBY,oCAAA;EACV,MAAA;IAAU,MAAA;IAAiB,SAAA;IAAoB,UAAA;EAAA;EAC/C,MAAA;EACA,OAAA;EACA,MAAA;EACA,QAAA;EACA,KAAA,GAAQ,KAAK;AAAA;;;;;;KAQH,iCAAA;EACV,KAAA,EAAO,OAAO;AAAA;;AATD;AAQf;;;;KAUY,6BAAA;EACV,KAAK;AAAA;;;AAAA;AAQP;;KAAY,6BAAA;EACV,MAAA;EACA,KAAA,GAAQ,KAAA;EACR,QAAA;EACA,KAAA,GAAQ,OAAO;AAAA;;KAIL,gCAAA;EACV,SAAA;EACA,OAAA,EAAS,cAAc;AAAA;;;;;KAOb,mCAAA;EACV,SAAA;EACA,QAAA,EAAU,iBAAiB;AAAA;AAF7B;AAAA,KAMY,0BAAA;EACV,WAAA;EACA,MAAM;AAAA;;KAII,0BAAA;EACV,MAAA,EAAQ,gBAAgB,CAAC,OAAA;AAAA;AAP3B;;;;AAAA,KAcY,sBAAA;EAA2B,KAAA,EAAO,OAAO;AAAA"}

package/esm/contracts/index.d.mts

@@ -1,5 +1,6 @@
+import { AttachmentPolicy } from "./attachment-policy.type.mjs";
 import { Attachment, AttachmentSource, ResolvedAttachment, StorageFileShape } from "./attachment.type.mjs";
-import { ContentPart, ImageSource } from "./content-part.type.mjs";
+import { BinarySource, ContentPart, ImageSource } from "./content-part.type.mjs";
 import { ModelToolCallRequest } from "./model-tool-call-request.type.mjs";
 import { Message } from "./conversation-message.type.mjs";
 import { ModelPricing } from "./result/model-pricing.type.mjs";
@@ -10,7 +11,7 @@ import { BaseReport, REPORT_SCHEMA_VERSION, ReportStatus, ReportType } from "./r
 import { FinishReason } from "./finish-reason.type.mjs";
 import { ToolCall } from "./result/tool-call.type.mjs";
 import { LLMTrip } from "./result/llm-trip.type.mjs";
-import { AgentReport, ExecutionReport, ExecutionStatus } from "./result/execution-report.type.mjs";
+import { AgentReport, CapturedMessage, ExecutionReport, ExecutionStatus } from "./result/execution-report.type.mjs";
 import { AgentResult } from "./result/agent-result.type.mjs";
 import { AgentCompletedPayload, AgentErrorPayload, AgentStartingPayload, AgentStreamingPayload, AgentToolCalledPayload, AgentToolCallingFailedPayload, AgentToolCallingPayload, AgentTripCompletedPayload, AgentTripStartedPayload, ToolEventMeta } from "./events/agent-events.type.mjs";
 import { EventIdentity, WithoutIdentity } from "./events/event-identity.type.mjs";
@@ -40,7 +41,7 @@ import { MiddlewareState } from "./middleware/middleware-state.type.mjs";
 import { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareSupervisorContext, MiddlewareSupervisorRef, MiddlewareToolContext, MiddlewareTripContext } from "./middleware/middleware-context.type.mjs";
 import { AgentMiddleware, AgentMiddlewareExecuteHooks, AgentMiddlewareSupervisorHooks, AgentMiddlewareToolHooks, AgentMiddlewareTripHooks } from "./middleware/middleware.contract.mjs";
 import { Placeholders } from "./placeholders.type.mjs";
-import { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract } from "./system-prompt.contract.mjs";
+import { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract, SystemPromptMergeOptions, SystemPromptMergeSource, SystemPromptMeta } from "./system-prompt.contract.mjs";
 import { RouteContext } from "./supervisor/route-context.type.mjs";
 import { AckCallback, AckConfig, AckEntry, AckRunEntry } from "./supervisor/ack-entry.type.mjs";
 import { DispatchRawResult, IntentCallback, IntentEntry, IntentRunEntry, SupervisorIntentValue } from "./supervisor/intent-entry.type.mjs";
@@ -66,6 +67,7 @@ import { RecallOptions } from "./memory/recall-options.type.mjs";
 import { MemoryContract } from "./memory/memory.contract.mjs";
 import { MemoryConfig, SemanticMemoryConfig } from "./memory/memory-config.type.mjs";
 import { CheckpointRecord, CheckpointStore } from "./orchestrator/checkpoint-store.contract.mjs";
+import { SessionLock } from "./orchestrator/session-lock.contract.mjs";
 import { OrchestratorCommands } from "./orchestrator/orchestrator-commands.type.mjs";
 import { OrchestratorEvent, OrchestratorEventHandler, OrchestratorEventHandlers, OrchestratorEventMap, OrchestratorEventName } from "./orchestrator/orchestrator-event.type.mjs";
 import { OrchestratorExecuteOptions, OrchestratorResumeOptions } from "./orchestrator/orchestrator-execute-options.type.mjs";
@@ -74,9 +76,9 @@ import { OrchestratorConfig, OrchestratorMemoryConfig, SummarizeCallback, Summar
 import { SessionContract } from "./orchestrator/session.contract.mjs";
 import { PlannerCapability } from "./planner/planner-capability.type.mjs";
 import { PlannerConfig } from "./planner/planner-config.type.mjs";
-import { PlannerExecuteOptions } from "./planner/planner-execute-options.type.mjs";
 import { PlannerPlan, PlannerStep } from "./planner/planner-plan.type.mjs";
 import { PlannerReport, PlannerReportType, PlannerResult, PlannerStepSnapshot } from "./planner/planner-result.type.mjs";
+import { PlannerExecuteOptions, PlannerStepDirective } from "./planner/planner-execute-options.type.mjs";
 import { PlannerContract } from "./planner/planner.contract.mjs";
 import { ModelConfig, SDKAdapterContract } from "./sdk-adapter.contract.mjs";
 import { CompleteEvent } from "./events/complete-event.type.mjs";

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

@@ -116,17 +116,20 @@ type ModelCapabilities = {
    */
   promptCaching?: boolean;
   /**
-   * True when the adapter accepts audio `ContentPart` input. When
-   * false/absent and the caller passes audio attachments, the agent
-   * throws upfront rather than dropping them at the wire layer (mirrors
-   * `vision`).
+   * True when the adapter accepts audio `ContentPart` input (A2). The
+   * agent gates `{ type: "audio" }` attachments on this flag — when
+   * false/absent it throws upfront rather than dropping them at the wire
+   * layer (mirrors `vision`). Wired end-to-end: audio `ContentPart` +
+   * attachment resolution exist; today Google (Gemini, via `inlineData`)
+   * declares it.
    */
   audio?: boolean;
   /**
-   * True when the adapter accepts PDF / document `ContentPart` input.
-   * When false/absent and the caller passes PDF attachments, the agent
-   * throws upfront rather than dropping them at the wire layer (mirrors
-   * `vision`).
+   * True when the adapter accepts PDF / document `ContentPart` input (A2).
+   * The agent gates `{ type: "pdf" }` attachments on this flag — when
+   * false/absent it throws upfront (mirrors `vision`). Wired end-to-end:
+   * Anthropic (`document` block), Bedrock Converse (`document` block), and
+   * Google (Gemini `inlineData`) map PDF parts.
    */
   pdf?: boolean;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"model.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/model.contract.ts"],"mappings":";;;;;;;;;;AAqBA;;;;;;;;;;;;KAAY,gBAAA;EACV,WAAA;EACA,SAAA,WAkBA;EAhBA,KAAA,GAAQ,UAAA;EA2BR;;;;;;;;EAlBA,cAAA,GAAiB,MAAA;EA6CP;;;;AAAe;AAY3B;EAlDE,MAAA,GAAS,WAAA;;;;;;;;;;AA4FN;EAjFH,SAAA;IACE,MAAA,GAAS,eAAA;IACT,SAAA;EAAA;EA+FK;;;;;;;;;;;EAlFP,YAAA;IACE,WAAA;EAAA,GA+FwB;EAAA,CA5FzB,GAAA;AAAA;;;;;;KAQS,eAAA;;;;;;;;;;;KAYA,iBAAA;EAuFgD;AAAA;AAgB5D;;;;EAhGE,gBAAA;EA2HmB;;;;;;;EAnHnB,MAAA;EAwHsE;;;;;;EAjHtE,SAAA;EAuGmB;;;;;EAjGnB,aAAA;EAsG2D;;;;;;EA/F3D,KAAA;EAoGyD;;;AAA8B;;;EA7FvF,GAAA;AAAA;;;;;;;;;;;KAaU,aAAA;EACV,OAAA;EACA,YAAA,EAAc,YAAA;EACd,KAAA,EAAO,KAAA;EAEP,SAAA,GAAY,oBAAA;AAAA;;;;;;;;;;KAYF,gBAAA;EACN,IAAA;EAAe,OAAA;AAAA;EAEf,IAAA;EACA,EAAA;EACA,IAAA;EACA,KAAA;;;;;;;EAOA,gBAAA,GAAmB,MAAA;AAAA;EAEnB,IAAA;EAAc,YAAA,EAAc,YAAA;EAAc,KAAA,EAAO,KAAA;AAAA;;;;;;;;;;;;;;;UAgBtC,aAAA;;WAEN,IAAA;;WAEA,QAAA;;;;;;WAMA,YAAA,GAAe,iBAAA;;;;;;;;;;;WAYf,OAAA,GAAU,YAAA;;;;EAKnB,QAAA,CAAS,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,aAAA;;;;EAKnE,MAAA,CAAO,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,aAAA,CAAc,gBAAA;AAAA"}
+{"version":3,"file":"model.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/model.contract.ts"],"mappings":";;;;;;;;;;AAqBA;;;;;;;;;;;;KAAY,gBAAA;EACV,WAAA;EACA,SAAA,WAkBA;EAhBA,KAAA,GAAQ,UAAA;EA2BR;;;;;;;;EAlBA,cAAA,GAAiB,MAAA;EA6CP;;;;AAAe;AAY3B;EAlDE,MAAA,GAAS,WAAA;;;;;;;;;;AA+FN;EApFH,SAAA;IACE,MAAA,GAAS,eAAA;IACT,SAAA;EAAA;EAkGK;;;;;;;;;;;EArFP,YAAA;IACE,WAAA;EAAA,GAkGwB;EAAA,CA/FzB,GAAA;AAAA;;;;;;KAQS,eAAA;;;;;;;;;;;KAYA,iBAAA;EA0FgD;AAAA;AAgB5D;;;;EAnGE,gBAAA;EA8HmB;;;;;;;EAtHnB,MAAA;EA2HsE;;;;;;EApHtE,SAAA;EA0GmB;;;;;EApGnB,aAAA;EAyG2D;;;;;;;;EAhG3D,KAAA;EAqGuF;AAAA;;;;;;EA7FvF,GAAA;AAAA;;;;;;;;;;;KAaU,aAAA;EACV,OAAA;EACA,YAAA,EAAc,YAAA;EACd,KAAA,EAAO,KAAA;EAEP,SAAA,GAAY,oBAAA;AAAA;;;;;;;;;;KAYF,gBAAA;EACN,IAAA;EAAe,OAAA;AAAA;EAEf,IAAA;EACA,EAAA;EACA,IAAA;EACA,KAAA;;;;;;;EAOA,gBAAA,GAAmB,MAAA;AAAA;EAEnB,IAAA;EAAc,YAAA,EAAc,YAAA;EAAc,KAAA,EAAO,KAAA;AAAA;;;;;;;;;;;;;;;UAgBtC,aAAA;;WAEN,IAAA;;WAEA,QAAA;;;;;;WAMA,YAAA,GAAe,iBAAA;;;;;;;;;;;WAYf,OAAA,GAAU,YAAA;;;;EAKnB,QAAA,CAAS,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,aAAA;;;;EAKnE,MAAA,CAAO,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,aAAA,CAAc,gBAAA;AAAA"}

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

@@ -1,5 +1,6 @@
 import { PgClientLike, RedisClientLike, SnapshotStore } from "./snapshot-store.contract.mjs";
 import { CheckpointRecord, CheckpointStore } from "./checkpoint-store.contract.mjs";
+import { SessionLock } from "./session-lock.contract.mjs";
 import { OrchestratorCommands } from "./orchestrator-commands.type.mjs";
 import { OrchestratorEvent, OrchestratorEventHandler, OrchestratorEventHandlers, OrchestratorEventMap, OrchestratorEventName } from "./orchestrator-event.type.mjs";
 import { OrchestratorExecuteOptions, OrchestratorResumeOptions } from "./orchestrator-execute-options.type.mjs";

package/esm/contracts/orchestrator/orchestrator-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 { SnapshotStore } from "./snapshot-store.contract.mjs";
 import { ModelContract } from "../model.contract.mjs";
 import { SystemPromptContract } from "../system-prompt.contract.mjs";
@@ -12,6 +13,7 @@ import { CompactionResult } from "../result/orchestrator-result.type.mjs";
 import { MemoryTier } from "../memory/memory-item.type.mjs";
 import { MemoryContract } from "../memory/memory.contract.mjs";
 import { CheckpointStore } from "./checkpoint-store.contract.mjs";
+import { SessionLock } from "./session-lock.contract.mjs";
 import { OrchestratorEventHandlers } from "./orchestrator-event.type.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
@@ -124,7 +126,15 @@ type OrchestratorMemoryConfig = {
  */
 type OrchestratorConfig<TOutput, TState = TOutput, TIntents extends Record<string, SupervisorIntentValue> = Record<string, SupervisorIntentValue>> = {
   /** Stable identifier — used in logs, events, checkpoints, signature. */name: string; /** Dev-curated version string. Metadata only (§10.2) — never parsed. */
-  version?: string; /** Prepended to the router agent's system prompt (router mode only). */
+  version?: string;
+  /**
+   * Per-flow observability routing. `true` routes each turn'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. Parity with agent/workflow/supervisor — a durable
+   * session root no longer needs a manual `observe.collect()`.
+   */
+  observe?: FlowObserveOption; /** Prepended to the router agent's system prompt (router mode only). */
   systemPrompt?: SystemPromptContract | string; /** Dispatchable units keyed by intent name (supervisor surface). */
   intents: TIntents; /** Deterministic per-turn dispatch. Mutually exclusive with `router`. */
   route?: (ctx: RouteContext<TState>) => Next | Promise<Next>; /** LLM-driven dispatch. Mutually exclusive with `route`. */
@@ -151,7 +161,26 @@ type OrchestratorConfig<TOutput, TState = TOutput, TIntents extends Record<strin
   }; /** Automatic post-turn compaction policy (§12). */
   summarize?: SummarizeConfig | SummarizeCallback; /** Number of turn snapshots to retain per session. Default 100. */
   keepSnapshots?: number | "all"; /** Durable session-state store. Falls back to `ai.config({ defaultCheckpointStore })`. */
-  checkpointStore?: CheckpointStore; /** Internal-supervisor snapshot store. Required when `iterate: true`. */
+  checkpointStore?: CheckpointStore;
+  /**
+   * Per-session turn serialization (C4). Each `execute` / `stream` /
+   * `resume` turn runs under `sessionLock.withLock(sessionId, …)` so a
+   * concurrent same-session turn can't race the checkpoint's read-modify-
+   * write and lose an update.
+   *
+   * - Omitted (default) → an in-process mutex keyed by `sessionId`. Fully
+   *   serializes same-session turns within ONE process; for a
+   *   horizontally-scaled deployment supply a distributed lock instead.
+   * - A {@link SessionLock} → your own (e.g. Redis/Postgres advisory
+   *   locks) for cross-process serialization.
+   * - `false` → no locking. Only when an external mechanism (sticky
+   *   routing, single-writer guarantee) already serializes the session.
+   *
+   * When a durable `checkpointStore` is configured but no explicit lock
+   * is supplied, the orchestrator warns once (outside tests) that the
+   * in-process default does not protect across processes.
+   */
+  sessionLock?: SessionLock | false; /** Internal-supervisor snapshot store. Required when `iterate: true`. */
   snapshotStore?: SnapshotStore;
   /**
    * Optional per-turn memory (memory core M2). When set, the

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

@@ -1 +1 @@
-{"version":3,"file":"orchestrator-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/orchestrator/orchestrator-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyBA;;;;;;KAAY,eAAA;EAeE,qEAbZ,UAAA,WAEA;EAAA,IAAA,WAEa;EAAb,UAAA,GAAa,aAAA;EAOC;;;;;EADd,SAAA,IACE,UAAA,EAAY,gBAAA,EACZ,GAAA;IAAO,SAAA;EAAA,MACJ,OAAA,eAEW;EAAhB,IAAA;IAAS,OAAA;EAAA;AAAA;;;;;;;KASC,iBAAA,IACV,OAAA,EAAS,OAAA,OACN,OAAA,CAAQ,gBAAA,IAAoB,gBAAA;;;;;AAAgB;AAmBjD;;;;;;;;;;;;KAAY,wBAAA;EAYR,gFAVF,KAAA,EAAO,cAAA;EAkBP;;;;;AAYS;EAvBT,MAAA;IACE,CAAA;IACA,SAAA;IACA,IAAA,GAAO,UAAA;EAAA;EAmDQ;;;;;;EA3CjB,QAAA;EA0DuC;;;;;EApDvC,YAAA,GAAe,UAAA;EAyDQ;;;;;EAnDvB,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BU,kBAAA,mBAED,OAAA,mBACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAEvD,qBAAA;EAWF,wEAPA,IAAA,UASA;EAPA,OAAA,WAO2B;EAL3B,YAAA,GAAe,oBAAA,WAKwB;EAFvC,OAAA,EAAS,QAAA,EAE6C;EAAtD,KAAA,IAAS,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,IAAA,GAAO,OAAA,CAAQ,IAAA,GAE7C;EAAT,MAAA,GAAS,aAAA,YAAyB,WAAA,CAAY,MAAA,GAAA;EAE9C,QAAA,IACE,GAAA,EAAK,eAAA,CAAgB,MAAA,MAClB,cAAA,GAAiB,OAAA,CAAQ,cAAA,GADvB;EAGP,KAAA,GAAQ,MAAA,EAHN;EAKF,MAAA,GAAS,gBAAA,CAAiB,OAAA,GAJJ;EAMtB,YAAA,WAJA;EAMA,aAAA;EAJA;;;;;EAWA,OAAA;EAMA;;;;;EAAA,aAAA;IACE,MAAA,cAAoB,QAAA,EAAU,OAAA,OAAc,OAAA;IAC5C,MAAA,cAAoB,QAAA,EAAU,OAAA,OAAc,OAAA;EAAA,GAG9C;EAAA,SAAA,GAAY,eAAA,GAAkB,iBAAA,EAAA;EAE9B,aAAA,mBAGA;EAAA,eAAA,GAAkB,eAAA,EAElB;EAAA,aAAA,GAAgB,aAAA;EAUhB;;;;;;AAG8B;;;EAH9B,MAAA,GAAS,cAAA,GAAiB,wBAAA;EAG1B,EAAA,GAAK,yBAAA;AAAA"}
+{"version":3,"file":"orchestrator-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/orchestrator/orchestrator-config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA2BA;;;;;;KAAY,eAAA;EAeE,qEAbZ,UAAA,WAEA;EAAA,IAAA,WAEa;EAAb,UAAA,GAAa,aAAA;EAOC;;;;;EADd,SAAA,IACE,UAAA,EAAY,gBAAA,EACZ,GAAA;IAAO,SAAA;EAAA,MACJ,OAAA,eAEW;EAAhB,IAAA;IAAS,OAAA;EAAA;AAAA;;;;;;;KASC,iBAAA,IACV,OAAA,EAAS,OAAA,OACN,OAAA,CAAQ,gBAAA,IAAoB,gBAAA;;;;;AAAgB;AAmBjD;;;;;;;;;;;;KAAY,wBAAA;EAYR,gFAVF,KAAA,EAAO,cAAA;EAkBP;;;;;AAYS;EAvBT,MAAA;IACE,CAAA;IACA,SAAA;IACA,IAAA,GAAO,UAAA;EAAA;EAmDQ;;;;;;EA3CjB,QAAA;EAkEc;;;;;EA5Dd,YAAA,GAAe,UAAA;EA8DmB;;;;;EAxDlC,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BU,kBAAA,mBAED,OAAA,mBACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAEvD,qBAAA;EAcF,wEAVA,IAAA,UAYA;EAVA,OAAA;EAaA;;;;;;;EALA,OAAA,GAAU,iBAAA,EAO4C;EALtD,YAAA,GAAe,oBAAA,WAON;EAJT,OAAA,EAAS,QAAA,EAIqC;EAF9C,KAAA,IAAS,GAAA,EAAK,YAAA,CAAa,MAAA,MAAY,IAAA,GAAO,OAAA,CAAQ,IAAA,GAK/C;EAHP,MAAA,GAAS,aAAA,YAAyB,WAAA,CAAY,MAAA,GAG5C;EADF,QAAA,IACE,GAAA,EAAK,eAAA,CAAgB,MAAA,MAClB,cAAA,GAAiB,OAAA,CAAQ,cAAA,GAAR;EAEtB,KAAA,GAAQ,MAAA,EAAR;EAEA,MAAA,GAAS,gBAAA,CAAiB,OAAA,GAA1B;EAEA,YAAA,WAF0B;EAI1B,aAAA;EAAA;;;;;EAOA,OAAA;EAO8C;;;;;EAD9C,aAAA;IACE,MAAA,cAAoB,QAAA,EAAU,OAAA,OAAc,OAAA;IAC5C,MAAA,cAAoB,QAAA,EAAU,OAAA,OAAc,OAAA;EAAA,GAQ9C;EALA,SAAA,GAAY,eAAA,GAAkB,iBAAA,EAwB9B;EAtBA,aAAA,mBAwBA;EArBA,eAAA,GAAkB,eAAA;EA+BlB;;;;;;AAG8B;;;;;;;;;;;;EAf9B,WAAA,GAAc,WAAA;EAEd,aAAA,GAAgB,aAAA;;;;;;;;;;EAUhB,MAAA,GAAS,cAAA,GAAiB,wBAAA;EAG1B,EAAA,GAAK,yBAAA;AAAA"}

package/esm/contracts/orchestrator/session-lock.contract.d.mts

@@ -0,0 +1,47 @@
+//#region ../@warlock.js/ai/src/contracts/orchestrator/session-lock.contract.d.ts
+/**
+ * Serializes concurrent turns for a single orchestrator session so the
+ * read-modify-write of the durable checkpoint can't lose an update
+ * (orchestrator C4). The orchestrator wraps each `execute()` / `stream()`
+ * / `resume()` turn in `withLock(sessionId, …)`.
+ *
+ * The framework default is an in-process mutex keyed by `sessionId`
+ * ({@link inProcessSessionLock}), which fully serializes same-session
+ * turns within ONE process. For a horizontally-scaled deployment (many
+ * processes / pods) supply a distributed implementation — Redis
+ * `SETNX` / Redlock, Postgres advisory locks, etc. — so the invariant
+ * holds across processes too. Set `sessionLock: false` on the config to
+ * opt out entirely (only when an external mechanism already serializes
+ * same-session turns, e.g. sticky routing).
+ *
+ * @example
+ * // A Redis-backed distributed lock.
+ * const redisLock: SessionLock = {
+ *   async withLock(key, fn, { signal } = {}) {
+ *     await acquireRedisLock(key, { signal });
+ *     try {
+ *       return await fn();
+ *     } finally {
+ *       await releaseRedisLock(key);
+ *     }
+ *   },
+ * };
+ */
+interface SessionLock {
+  /**
+   * Acquire the lock for `key` (the sessionId), run `fn`, and release it
+   * — even if `fn` throws or rejects. Concurrent calls for the SAME key
+   * run one at a time, in arrival order; calls for DIFFERENT keys never
+   * contend.
+   *
+   * `options.signal` aborts the WAIT for the lock (never the critical
+   * section once acquired): a caller cancelled while queued rejects with
+   * the signal's reason instead of deadlocking behind a stuck holder.
+   */
+  withLock<T>(key: string, fn: () => Promise<T>, options?: {
+    signal?: AbortSignal;
+  }): Promise<T>;
+}
+//#endregion
+export { SessionLock };
+//# sourceMappingURL=session-lock.contract.d.mts.map

package/esm/contracts/orchestrator/session-lock.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lock.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/orchestrator/session-lock.contract.ts"],"mappings":";;AA4BA;;;;;;;;;;;;;;;;;;;;;;AAec;;;;;UAfG,WAAA;;;;;;;;;;;EAWf,QAAA,IACE,GAAA,UACA,EAAA,QAAU,OAAA,CAAQ,CAAA,GAClB,OAAA;IAAY,MAAA,GAAS,WAAA;EAAA,IACpB,OAAA,CAAQ,CAAA;AAAA"}

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

@@ -1,6 +1,6 @@
 import { PlannerCapability } from "./planner-capability.type.mjs";
 import { PlannerConfig } from "./planner-config.type.mjs";
-import { PlannerExecuteOptions } from "./planner-execute-options.type.mjs";
 import { PlannerPlan, PlannerStep } from "./planner-plan.type.mjs";
 import { PlannerReport, PlannerReportType, PlannerResult, PlannerStepSnapshot } from "./planner-result.type.mjs";
+import { PlannerExecuteOptions, PlannerStepDirective } from "./planner-execute-options.type.mjs";
 import { PlannerContract } from "./planner.contract.mjs";

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

@@ -1,4 +1,5 @@
 import { AgentContract } from "../agent/agent.contract.mjs";
+import { FlowObserveOption } from "../../observe/resolve-observers.mjs";
 import { ModelContract } from "../model.contract.mjs";
 import { SystemPromptContract } from "../system-prompt.contract.mjs";
 import { PlannerCapability } from "./planner-capability.type.mjs";
@@ -35,6 +36,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 +81,28 @@ 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;
+  };
 };
 //#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":";;;;;;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,aAAA;EAiDV,0EA/CA,IAAA,UA+C0B;EA7C1B,OAAA;EAyDA;;;;AASqB;;;EA1DrB,OAAA,GAAU,iBAAA;;;;;EAKV,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;AAAA"}