@warlock.js/ai 4.4.0 → 4.6.0

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/agent/index.d.mts

@@ -1,3 +1,4 @@
 import { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalReport, EvalScore, EvalScorer, EvalScorerContext } from "./eval.type.mjs";
 import { AgentContract, AgentEventHandler } from "./agent.contract.mjs";
-import { AgentExecuteOptions } from "./agent-options.type.mjs";
+import { AgentExecuteOptions, AgentResumeOptions } from "./agent-options.type.mjs";
+import { AgentSnapshot, AgentSnapshotStatus } from "./agent-snapshot.type.mjs";

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/image-model.contract.d.mts

@@ -0,0 +1,156 @@
+import { Usage } from "./result/usage.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/image-model.contract.d.ts
+/**
+ * USD pricing for an image-generation model. Image providers meter one
+ * of two ways, and this single shape covers both so the cost rolls up
+ * through the same `Usage.cost` path the text models already use — no
+ * second accounting path (only a different INPUT unit).
+ *
+ * - **Token-metered** (OpenAI `gpt-image-1` family): the request bills
+ *   per input/output token exactly like a chat model. Set `input` /
+ *   `output` (USD per 1M tokens) and the framework prices the returned
+ *   token `Usage` with the standard {@link computeCost} math.
+ * - **Per-image-metered** (DALL·E, Google Imagen): the request bills a
+ *   flat amount per generated image, with no token usage. Set `perImage`
+ *   (USD per image), optionally overridden per requested size via
+ *   `perImageBySize`.
+ *
+ * When BOTH families' fields are set, per-image wins (a provider is one
+ * or the other, never both). When nothing is set, `Usage.cost` stays
+ * `undefined` — honest "cost unknown", not a false zero.
+ *
+ * @example
+ * // gpt-image-1 — token-metered:
+ * const pricing: ImageModelPricing = { input: 5, output: 40 };
+ *
+ * @example
+ * // DALL·E 3 — per-image, size-tiered:
+ * const pricing: ImageModelPricing = {
+ *   perImage: 0.04,
+ *   perImageBySize: { "1024x1024": 0.04, "1792x1024": 0.08, "1024x1792": 0.08 },
+ * };
+ */
+type ImageModelPricing = {
+  /** USD per 1M input (prompt) tokens — token-metered models only. */input?: number; /** USD per 1M output (image) tokens — token-metered models only. */
+  output?: number; /** Flat USD per generated image — per-image-metered models. */
+  perImage?: number;
+  /**
+   * Per-size USD-per-image overrides, keyed by the requested `size`
+   * label (e.g. `"1024x1024"`). When the resolved request size is a key
+   * here, it wins over the flat `perImage`. Lets one model price its
+   * size tiers (DALL·E 3 HD/large sizes cost more) without a second
+   * model instance.
+   */
+  perImageBySize?: Record<string, number>;
+};
+/**
+ * One generated image, normalized to a discriminated shape so callers
+ * never have to probe which field a provider populated.
+ *
+ * - `{ type: "url" }` — a remote URL the provider hosts (DALL·E with
+ *   `response_format: "url"`); URLs are typically short-lived, so
+ *   download promptly if you need to persist the bytes.
+ * - `{ type: "base64" }` — inlined base64 bytes with an explicit IANA
+ *   `mediaType` (the GPT-image family and Imagen always return bytes).
+ *
+ * `revisedPrompt` carries the provider's rewritten prompt when prompt
+ * enhancement ran (OpenAI `revised_prompt`, Imagen `enhancedPrompt`).
+ */
+type GeneratedImage = {
+  type: "url";
+  url: string;
+  mediaType?: string;
+  revisedPrompt?: string;
+} | {
+  type: "base64";
+  base64: string;
+  mediaType: string;
+  revisedPrompt?: string;
+};
+/**
+ * Options for a single {@link ImageModelContract.generate} request.
+ * Every field is optional and provider-neutral; each adapter maps the
+ * ones its API supports and ignores the rest. Provider-specific knobs
+ * ride the index signature.
+ */
+type ImageGenerationOptions = {
+  /** How many images to generate. Adapters clamp to the provider's max. */count?: number;
+  /**
+   * Requested pixel size as `"WxH"` (e.g. `"1024x1024"`). Forwarded to
+   * the provider's size param AND used to resolve `perImageBySize`
+   * pricing. Mutually-informative with `aspectRatio` — pass whichever
+   * the target provider speaks (OpenAI = size, Imagen = aspectRatio).
+   */
+  size?: string; /** Quality tier (e.g. `"standard"` / `"hd"` / `"low"` / `"high"`). */
+  quality?: string; /** Aspect ratio (e.g. `"1:1"`, `"16:9"`) — ratio-based providers (Imagen). */
+  aspectRatio?: string; /** Concepts to steer the image away from (Imagen `negativePrompt`). */
+  negativePrompt?: string; /** Output container hint (`"png"` / `"jpeg"` / `"webp"`). */
+  format?: string; /** Cancellation handle wired into the provider request where supported. */
+  signal?: AbortSignal; /** Provider-specific escape hatch — forwarded verbatim. */
+  [key: string]: unknown;
+};
+/**
+ * Raw result of an {@link ImageModelContract.generate} call. Low-level,
+ * like `EmbedderContract.embed` — it returns the images plus token
+ * `Usage` (zeroed for per-image-metered providers) and THROWS a typed
+ * `AIError` on failure. The never-throws `{ data, error, usage, report }`
+ * envelope is added one layer up by the `ai.image()` facade verb.
+ */
+type ImageGenerationResponse = {
+  images: GeneratedImage[];
+  /**
+   * Token usage when the provider meters per token (gpt-image-1);
+   * `{ input: 0, output: 0, total: 0 }` for per-image-metered providers
+   * (DALL·E, Imagen), whose spend is priced from the image count via
+   * {@link ImageModelPricing.perImage}.
+   */
+  usage: Usage;
+};
+/**
+ * Provider-neutral contract for an image-generation model — the output
+ * counterpart to {@link EmbedderContract}. Produced by an adapter's
+ * optional `image?(config)` factory and handed to the `ai.image()`
+ * facade verb, which wraps `generate()` into the uniform result
+ * envelope, prices it, builds the report, and routes it to observers.
+ *
+ * @example
+ * const model = openai.image({ name: "gpt-image-1" });
+ * const { images, usage } = await model.generate("a red bicycle on a white background");
+ */
+interface ImageModelContract {
+  /** Image model identifier (e.g. `"gpt-image-1"`, `"imagen-4.0-generate-001"`). */
+  readonly name: string;
+  /** Provider this model belongs to (e.g. `"openai"`, `"google"`). */
+  readonly provider: string;
+  /**
+   * Per-million-token OR per-image USD pricing. When set, `ai.image()`
+   * computes `Usage.cost` at emit time so image spend rolls up through
+   * the same report tree as text spend. Resolution mirrors the chat
+   * models: per-model `pricing` > SDK registry > undefined.
+   */
+  readonly pricing?: ImageModelPricing;
+  /**
+   * Generate one or more images from a text prompt. Returns the
+   * normalized images plus usage, or throws a typed `AIError` (auth,
+   * rate-limit, content-filter, invalid-request) — caught and surfaced
+   * on `result.error` by the `ai.image()` facade.
+   */
+  generate(prompt: string, options?: ImageGenerationOptions): Promise<ImageGenerationResponse>;
+}
+/**
+ * Configuration passed to an adapter's `image()` factory. Mirrors
+ * {@link EmbedderConfig}: `name` plus an optional per-model `pricing`
+ * override and provider-specific keys on the index signature.
+ *
+ * @example
+ * openai.image({ name: "dall-e-3", pricing: { perImage: 0.04 } });
+ */
+type ImageModelConfig = {
+  name: string; /** Per-model USD pricing override; wins over the SDK-level registry. */
+  pricing?: ImageModelPricing;
+  [key: string]: unknown;
+};
+//#endregion
+export { GeneratedImage, ImageGenerationOptions, ImageGenerationResponse, ImageModelConfig, ImageModelContract, ImageModelPricing };
+//# sourceMappingURL=image-model.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image-model.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/image-model.contract.ts"],"mappings":";;;;;AAgCA;;;;;;;;;;AAcyB;AAgBzB;;;;;;;;;;;;;AAEsE;AAQtE;;;KAxCY,iBAAA;EA0CV,oEAxCA,KAAA,WAiDA;EA/CA,MAAA,WAmDA;EAjDA,QAAA;EAqDA;;;;AAEY;AAUd;;EAzDE,cAAA,GAAiB,MAAM;AAAA;;;;;;AAiEX;AAcd;;;;;;;KA/DY,cAAA;EACN,IAAA;EAAa,GAAA;EAAa,SAAA;EAAoB,aAAA;AAAA;EAC9C,IAAA;EAAgB,MAAA;EAAgB,SAAA;EAAmB,aAAA;AAAA;;;AAgFoC;AAW7F;;;KAnFY,sBAAA;EAoFV,yEAlFA,KAAA;EAoFU;;;AACE;;;EA9EZ,IAAA;EAEA,OAAA;EAEA,WAAA;EAEA,cAAA;EAEA,MAAA;EAEA,MAAA,GAAS,WAAW;GAEnB,GAAA;AAAA;;;;;;;;KAUS,uBAAA;EACV,MAAA,EAAQ,cAAA;;;;;;;EAOR,KAAA,EAAO,KAAK;AAAA;;;;;;;;;;;;UAcG,kBAAA;;WAEN,IAAA;;WAEA,QAAA;;;;;;;WAOA,OAAA,GAAU,iBAAA;;;;;;;EAQnB,QAAA,CAAS,MAAA,UAAgB,OAAA,GAAU,sBAAA,GAAyB,OAAA,CAAQ,uBAAA;AAAA;;;;;;;;;KAW1D,gBAAA;EACV,IAAA;EAEA,OAAA,GAAU,iBAAiB;EAAA,CAC1B,GAAA;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";
@@ -59,13 +60,16 @@ import { SupervisorAgentCompletedPayload, SupervisorAgentFailedPayload, Supervis
 import { WorkflowCancelledPayload, WorkflowCompletedPayload, WorkflowErrorPayload, WorkflowLoopWarningPayload, WorkflowStartingPayload, WorkflowStepCompletedPayload, WorkflowStepFailedPayload, WorkflowStepRetryingPayload, WorkflowStepSkippedPayload, WorkflowStepStartingPayload, WorkflowStepStreamingPayload } from "./events/workflow-events.type.mjs";
 import { AgentEventMap, SupervisorEventMap, WorkflowEventMap } from "./events/event-map.type.mjs";
 import { StreamingToolGuardConfig } from "./streaming-tool-guard-config.type.mjs";
-import { AgentExecuteOptions } from "./agent/agent-options.type.mjs";
+import { AgentExecuteOptions, AgentResumeOptions } from "./agent/agent-options.type.mjs";
+import { AgentSnapshot, AgentSnapshotStatus } from "./agent/agent-snapshot.type.mjs";
 import { EmbedderConfig, EmbedderContract, EmbeddingBatchResult, EmbeddingResult, EmbeddingUsage } from "./embedder.contract.mjs";
+import { GeneratedImage, ImageGenerationOptions, ImageGenerationResponse, ImageModelConfig, ImageModelContract, ImageModelPricing } from "./image-model.contract.mjs";
 import { MemoryItem, MemoryTier, RecalledMemory } from "./memory/memory-item.type.mjs";
 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";
@@ -73,11 +77,14 @@ import { OrchestratorAsToolOptions, OrchestratorContract, OrchestratorSessionSco
 import { OrchestratorConfig, OrchestratorMemoryConfig, SummarizeCallback, SummarizeConfig } from "./orchestrator/orchestrator-config.type.mjs";
 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 { PlannerSnapshot, PlannerSnapshotStatus } from "./planner/planner-snapshot.type.mjs";
+import { PlannerConfig } from "./planner/planner-config.type.mjs";
+import { PlannerExecuteOptions, PlannerResumeOptions, PlannerStepDirective } from "./planner/planner-execute-options.type.mjs";
 import { PlannerContract } from "./planner/planner.contract.mjs";
+import { GeneratedAudio, SpeechGenerationResponse, SpeechModelConfig, SpeechModelContract, SpeechModelPricing, SpeechOptions } from "./speech-model.contract.mjs";
+import { AudioInput, TranscribeOptions, TranscriptionModelConfig, TranscriptionModelContract, TranscriptionModelPricing, TranscriptionResponse, TranscriptionSegment } from "./transcription-model.contract.mjs";
 import { ModelConfig, SDKAdapterContract } from "./sdk-adapter.contract.mjs";
 import { CompleteEvent } from "./events/complete-event.type.mjs";
 import { UsageEvent } from "./events/usage-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,7 @@
 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 { PlannerSnapshot, PlannerSnapshotStatus } from "./planner-snapshot.type.mjs";
+import { PlannerConfig } from "./planner-config.type.mjs";
+import { PlannerExecuteOptions, PlannerResumeOptions, PlannerStepDirective } from "./planner-execute-options.type.mjs";
 import { PlannerContract } from "./planner.contract.mjs";