@warlock.js/ai 4.5.0 → 4.6.1

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

@@ -60,8 +60,10 @@ 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";
@@ -75,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 { 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 { 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/planner/index.d.mts

@@ -1,6 +1,7 @@
 import { PlannerCapability } from "./planner-capability.type.mjs";
-import { PlannerConfig } from "./planner-config.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 { 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";

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

@@ -1,8 +1,10 @@
 import { AgentContract } from "../agent/agent.contract.mjs";
 import { FlowObserveOption } from "../../observe/resolve-observers.mjs";
+import { SnapshotStore } from "../orchestrator/snapshot-store.contract.mjs";
 import { ModelContract } from "../model.contract.mjs";
 import { SystemPromptContract } from "../system-prompt.contract.mjs";
 import { PlannerCapability } from "./planner-capability.type.mjs";
+import { PlannerSnapshot } from "./planner-snapshot.type.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region ../@warlock.js/ai/src/contracts/planner/planner-config.type.d.ts
@@ -103,6 +105,34 @@ type PlannerConfig<TOutput = unknown> = {
   replan?: {
     maxReplans: number;
   };
+  /**
+   * Opt-in durable mid-run crash-resume. When set, the planner
+   * checkpoints its state to a {@link SnapshotStore} after every settled
+   * plan node, so a `planner.resume(runId)` after a crash re-hydrates the
+   * frozen plan + executed-node ledger + usage + child reports and
+   * continues scheduling only the unfinished frontier — never re-calling
+   * the planning LLM and never re-dispatching a completed node's
+   * capability.
+   *
+   * Absent ⇒ no persistence, zero behavior change: the planner runs
+   * byte-for-byte as today.
+   *
+   * - `store` — the snapshot store to persist to. Optional; falls back to
+   *   `ai.config({ defaultSnapshotStore })`. When neither is set, snapshot
+   *   writes silently skip and `resume()` throws.
+   * - `deleteOnComplete` — drop the snapshot once the run terminates
+   *   successfully. Default `false` (keep it for the completed-run
+   *   short-circuit + audit).
+   *
+   * **Idempotency caveat.** A crash mid-node re-runs that node's
+   * capability on resume; side-effectful capabilities must be idempotent —
+   * the same caller-responsibility boundary the supervisor and workflow
+   * primitives already document.
+   */
+  durable?: {
+    /** Snapshot store to persist to. Falls back to the global default. */store?: SnapshotStore<PlannerSnapshot>; /** Drop the snapshot on successful completion. Default `false`. */
+    deleteOnComplete?: boolean;
+  };
 };
 //#endregion
 export { PlannerConfig };

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

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

package/esm/contracts/planner/planner-execute-options.type.d.mts

@@ -85,6 +85,18 @@ type PlannerExecuteOptions<TOutput = unknown> = {
    */
   onStep?: (snapshot: PlannerStepSnapshot, plan: PlannerPlan) => void | PlannerStepDirective | Promise<void | PlannerStepDirective>;
 };
+/**
+ * Options accepted by `planner.resume(runId, options?)`.
+ *
+ * `force: true` bypasses the signature drift check — use only when you
+ * have verified the definition change is safe for the in-flight
+ * snapshot. `PlannerDriftError` is otherwise thrown without executing
+ * anything. Everything else mirrors {@link PlannerExecuteOptions} (e.g.
+ * re-supply a `signal` to keep the resumed run cancellable).
+ */
+type PlannerResumeOptions<TOutput = unknown> = PlannerExecuteOptions<TOutput> & {
+  /** Bypass the drift check and resume against the changed definition. */force?: boolean;
+};
 //#endregion
-export { PlannerExecuteOptions, PlannerStepDirective };
+export { PlannerExecuteOptions, PlannerResumeOptions, PlannerStepDirective };
 //# sourceMappingURL=planner-execute-options.type.d.mts.map

package/esm/contracts/planner/planner-execute-options.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"planner-execute-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-execute-options.type.ts"],"mappings":";;;;;;;;AAiBA;;;;;;;;;AAG8B;KAHlB,oBAAA;EACN,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;EAAgB,QAAA;AAAA;;;;;;;KAQV,qBAAA;EAAsB,+DAEhC,KAAA;EAKA;;;;EAAA,YAAA,GAAe,YAAA;EAef;;;;;EATA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EAyC1B;;;;;;;;EAhCA,MAAA,GAAS,WAAA;EAmC6D;;;;;;EA5BtE,SAAA;;;;;;;;;;EAUA,IAAA;;;;;;;;EAQA,YAAA,GAAe,WAAA;;;;;;;EAOf,MAAA,IACE,QAAA,EAAU,mBAAA,EACV,IAAA,EAAM,WAAA,YACI,oBAAA,GAAuB,OAAA,QAAe,oBAAA;AAAA"}
+{"version":3,"file":"planner-execute-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-execute-options.type.ts"],"mappings":";;;;;;;;AAiBA;;;;;;;;;AAG8B;KAHlB,oBAAA;EACN,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;EAAgB,QAAA;AAAA;;;;;;;KAQV,qBAAA;EAAsB,+DAEhC,KAAA;EAKA;;;;EAAA,YAAA,GAAe,YAAA;EAef;;;;;EATA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EAyC1B;;;;;;;;EAhCA,MAAA,GAAS,WAAA;EAmC6D;AAYxE;;;;;EAxCE,SAAA;EAwC0E;;;AAErE;;;;;;EAhCL,IAAA;;;;;;;;EAQA,YAAA,GAAe,WAAA;;;;;;;EAOf,MAAA,IACE,QAAA,EAAU,mBAAA,EACV,IAAA,EAAM,WAAA,YACI,oBAAA,GAAuB,OAAA,QAAe,oBAAA;AAAA;;;;;;;;;;KAYxC,oBAAA,sBAA0C,qBAAqB,CAAC,OAAA;0EAE1E,KAAA;AAAA"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-snapshot.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-snapshot.type.ts"],"mappings":";;;;;;;;AAgBA;;;;AAAiC;AAqCjC;;;;KArCY,qBAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAoEH;;;;;;;KA/BG,eAAA;qDAEV,KAAA;EAEA,WAAA;EAEA,SAAA;EAEA,OAAA;EAEA,IAAA;;;;;;EAMA,IAAA,EAAM,WAAA;;;;;;EAMN,aAAA,EAAe,mBAAA;EAEf,KAAA,EAAO,KAAA;EAEP,QAAA,EAAU,UAAA;EAEV,WAAA;EACA,MAAA,EAAQ,qBAAA;EACR,SAAA;EACA,OAAA;AAAA"}

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

@@ -1,6 +1,6 @@
 import { ExecutableContract } from "../executable.contract.mjs";
 import { PlannerResult } from "./planner-result.type.mjs";
-import { PlannerExecuteOptions } from "./planner-execute-options.type.mjs";
+import { PlannerExecuteOptions, PlannerResumeOptions } from "./planner-execute-options.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/planner/planner.contract.d.ts
 /**
@@ -54,6 +54,26 @@ interface PlannerContract<TOutput = unknown> extends ExecutableContract<string,
    * shape; runtime failures surface on `result.error`.
    */
   execute(goal: string, options?: PlannerExecuteOptions<TOutput>): Promise<PlannerResult<TOutput>>;
+  /**
+   * Resume a durable run after a crash. Loads the snapshot persisted
+   * under `runId` (requires `durable` on the config, or a global
+   * `defaultSnapshotStore`), re-hydrates the frozen plan + executed-node
+   * ledger + usage, and continues scheduling only the unfinished frontier
+   * — never re-calling the planning LLM and never re-dispatching a
+   * completed node's capability. A resume of an already-settled run
+   * re-returns the stored result without running anything.
+   *
+   * Refuses to continue when the current definition has structurally
+   * drifted from the snapshot (`PlannerDriftError`), unless
+   * `{ force: true }` is passed. Throws `PlannerFailedError` when no store
+   * is configured or no snapshot exists for `runId`.
+   *
+   * @example
+   * const result = await research.execute("compare A vs B", { runId: "plan-7" });
+   * // ...process crashes mid-run...
+   * const recovered = await research.resume("plan-7");
+   */
+  resume(runId: string, options?: PlannerResumeOptions<TOutput>): Promise<PlannerResult<TOutput>>;
 }
 //#endregion
 export { PlannerContract };

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

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

package/esm/contracts/result/base-report.type.d.mts

@@ -20,7 +20,7 @@ declare const REPORT_SCHEMA_VERSION = 1;
  * {@link BaseReport}. Forms a closed union so consumers can narrow on
  * the tree without string-matching on `name`.
  */
-type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor" | "team" | "orchestrator" | "batch" | "planner";
+type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor" | "team" | "orchestrator" | "batch" | "planner" | "image" | "speech" | "transcription" | "video" | "realtime";
 /**
  * Terminal status every executable primitive reports. Unified across
  * tools, agents, workflows, and supervisors so dashboards and

package/esm/contracts/result/base-report.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"base-report.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"mappings":";;;;;;;AAeA;;;;AAAkC;AAOlC;;;;cAPa,qBAAA;AA2Cb;;;;AAAwB;AAAxB,KApCY,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KAoCA,YAAA;;;;;;;;AA0HS;;;;;;;;;;;;;;;;;KA1FT,UAAA;sFAEV,KAAA;;;;;;;;;;EAUA,WAAA;;;;;;;EAOA,SAAA;EAEA,IAAA;;;;;;;;;;;;EAYA,OAAA;;;;;;;;;;EAUA,SAAA;EAEA,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;;;;;;;;;;;;EAYR,KAAA,GAAQ,OAAA;EAER,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;;;;;;EAMP,QAAA,EAAU,UAAA;;;;;;;;EAQV,QAAA,GAAW,YAAA;;;;;;;;;EASX,mBAAA;AAAA"}
+{"version":3,"file":"base-report.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"mappings":";;;;;;;AAeA;;;;AAAkC;AAOlC;;;;cAPa,qBAAA;AAgDb;;;;AAAwB;AAAxB,KAzCY,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KAyCA,YAAA;;;;;;;;AA0HS;;;;;;;;;;;;;;;;;KA1FT,UAAA;sFAEV,KAAA;;;;;;;;;;EAUA,WAAA;;;;;;;EAOA,SAAA;EAEA,IAAA;;;;;;;;;;;;EAYA,OAAA;;;;;;;;;;EAUA,SAAA;EAEA,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;;;;;;;;;;;;EAYR,KAAA,GAAQ,OAAA;EAER,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;;;;;;EAMP,QAAA,EAAU,UAAA;;;;;;;;EAQV,QAAA,GAAW,YAAA;;;;;;;;;EASX,mBAAA;AAAA"}

package/esm/contracts/result/base-report.type.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"base-report.type.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"sourcesContent":["import type { AIError } from \"../../errors/ai-error\";\nimport type { AttemptEntry } from \"./attempt-entry.type\";\nimport type { Usage } from \"./usage.type\";\n\n/**\n * Wire-format version stamped on every root `BaseReport`. Bumped only\n * when we make a BREAKING change to the report shape (field removed,\n * required-ness flipped, semantics changed). Additive changes (new\n * optional fields) do not bump.\n *\n * Panoptic and other downstream consumers branch on this to parse\n * old stored reports with their original-shape rules.\n *\n * Current: **1** — initial Panoptic-readiness shape.\n */\nexport const REPORT_SCHEMA_VERSION = 1;\n\n/**\n * Discriminator for the kind of executable that produced a given\n * {@link BaseReport}. Forms a closed union so consumers can narrow on\n * the tree without string-matching on `name`.\n */\nexport type ReportType =\n  | \"tool\"\n  | \"callback\"\n  | \"agent\"\n  | \"workflow\"\n  | \"supervisor\"\n  | \"team\"\n  | \"orchestrator\"\n  | \"batch\"\n  | \"planner\";\n\n/**\n * Terminal status every executable primitive reports. Unified across\n * tools, agents, workflows, and supervisors so dashboards and\n * generic traversal helpers don't special-case per primitive.\n *\n * - `\"completed\"` — ran to natural end with a usable result.\n * - `\"failed\"` — aborted mid-run or finished without a usable result\n *   (crash, schema failure, max-trips, etc.). The\n *   accompanying `error` on the envelope carries the typed cause.\n * - `\"cancelled\"` — caller aborted before completion via `AbortSignal`.\n * - `\"max-iterations\"` — supervisor-specific termination when the\n *   iteration cap was hit without an explicit `END` / `satisfied`.\n *   Harmless on non-supervisor reports; keeping it on the shared\n *   union lets consumers write one `switch` for every status.\n * - `\"awaiting-input\"` — orchestrator-specific NON-terminal status: the\n *   session is paused waiting for the next user turn (§15.6). The only\n *   non-terminal member of this union; consumers branching on\n *   `status === \"completed\"` must treat it as a session-continues path,\n *   not a failure. Harmless on non-orchestrator reports.\n * - `\"awaiting-approval\"` — planner-specific NON-terminal status: a\n *   `mode: \"plan-only\"` run generated and validated a plan but executed\n *   nothing, pending sign-off (the plan rides on `result.plan`). Mirrors\n *   `\"awaiting-input\"` at the plan boundary. Harmless on non-planner\n *   reports.\n */\nexport type ReportStatus =\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"max-iterations\"\n  | \"awaiting-input\"\n  | \"awaiting-approval\";\n\n/**\n * Universal execution report shared by every primitive. Per-primitive\n * report types extend this with their own domain-specific fields\n * (agent trips, workflow steps, supervisor iteration snapshots) while\n * keeping the root fields identical. Recursion happens through\n * {@link BaseReport.children} — any executable this node invoked\n * contributes its own full report here, producing a walkable tree of\n * the entire run.\n *\n * **Usage rollup.** `usage` at every node equals this node's own cost\n * plus the sum of each child's `usage`. Leaves (tools) contribute\n * zero own-cost; composites contribute their direct LLM spend only,\n * with children covering everything delegated.\n *\n * @example\n * function totalCost(report: BaseReport): number {\n *   return report.usage.total;\n * }\n *\n * function walk(report: BaseReport, depth = 0): void {\n *   console.log(`${\"  \".repeat(depth)}${report.type} \"${report.name}\" — ${report.status}`);\n *   for (const child of report.children) walk(child, depth + 1);\n * }\n */\nexport type BaseReport = {\n  /** Stable id for this execution node. Generated per `execute()`/`invoke()` call. */\n  runId: string;\n  /**\n   * Run-id of the immediate parent execution node, when this node was\n   * invoked as part of a larger run (e.g. a tool dispatched by an\n   * agent; an agent dispatched by a supervisor; an inner primitive\n   * wrapped via `asTool()`). Absent on root nodes.\n   *\n   * Lets Panoptic and other flat-row consumers reconstruct the tree\n   * without traversing `children[]` in memory.\n   */\n  parentRunId?: string;\n  /**\n   * Run-id of the top-level execution this node belongs to. Equals\n   * `runId` on the root node, and is propagated downward to every\n   * descendant. Used to slice flat report tables back into per-run\n   * groupings.\n   */\n  rootRunId: string;\n  /** Executable identity — the tool/agent/workflow/supervisor name. */\n  name: string;\n  /**\n   * Dev-curated version string mirrored from the primitive's config\n   * (`AgentConfig.version`, `ToolConfig.version`, etc.). Free-form —\n   * the framework neither parses nor compares it. Stored verbatim on\n   * every report so trip-archive queries can distinguish runs of\n   * \"agent X v2.1\" from \"agent X v2.2\" even when name + signature\n   * are identical.\n   *\n   * Stays `undefined` when the dev didn't declare one — never\n   * auto-defaulted.\n   */\n  version?: string;\n  /**\n   * Caller-supplied identifier that groups multiple `.execute()` calls\n   * into one conceptual user session / request. Propagated to every\n   * descendant report node so flat queries (\"total spend for session\n   * X today\") work without joining the tree.\n   *\n   * Threaded from `execute()` options on every primitive. Optional —\n   * absent when the caller didn't supply one.\n   */\n  sessionId?: string;\n  /** Discriminator for the kind of executable that produced this report. */\n  type: ReportType;\n  /** Terminal status of this execution. */\n  status: ReportStatus;\n  /**\n   * Terminal error stamped on a `failed` / `cancelled` node so the typed\n   * cause travels WITH the report tree — not only on the result envelope.\n   * Essential for the observe path: an {@link import(\"../../observe/observer.contract\").Observer}\n   * receives `collect(report)` with no envelope, so a failed root would\n   * otherwise expose `status` with no error type/message. Child tool nodes\n   * already carry their error this way (`ToolCall.error`); root primitives\n   * (agent / workflow / supervisor / orchestrator / planner) stamp it here\n   * too. Absent on a `completed` node. Panoptic normalizes it to a JSON-safe\n   * span error during projection — the raw `AIError` never has to serialize.\n   */\n  error?: AIError;\n  /** ISO-8601 wall-clock timestamp when execution began. */\n  startedAt: string;\n  /** ISO-8601 wall-clock timestamp when execution finished. */\n  endedAt: string;\n  /** Monotonic duration in milliseconds — `performance.now()` delta. */\n  duration: number;\n  /** Rolled-up usage: own cost + sum of `children[].usage`. */\n  usage: Usage;\n  /**\n   * Reports of every executable invoked by this node, in invocation\n   * order. Empty for leaves (pure tools) and for executables that\n   * didn't delegate work.\n   */\n  children: BaseReport[];\n  /**\n   * Retry history when middleware (or, for workflow steps, the engine\n   * itself) retried this node before it either succeeded or gave up.\n   * Absent when zero retries happened — keeps the common-case payload\n   * lean. The surviving (final) attempt is NOT duplicated here; its\n   * outcome is the report's own `status` / timing.\n   */\n  attempts?: AttemptEntry[];\n  /**\n   * Wire-format version of this report shape. Only present on root\n   * report nodes — implies the same version for the whole tree.\n   * Panoptic / archive consumers branch on this to parse old reports\n   * with their original-shape rules.\n   *\n   * Always equals {@link REPORT_SCHEMA_VERSION} at write time.\n   */\n  reportSchemaVersion?: number;\n};\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,wBAAwB"}
+{"version":3,"file":"base-report.type.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"sourcesContent":["import type { AIError } from \"../../errors/ai-error\";\nimport type { AttemptEntry } from \"./attempt-entry.type\";\nimport type { Usage } from \"./usage.type\";\n\n/**\n * Wire-format version stamped on every root `BaseReport`. Bumped only\n * when we make a BREAKING change to the report shape (field removed,\n * required-ness flipped, semantics changed). Additive changes (new\n * optional fields) do not bump.\n *\n * Panoptic and other downstream consumers branch on this to parse\n * old stored reports with their original-shape rules.\n *\n * Current: **1** — initial Panoptic-readiness shape.\n */\nexport const REPORT_SCHEMA_VERSION = 1;\n\n/**\n * Discriminator for the kind of executable that produced a given\n * {@link BaseReport}. Forms a closed union so consumers can narrow on\n * the tree without string-matching on `name`.\n */\nexport type ReportType =\n  | \"tool\"\n  | \"callback\"\n  | \"agent\"\n  | \"workflow\"\n  | \"supervisor\"\n  | \"team\"\n  | \"orchestrator\"\n  | \"batch\"\n  | \"planner\"\n  | \"image\"\n  | \"speech\"\n  | \"transcription\"\n  | \"video\"\n  | \"realtime\";\n\n/**\n * Terminal status every executable primitive reports. Unified across\n * tools, agents, workflows, and supervisors so dashboards and\n * generic traversal helpers don't special-case per primitive.\n *\n * - `\"completed\"` — ran to natural end with a usable result.\n * - `\"failed\"` — aborted mid-run or finished without a usable result\n *   (crash, schema failure, max-trips, etc.). The\n *   accompanying `error` on the envelope carries the typed cause.\n * - `\"cancelled\"` — caller aborted before completion via `AbortSignal`.\n * - `\"max-iterations\"` — supervisor-specific termination when the\n *   iteration cap was hit without an explicit `END` / `satisfied`.\n *   Harmless on non-supervisor reports; keeping it on the shared\n *   union lets consumers write one `switch` for every status.\n * - `\"awaiting-input\"` — orchestrator-specific NON-terminal status: the\n *   session is paused waiting for the next user turn (§15.6). The only\n *   non-terminal member of this union; consumers branching on\n *   `status === \"completed\"` must treat it as a session-continues path,\n *   not a failure. Harmless on non-orchestrator reports.\n * - `\"awaiting-approval\"` — planner-specific NON-terminal status: a\n *   `mode: \"plan-only\"` run generated and validated a plan but executed\n *   nothing, pending sign-off (the plan rides on `result.plan`). Mirrors\n *   `\"awaiting-input\"` at the plan boundary. Harmless on non-planner\n *   reports.\n */\nexport type ReportStatus =\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"max-iterations\"\n  | \"awaiting-input\"\n  | \"awaiting-approval\";\n\n/**\n * Universal execution report shared by every primitive. Per-primitive\n * report types extend this with their own domain-specific fields\n * (agent trips, workflow steps, supervisor iteration snapshots) while\n * keeping the root fields identical. Recursion happens through\n * {@link BaseReport.children} — any executable this node invoked\n * contributes its own full report here, producing a walkable tree of\n * the entire run.\n *\n * **Usage rollup.** `usage` at every node equals this node's own cost\n * plus the sum of each child's `usage`. Leaves (tools) contribute\n * zero own-cost; composites contribute their direct LLM spend only,\n * with children covering everything delegated.\n *\n * @example\n * function totalCost(report: BaseReport): number {\n *   return report.usage.total;\n * }\n *\n * function walk(report: BaseReport, depth = 0): void {\n *   console.log(`${\"  \".repeat(depth)}${report.type} \"${report.name}\" — ${report.status}`);\n *   for (const child of report.children) walk(child, depth + 1);\n * }\n */\nexport type BaseReport = {\n  /** Stable id for this execution node. Generated per `execute()`/`invoke()` call. */\n  runId: string;\n  /**\n   * Run-id of the immediate parent execution node, when this node was\n   * invoked as part of a larger run (e.g. a tool dispatched by an\n   * agent; an agent dispatched by a supervisor; an inner primitive\n   * wrapped via `asTool()`). Absent on root nodes.\n   *\n   * Lets Panoptic and other flat-row consumers reconstruct the tree\n   * without traversing `children[]` in memory.\n   */\n  parentRunId?: string;\n  /**\n   * Run-id of the top-level execution this node belongs to. Equals\n   * `runId` on the root node, and is propagated downward to every\n   * descendant. Used to slice flat report tables back into per-run\n   * groupings.\n   */\n  rootRunId: string;\n  /** Executable identity — the tool/agent/workflow/supervisor name. */\n  name: string;\n  /**\n   * Dev-curated version string mirrored from the primitive's config\n   * (`AgentConfig.version`, `ToolConfig.version`, etc.). Free-form —\n   * the framework neither parses nor compares it. Stored verbatim on\n   * every report so trip-archive queries can distinguish runs of\n   * \"agent X v2.1\" from \"agent X v2.2\" even when name + signature\n   * are identical.\n   *\n   * Stays `undefined` when the dev didn't declare one — never\n   * auto-defaulted.\n   */\n  version?: string;\n  /**\n   * Caller-supplied identifier that groups multiple `.execute()` calls\n   * into one conceptual user session / request. Propagated to every\n   * descendant report node so flat queries (\"total spend for session\n   * X today\") work without joining the tree.\n   *\n   * Threaded from `execute()` options on every primitive. Optional —\n   * absent when the caller didn't supply one.\n   */\n  sessionId?: string;\n  /** Discriminator for the kind of executable that produced this report. */\n  type: ReportType;\n  /** Terminal status of this execution. */\n  status: ReportStatus;\n  /**\n   * Terminal error stamped on a `failed` / `cancelled` node so the typed\n   * cause travels WITH the report tree — not only on the result envelope.\n   * Essential for the observe path: an {@link import(\"../../observe/observer.contract\").Observer}\n   * receives `collect(report)` with no envelope, so a failed root would\n   * otherwise expose `status` with no error type/message. Child tool nodes\n   * already carry their error this way (`ToolCall.error`); root primitives\n   * (agent / workflow / supervisor / orchestrator / planner) stamp it here\n   * too. Absent on a `completed` node. Panoptic normalizes it to a JSON-safe\n   * span error during projection — the raw `AIError` never has to serialize.\n   */\n  error?: AIError;\n  /** ISO-8601 wall-clock timestamp when execution began. */\n  startedAt: string;\n  /** ISO-8601 wall-clock timestamp when execution finished. */\n  endedAt: string;\n  /** Monotonic duration in milliseconds — `performance.now()` delta. */\n  duration: number;\n  /** Rolled-up usage: own cost + sum of `children[].usage`. */\n  usage: Usage;\n  /**\n   * Reports of every executable invoked by this node, in invocation\n   * order. Empty for leaves (pure tools) and for executables that\n   * didn't delegate work.\n   */\n  children: BaseReport[];\n  /**\n   * Retry history when middleware (or, for workflow steps, the engine\n   * itself) retried this node before it either succeeded or gave up.\n   * Absent when zero retries happened — keeps the common-case payload\n   * lean. The surviving (final) attempt is NOT duplicated here; its\n   * outcome is the report's own `status` / timing.\n   */\n  attempts?: AttemptEntry[];\n  /**\n   * Wire-format version of this report shape. Only present on root\n   * report nodes — implies the same version for the whole tree.\n   * Panoptic / archive consumers branch on this to parse old reports\n   * with their original-shape rules.\n   *\n   * Always equals {@link REPORT_SCHEMA_VERSION} at write time.\n   */\n  reportSchemaVersion?: number;\n};\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,wBAAwB"}

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

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

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

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

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

@@ -0,0 +1,97 @@
+import { Usage } from "./result/usage.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/speech-model.contract.d.ts
+/**
+ * USD pricing for a text-to-speech model. TTS providers meter one of
+ * two ways, and this single shape covers both so the cost folds into
+ * the same `Usage.cost` rollup the text + image paths use:
+ *
+ * - **Per-character** (OpenAI `tts-1` / `tts-1-hd`): billed per input
+ *   character. Set `perMillionCharacters` (USD per 1,000,000 chars).
+ * - **Token-metered** (OpenAI `gpt-4o-mini-tts`): billed per input/output
+ *   token like a chat model. Set `input` / `output` (USD per 1M tokens).
+ *
+ * Per-character wins when both are set. Nothing set → `Usage.cost`
+ * stays `undefined` (honest "cost unknown", not a false zero).
+ *
+ * @example
+ * const pricing: SpeechModelPricing = { perMillionCharacters: 15 }; // tts-1
+ */
+type SpeechModelPricing = {
+  /** USD per 1M input characters — per-character-metered TTS. */perMillionCharacters?: number; /** USD per 1M input tokens — token-metered TTS. */
+  input?: number; /** USD per 1M output (audio) tokens — token-metered TTS. */
+  output?: number;
+};
+/**
+ * Generated audio, normalized to a discriminated shape (mirrors
+ * {@link GeneratedImage}). TTS providers return raw audio bytes, so the
+ * `base64` variant is the only one today; the union leaves room for a
+ * future hosted-`url` variant without a breaking change.
+ */
+type GeneratedAudio = {
+  type: "base64"; /** Base64-encoded audio bytes. */
+  base64: string; /** IANA media type (e.g. `"audio/mpeg"`, `"audio/wav"`). */
+  mediaType: string;
+};
+/**
+ * Options for a single {@link SpeechModelContract.generate} request.
+ * Provider-neutral; each adapter maps the ones its API supports.
+ */
+type SpeechOptions = {
+  /** Voice id/name (e.g. OpenAI `"alloy"`, `"verse"`). Defaults per model config. */voice?: string; /** Output container (`"mp3"` / `"opus"` / `"aac"` / `"flac"` / `"wav"` / `"pcm"`). */
+  format?: string; /** Playback speed multiplier (provider range, e.g. OpenAI `0.25`–`4.0`). */
+  speed?: number; /** Extra steering of tone/delivery (OpenAI `gpt-4o-mini-tts` `instructions`). */
+  instructions?: string; /** Cancellation handle wired into the provider request where supported. */
+  signal?: AbortSignal; /** Provider-specific escape hatch — forwarded verbatim. */
+  [key: string]: unknown;
+};
+/**
+ * Raw result of a {@link SpeechModelContract.generate} call — low-level
+ * (like `EmbedderContract.embed`): returns the audio + usage and THROWS
+ * a typed `AIError` on failure. The never-throws `{ data, error, usage,
+ * report }` envelope is added by the `ai.speech()` facade verb.
+ */
+type SpeechGenerationResponse = {
+  audio: GeneratedAudio;
+  /**
+   * Token usage when the provider meters per token (gpt-4o-mini-tts);
+   * `{ input: 0, output: 0, total: 0 }` for per-character-metered models,
+   * whose spend is priced from {@link characters}.
+   */
+  usage: Usage; /** Number of input characters synthesized — drives per-character cost. */
+  characters: number;
+};
+/**
+ * Provider-neutral contract for a text-to-speech model — the audio
+ * sibling of {@link ImageModelContract}. Produced by an adapter's
+ * optional `speech?(config)` factory and consumed by `ai.speech()`.
+ *
+ * @example
+ * const tts = openai.speech({ name: "tts-1", voice: "alloy" });
+ * const { audio } = await tts.generate("Welcome aboard.");
+ */
+interface SpeechModelContract {
+  /** Model identifier (e.g. `"tts-1"`, `"gpt-4o-mini-tts"`). */
+  readonly name: string;
+  /** Provider this model belongs to (e.g. `"openai"`). */
+  readonly provider: string;
+  /** Per-character or per-token USD pricing; folded into `Usage.cost` by `ai.speech()`. */
+  readonly pricing?: SpeechModelPricing;
+  /** Synthesize speech from text. Throws a typed `AIError` on failure. */
+  generate(text: string, options?: SpeechOptions): Promise<SpeechGenerationResponse>;
+}
+/**
+ * Configuration passed to an adapter's `speech()` factory. Mirrors
+ * {@link ImageModelConfig}: `name` + an optional per-model `pricing`
+ * override + a default `voice`, with provider-specific keys on the
+ * index signature.
+ */
+type SpeechModelConfig = {
+  name: string; /** Per-model USD pricing override; wins over the SDK-level registry. */
+  pricing?: SpeechModelPricing; /** Default voice when a call omits `options.voice`. */
+  voice?: string;
+  [key: string]: unknown;
+};
+//#endregion
+export { GeneratedAudio, SpeechGenerationResponse, SpeechModelConfig, SpeechModelContract, SpeechModelPricing, SpeechOptions };
+//# sourceMappingURL=speech-model.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"speech-model.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/speech-model.contract.ts"],"mappings":";;;;;AAkBA;;;;;;;;AAMQ;AASR;;;;;KAfY,kBAAA;EAoBV,+DAlBA,oBAAA,WAkBS;EAhBT,KAAA,WAuBuB;EArBvB,MAAA;AAAA;;;;;;;KASU,cAAA;EACV,IAAA,YAuBY;EArBZ,MAAA,UA8BkC;EA5BlC,SAAA;AAAA;;;;;KAOU,aAAA;EA8BA,mFA5BV,KAAA,WAwCe;EAtCf,MAAA;EAEA,KAAA,WA6CiC;EA3CjC,YAAA,WA2CiD;EAzCjD,MAAA,GAAS,WAAW,EAyCoC;EAAA,CAvCvD,GAAA;AAAA;;;;;;;KASS,wBAAA;EACV,KAAA,EAAO,cAAA;EA6B0E;AAAA;AASnF;;;EAhCE,KAAA,EAAO,KAAK,EAiCZ;EA/BA,UAAA;AAAA;;;;AAoCY;;;;;;UAxBG,mBAAA;;WAEN,IAAA;;WAEA,QAAA;;WAEA,OAAA,GAAU,kBAAA;;EAGnB,QAAA,CAAS,IAAA,UAAc,OAAA,GAAU,aAAA,GAAgB,OAAA,CAAQ,wBAAA;AAAA;;;;;;;KAS/C,iBAAA;EACV,IAAA;EAEA,OAAA,GAAU,kBAAkB;EAE5B,KAAA;EAAA,CACC,GAAA;AAAA"}