@warlock.js/ai 4.5.0 → 4.6.1

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

@@ -0,0 +1,101 @@
+import { Usage } from "./result/usage.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/transcription-model.contract.d.ts
+/**
+ * USD pricing for a speech-to-text (transcription) model. STT providers
+ * meter one of two ways; this single shape covers both so the cost
+ * folds into the same `Usage.cost` rollup as text / image / speech:
+ *
+ * - **Per-minute** (OpenAI `whisper-1`): billed per minute of input
+ *   audio. Set `perMinute` (USD per audio-minute).
+ * - **Token-metered** (OpenAI `gpt-4o-transcribe`): billed per
+ *   input/output token. Set `input` / `output` (USD per 1M tokens).
+ *
+ * Per-minute wins when both are set. Nothing set → `Usage.cost` stays
+ * `undefined`.
+ *
+ * @example
+ * const pricing: TranscriptionModelPricing = { perMinute: 0.006 }; // whisper-1
+ */
+type TranscriptionModelPricing = {
+  /** USD per minute of input audio — per-minute-metered STT. */perMinute?: number; /** USD per 1M input (audio) tokens — token-metered STT. */
+  input?: number; /** USD per 1M output (text) tokens — token-metered STT. */
+  output?: number;
+};
+/** One timestamped segment of a transcription (when the provider returns segments). */
+type TranscriptionSegment = {
+  text: string; /** Segment start time in seconds. */
+  start?: number; /** Segment end time in seconds. */
+  end?: number;
+};
+/**
+ * The audio to transcribe — inlined base64 bytes with an explicit IANA
+ * media type, plus an optional filename (some providers infer the codec
+ * from the extension). Read a file to base64 before calling, or pass
+ * in-memory bytes; this keeps the verb provider-neutral and
+ * serializable (no `fs` coupling in core).
+ *
+ * @example
+ * const audio: AudioInput = { base64: buf.toString("base64"), mediaType: "audio/mpeg", filename: "note.mp3" };
+ */
+type AudioInput = {
+  base64: string;
+  mediaType: string;
+  filename?: string;
+};
+/** Options for a single {@link TranscriptionModelContract.transcribe} request. */
+type TranscribeOptions = {
+  /** BCP-47 language hint (e.g. `"en"`) — improves accuracy + latency. */language?: string; /** Optional priming prompt (spelling/style hints). */
+  prompt?: string; /** Provider response format override (e.g. `"verbose_json"` for segments + duration). */
+  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 a {@link TranscriptionModelContract.transcribe} call —
+ * low-level (throws a typed `AIError` on failure). The never-throws
+ * envelope is added by the `ai.transcribe()` facade verb.
+ */
+type TranscriptionResponse = {
+  /** The full transcript text. */text: string; /** Timestamped segments when the provider returns them (verbose mode). */
+  segments?: TranscriptionSegment[]; /** Input audio duration in seconds — drives per-minute cost when present. */
+  durationSeconds?: number;
+  /**
+   * Token usage when the provider meters per token (gpt-4o-transcribe);
+   * `{ input: 0, output: 0, total: 0 }` for per-minute-metered models,
+   * whose spend is priced from {@link durationSeconds}.
+   */
+  usage: Usage;
+};
+/**
+ * Provider-neutral contract for a speech-to-text model — the inverse of
+ * {@link SpeechModelContract}. Produced by an adapter's optional
+ * `transcribe?(config)` factory and consumed by `ai.transcribe()`.
+ *
+ * @example
+ * const stt = openai.transcribe({ name: "whisper-1" });
+ * const { text } = await stt.transcribe({ base64, mediaType: "audio/mpeg" });
+ */
+interface TranscriptionModelContract {
+  /** Model identifier (e.g. `"whisper-1"`, `"gpt-4o-transcribe"`). */
+  readonly name: string;
+  /** Provider this model belongs to (e.g. `"openai"`). */
+  readonly provider: string;
+  /** Per-minute or per-token USD pricing; folded into `Usage.cost` by `ai.transcribe()`. */
+  readonly pricing?: TranscriptionModelPricing;
+  /** Transcribe audio to text. Throws a typed `AIError` on failure. */
+  transcribe(audio: AudioInput, options?: TranscribeOptions): Promise<TranscriptionResponse>;
+}
+/**
+ * Configuration passed to an adapter's `transcribe()` factory. Mirrors
+ * {@link SpeechModelConfig}: `name` + an optional per-model `pricing`
+ * override, with provider-specific keys on the index signature.
+ */
+type TranscriptionModelConfig = {
+  name: string; /** Per-model USD pricing override; wins over the SDK-level registry. */
+  pricing?: TranscriptionModelPricing;
+  [key: string]: unknown;
+};
+//#endregion
+export { AudioInput, TranscribeOptions, TranscriptionModelConfig, TranscriptionModelContract, TranscriptionModelPricing, TranscriptionResponse, TranscriptionSegment };
+//# sourceMappingURL=transcription-model.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transcription-model.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/transcription-model.contract.ts"],"mappings":";;;;;AAkBA;;;;;;;;AAMQ;AAIR;;;;;KAVY,yBAAA;EAeV,8DAbA,SAAA,WAaG;EAXH,KAAA,WAwBoB;EAtBpB,MAAA;AAAA;;KAIU,oBAAA;EACV,IAAA,UAoBQ;EAlBR,KAAA,WAsBU;EApBV,GAAA;AAAA;;;;;;;;;AA8BY;AAQd;KAzBY,UAAA;EACV,MAAA;EACA,SAAA;EACA,QAAA;AAAA;;KAIU,iBAAA;EA8BV,wEA5BA,QAAA,WA4BY;EA1BZ,MAAA,WAsCe;EApCf,MAAA;EAEA,MAAA,GAAS,WAAW,EA2CF;EAAA,CAzCjB,GAAA;AAAA;;;;;;KAQS,qBAAA;EA8BS,gCA5BnB,IAAA,UA+BkB;EA7BlB,QAAA,GAAW,oBAAA,IA6B6B;EA3BxC,eAAA;EA2B4D;;;AAA6B;AAQ3F;EA7BE,KAAA,EAAO,KAAK;AAAA;;;;;;;AAiCA;;;UArBG,0BAAA;;WAEN,IAAA;;WAEA,QAAA;;WAEA,OAAA,GAAU,yBAAA;;EAGnB,UAAA,CAAW,KAAA,EAAO,UAAA,EAAY,OAAA,GAAU,iBAAA,GAAoB,OAAA,CAAQ,qBAAA;AAAA;;;;;;KAQ1D,wBAAA;EACV,IAAA;EAEA,OAAA,GAAU,yBAAyB;EAAA,CAClC,GAAA;AAAA"}

package/esm/errors/agent-drift-error.d.mts

@@ -0,0 +1,32 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/agent-drift-error.d.ts
+type AgentDriftErrorOptions = AIErrorOptions & {
+  /** Signature recorded on the snapshot being resumed. */savedSignature: string; /** Signature computed from the current agent definition. */
+  currentSignature: string;
+  runId: string;
+};
+/**
+ * `agent.resume(runId)` loaded a durable snapshot whose structural
+ * fingerprint does not match the current agent definition (model +
+ * provider + sorted tool names + maxTrips + output presence + version).
+ * The resume is refused — no trip runs — and the user decides how to
+ * recover: discard the snapshot, migrate manually, or call
+ * `resume(runId, { force: true })` to bypass the check.
+ *
+ * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+ * different primitive. Thrown (not returned on `result.error`) because a
+ * drifted resume never produces a valid run.
+ */
+declare class AgentDriftError extends AgentExecutionError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly savedSignature: string;
+  readonly currentSignature: string;
+  readonly runId: string;
+  constructor(message: string, options: AgentDriftErrorOptions);
+}
+//#endregion
+export { AgentDriftError, AgentDriftErrorOptions };
+//# sourceMappingURL=agent-drift-error.d.mts.map

package/esm/errors/agent-drift-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-drift-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/agent-drift-error.ts"],"mappings":";;;;;KAIY,sBAAA,GAAyB,cAAc;0DAEjD,cAAA,UAFgC;EAIhC,gBAAA;EACA,KAAA;AAAA;;;;;AAAK;AAeP;;;;;;;cAAa,eAAA,SAAwB,mBAAA;EAAA,gBACZ,eAAA,EAAiB,aAAA;EAAA,SAExB,cAAA;EAAA,SACA,gBAAA;EAAA,SACA,KAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,sBAAA;AAAA"}

package/esm/errors/agent-drift-error.mjs

@@ -0,0 +1,31 @@
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/agent-drift-error.ts
+/**
+* `agent.resume(runId)` loaded a durable snapshot whose structural
+* fingerprint does not match the current agent definition (model +
+* provider + sorted tool names + maxTrips + output presence + version).
+* The resume is refused — no trip runs — and the user decides how to
+* recover: discard the snapshot, migrate manually, or call
+* `resume(runId, { force: true })` to bypass the check.
+*
+* Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+* different primitive. Thrown (not returned on `result.error`) because a
+* drifted resume never produces a valid run.
+*/
+var AgentDriftError = class extends AgentExecutionError {
+	static {
+		this.defaultCategory = "drift";
+	}
+	constructor(message, options) {
+		super(message, options, "AGENT_DRIFT");
+		this.name = "AgentDriftError";
+		this.savedSignature = options.savedSignature;
+		this.currentSignature = options.currentSignature;
+		this.runId = options.runId;
+	}
+};
+
+//#endregion
+export { AgentDriftError };
+//# sourceMappingURL=agent-drift-error.mjs.map

package/esm/errors/agent-drift-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-drift-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/agent-drift-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport { AgentExecutionError } from \"./agent-execution-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\n\nexport type AgentDriftErrorOptions = AIErrorOptions & {\n  /** Signature recorded on the snapshot being resumed. */\n  savedSignature: string;\n  /** Signature computed from the current agent definition. */\n  currentSignature: string;\n  runId: string;\n};\n\n/**\n * `agent.resume(runId)` loaded a durable snapshot whose structural\n * fingerprint does not match the current agent definition (model +\n * provider + sorted tool names + maxTrips + output presence + version).\n * The resume is refused — no trip runs — and the user decides how to\n * recover: discard the snapshot, migrate manually, or call\n * `resume(runId, { force: true })` to bypass the check.\n *\n * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,\n * different primitive. Thrown (not returned on `result.error`) because a\n * drifted resume never produces a valid run.\n */\nexport class AgentDriftError extends AgentExecutionError {\n  public static readonly defaultCategory: ErrorCategory = \"drift\";\n\n  public readonly savedSignature: string;\n  public readonly currentSignature: string;\n  public readonly runId: string;\n\n  public constructor(message: string, options: AgentDriftErrorOptions) {\n    super(message, options, \"AGENT_DRIFT\");\n    this.name = \"AgentDriftError\";\n    this.savedSignature = options.savedSignature;\n    this.currentSignature = options.currentSignature;\n    this.runId = options.runId;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwBA,IAAa,kBAAb,cAAqC,oBAAoB;;yBACC;;CAMxD,AAAO,YAAY,SAAiB,SAAiC;EACnE,MAAM,SAAS,SAAS,aAAa;EACrC,KAAK,OAAO;EACZ,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,mBAAmB,QAAQ;EAChC,KAAK,QAAQ,QAAQ;CACvB;AACF"}

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

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

package/esm/errors/index.d.mts

@@ -3,6 +3,7 @@ import { AIErrorCode } from "./error-code.type.mjs";
 import { AIError, AIErrorOptions } from "./ai-error.mjs";
 import { AgentExecutionError } from "./agent-execution-error.mjs";
 import { AgentCancelledError, AgentCancelledErrorOptions } from "./agent-cancelled-error.mjs";
+import { AgentDriftError, AgentDriftErrorOptions } from "./agent-drift-error.mjs";
 import { AgentMaxTripsError, AgentMaxTripsErrorOptions } from "./agent-max-trips-error.mjs";
 import { BudgetExceededError, BudgetExceededErrorOptions, BudgetUnit } from "./budget-exceeded-error.mjs";
 import { ProviderError } from "./provider-error.mjs";
@@ -21,6 +22,7 @@ import { OrchestratorDriftError, OrchestratorDriftErrorOptions } from "./orchest
 import { OutboundPolicyError } from "./outbound-policy-error.mjs";
 import { PlannerFailedError } from "./planner-failed-error.mjs";
 import { PlannerCancelledError, PlannerCancelledErrorOptions } from "./planner-cancelled-error.mjs";
+import { PlannerDriftError, PlannerDriftErrorOptions } from "./planner-drift-error.mjs";
 import { PlannerPlanInvalidError } from "./planner-plan-invalid-error.mjs";
 import { ProviderAuthError } from "./provider-auth-error.mjs";
 import { ProviderRateLimitError, ProviderRateLimitErrorOptions } from "./provider-rate-limit-error.mjs";

package/esm/errors/index.mjs

@@ -1,6 +1,7 @@
 import { AIError } from "./ai-error.mjs";
 import { AgentExecutionError } from "./agent-execution-error.mjs";
 import { AgentCancelledError } from "./agent-cancelled-error.mjs";
+import { AgentDriftError } from "./agent-drift-error.mjs";
 import { AgentMaxTripsError } from "./agent-max-trips-error.mjs";
 import { BudgetExceededError } from "./budget-exceeded-error.mjs";
 import { ProviderError } from "./provider-error.mjs";
@@ -19,6 +20,7 @@ import { OrchestratorDriftError } from "./orchestrator-drift-error.mjs";
 import { OutboundPolicyError } from "./outbound-policy-error.mjs";
 import { PlannerFailedError } from "./planner-failed-error.mjs";
 import { PlannerCancelledError } from "./planner-cancelled-error.mjs";
+import { PlannerDriftError } from "./planner-drift-error.mjs";
 import { PlannerPlanInvalidError } from "./planner-plan-invalid-error.mjs";
 import { ProviderAuthError } from "./provider-auth-error.mjs";
 import { ProviderRateLimitError } from "./provider-rate-limit-error.mjs";

package/esm/errors/planner-drift-error.d.mts

@@ -0,0 +1,34 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { PlannerFailedError } from "./planner-failed-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/planner-drift-error.d.ts
+type PlannerDriftErrorOptions = AIErrorOptions & {
+  /** Signature recorded on the snapshot being resumed. */savedSignature: string; /** Signature computed from the current planner definition. */
+  currentSignature: string;
+  runId: string;
+};
+/**
+ * `planner.resume(runId)` loaded a durable snapshot whose structural
+ * fingerprint does not match the current planner definition (name +
+ * ordered capability names). The resume is refused — no node runs — and
+ * the user decides how to recover: discard the snapshot, migrate
+ * manually, or call `resume(runId, { force: true })` to bypass the check.
+ *
+ * A mid-run re-plan is NOT drift — the plan changed, not the definition;
+ * the persisted `replanCount` honors the replan budget across a resume.
+ *
+ * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+ * different primitive. Thrown (not returned on `result.error`) because a
+ * drifted resume never produces a valid run.
+ */
+declare class PlannerDriftError extends PlannerFailedError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly savedSignature: string;
+  readonly currentSignature: string;
+  readonly runId: string;
+  constructor(message: string, options: PlannerDriftErrorOptions);
+}
+//#endregion
+export { PlannerDriftError, PlannerDriftErrorOptions };
+//# sourceMappingURL=planner-drift-error.d.mts.map

package/esm/errors/planner-drift-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-drift-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/planner-drift-error.ts"],"mappings":";;;;;KAIY,wBAAA,GAA2B,cAAc;0DAEnD,cAAA,UAFkC;EAIlC,gBAAA;EACA,KAAA;AAAA;;;;;AAAK;AAiBP;;;;;;;;;cAAa,iBAAA,SAA0B,kBAAA;EAAA,gBACd,eAAA,EAAiB,aAAA;EAAA,SAExB,cAAA;EAAA,SACA,gBAAA;EAAA,SACA,KAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,wBAAA;AAAA"}

package/esm/errors/planner-drift-error.mjs

@@ -0,0 +1,33 @@
+import { PlannerFailedError } from "./planner-failed-error.mjs";
+
+//#region ../@warlock.js/ai/src/errors/planner-drift-error.ts
+/**
+* `planner.resume(runId)` loaded a durable snapshot whose structural
+* fingerprint does not match the current planner definition (name +
+* ordered capability names). The resume is refused — no node runs — and
+* the user decides how to recover: discard the snapshot, migrate
+* manually, or call `resume(runId, { force: true })` to bypass the check.
+*
+* A mid-run re-plan is NOT drift — the plan changed, not the definition;
+* the persisted `replanCount` honors the replan budget across a resume.
+*
+* Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,
+* different primitive. Thrown (not returned on `result.error`) because a
+* drifted resume never produces a valid run.
+*/
+var PlannerDriftError = class extends PlannerFailedError {
+	static {
+		this.defaultCategory = "drift";
+	}
+	constructor(message, options) {
+		super(message, options, "PLANNER_DRIFT");
+		this.name = "PlannerDriftError";
+		this.savedSignature = options.savedSignature;
+		this.currentSignature = options.currentSignature;
+		this.runId = options.runId;
+	}
+};
+
+//#endregion
+export { PlannerDriftError };
+//# sourceMappingURL=planner-drift-error.mjs.map

package/esm/errors/planner-drift-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-drift-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/planner-drift-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\nimport { PlannerFailedError } from \"./planner-failed-error\";\n\nexport type PlannerDriftErrorOptions = AIErrorOptions & {\n  /** Signature recorded on the snapshot being resumed. */\n  savedSignature: string;\n  /** Signature computed from the current planner definition. */\n  currentSignature: string;\n  runId: string;\n};\n\n/**\n * `planner.resume(runId)` loaded a durable snapshot whose structural\n * fingerprint does not match the current planner definition (name +\n * ordered capability names). The resume is refused — no node runs — and\n * the user decides how to recover: discard the snapshot, migrate\n * manually, or call `resume(runId, { force: true })` to bypass the check.\n *\n * A mid-run re-plan is NOT drift — the plan changed, not the definition;\n * the persisted `replanCount` honors the replan budget across a resume.\n *\n * Mirrors `SupervisorDriftError` / `WorkflowDriftError` — same rationale,\n * different primitive. Thrown (not returned on `result.error`) because a\n * drifted resume never produces a valid run.\n */\nexport class PlannerDriftError extends PlannerFailedError {\n  public static readonly defaultCategory: ErrorCategory = \"drift\";\n\n  public readonly savedSignature: string;\n  public readonly currentSignature: string;\n  public readonly runId: string;\n\n  public constructor(message: string, options: PlannerDriftErrorOptions) {\n    super(message, options, \"PLANNER_DRIFT\");\n    this.name = \"PlannerDriftError\";\n    this.savedSignature = options.savedSignature;\n    this.currentSignature = options.currentSignature;\n    this.runId = options.runId;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA0BA,IAAa,oBAAb,cAAuC,mBAAmB;;yBACA;;CAMxD,AAAO,YAAY,SAAiB,SAAmC;EACrE,MAAM,SAAS,SAAS,eAAe;EACvC,KAAK,OAAO;EACZ,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,mBAAmB,QAAQ;EAChC,KAAK,QAAQ,QAAQ;CACvB;AACF"}

package/esm/image/image-cost.d.mts

@@ -0,0 +1,32 @@
+import { ModelPricing } from "../contracts/result/model-pricing.type.mjs";
+import { Usage } from "../contracts/result/usage.type.mjs";
+import { ImageModelPricing } from "../contracts/image-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/image/image-cost.d.ts
+/**
+ * Price one image-generation `Usage` against an
+ * {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD
+ * breakdown so image spend folds into the exact same `Usage.cost`
+ * rollup the text path uses (`accumulateCost` / `mergeUsage`). There is
+ * no separate image-cost field anywhere downstream — only this one
+ * function, which knows the two metering models:
+ *
+ * - **Per-image** (DALL·E, Imagen): `perImageBySize[size]` (when the
+ *   request `size` matches a tier) else flat `perImage`, times the
+ *   number of images returned, attributed to `cost.output` (the image
+ *   IS the output). Token channels stay 0.
+ * - **Token** (gpt-image-1): delegates to the standard
+ *   {@link computeCost} against the prompt/image token `Usage`.
+ *
+ * Per-image wins when both shapes are configured (a provider is one or
+ * the other). Returns `undefined` when no usable pricing is present —
+ * the framework treats that as "cost unknown", never a false zero.
+ *
+ * @example
+ * computeImageCost({ input: 0, output: 0, total: 0 }, 2, "1024x1024", { perImage: 0.04 });
+ * // → { input: 0, output: 0.08 }
+ */
+declare function computeImageCost(usage: Usage, imageCount: number, size: string | undefined, pricing: ImageModelPricing | undefined): ModelPricing | undefined;
+//#endregion
+export { computeImageCost };
+//# sourceMappingURL=image-cost.d.mts.map

package/esm/image/image-cost.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-cost.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image-cost.ts"],"mappings":";;;;;;;AA4BA;;;;;;;;;;;;;;;;AAKe;;;;;iBALC,gBAAA,CACd,KAAA,EAAO,KAAA,EACP,UAAA,UACA,IAAA,sBACA,OAAA,EAAS,iBAAA,eACR,YAAA"}

package/esm/image/image-cost.mjs

@@ -0,0 +1,55 @@
+import { computeCost } from "../utils/compute-cost.mjs";
+
+//#region ../@warlock.js/ai/src/image/image-cost.ts
+/**
+* Price one image-generation `Usage` against an
+* {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD
+* breakdown so image spend folds into the exact same `Usage.cost`
+* rollup the text path uses (`accumulateCost` / `mergeUsage`). There is
+* no separate image-cost field anywhere downstream — only this one
+* function, which knows the two metering models:
+*
+* - **Per-image** (DALL·E, Imagen): `perImageBySize[size]` (when the
+*   request `size` matches a tier) else flat `perImage`, times the
+*   number of images returned, attributed to `cost.output` (the image
+*   IS the output). Token channels stay 0.
+* - **Token** (gpt-image-1): delegates to the standard
+*   {@link computeCost} against the prompt/image token `Usage`.
+*
+* Per-image wins when both shapes are configured (a provider is one or
+* the other). Returns `undefined` when no usable pricing is present —
+* the framework treats that as "cost unknown", never a false zero.
+*
+* @example
+* computeImageCost({ input: 0, output: 0, total: 0 }, 2, "1024x1024", { perImage: 0.04 });
+* // → { input: 0, output: 0.08 }
+*/
+function computeImageCost(usage, imageCount, size, pricing) {
+	if (!pricing) return;
+	if (pricing.perImage !== void 0 || pricing.perImageBySize !== void 0) {
+		const perImage = resolvePerImageRate(size, pricing);
+		if (perImage === void 0) return;
+		return {
+			input: 0,
+			output: perImage * imageCount
+		};
+	}
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
+/**
+* Resolve the USD-per-image rate: a `perImageBySize` tier matching the
+* requested `size` wins, otherwise the flat `perImage`. Returns
+* `undefined` only when neither is set (the caller already gated on
+* per-image metering being configured at all).
+*/
+function resolvePerImageRate(size, pricing) {
+	if (size !== void 0 && pricing.perImageBySize?.[size] !== void 0) return pricing.perImageBySize[size];
+	return pricing.perImage;
+}
+
+//#endregion
+export { computeImageCost };
+//# sourceMappingURL=image-cost.mjs.map

package/esm/image/image-cost.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-cost.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image-cost.ts"],"sourcesContent":["import type { ImageModelPricing } from \"../contracts/image-model.contract\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { computeCost } from \"../utils/compute-cost\";\n\n/**\n * Price one image-generation `Usage` against an\n * {@link ImageModelPricing}, returning a `ModelPricing`-shaped USD\n * breakdown so image spend folds into the exact same `Usage.cost`\n * rollup the text path uses (`accumulateCost` / `mergeUsage`). There is\n * no separate image-cost field anywhere downstream — only this one\n * function, which knows the two metering models:\n *\n * - **Per-image** (DALL·E, Imagen): `perImageBySize[size]` (when the\n *   request `size` matches a tier) else flat `perImage`, times the\n *   number of images returned, attributed to `cost.output` (the image\n *   IS the output). Token channels stay 0.\n * - **Token** (gpt-image-1): delegates to the standard\n *   {@link computeCost} against the prompt/image token `Usage`.\n *\n * Per-image wins when both shapes are configured (a provider is one or\n * the other). Returns `undefined` when no usable pricing is present —\n * the framework treats that as \"cost unknown\", never a false zero.\n *\n * @example\n * computeImageCost({ input: 0, output: 0, total: 0 }, 2, \"1024x1024\", { perImage: 0.04 });\n * // → { input: 0, output: 0.08 }\n */\nexport function computeImageCost(\n  usage: Usage,\n  imageCount: number,\n  size: string | undefined,\n  pricing: ImageModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  const perImageMetered = pricing.perImage !== undefined || pricing.perImageBySize !== undefined;\n\n  if (perImageMetered) {\n    const perImage = resolvePerImageRate(size, pricing);\n\n    if (perImage === undefined) {\n      return undefined;\n    }\n\n    return { input: 0, output: perImage * imageCount };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve the USD-per-image rate: a `perImageBySize` tier matching the\n * requested `size` wins, otherwise the flat `perImage`. Returns\n * `undefined` only when neither is set (the caller already gated on\n * per-image metering being configured at all).\n */\nfunction resolvePerImageRate(\n  size: string | undefined,\n  pricing: ImageModelPricing,\n): number | undefined {\n  if (size !== undefined && pricing.perImageBySize?.[size] !== undefined) {\n    return pricing.perImageBySize[size];\n  }\n\n  return pricing.perImage;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iBACd,OACA,YACA,MACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAKF,IAFwB,QAAQ,aAAa,UAAa,QAAQ,mBAAmB,QAEhE;EACnB,MAAM,WAAW,oBAAoB,MAAM,OAAO;EAElD,IAAI,aAAa,QACf;EAGF,OAAO;GAAE,OAAO;GAAG,QAAQ,WAAW;EAAW;CACnD;CAEA,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;;;;;;AAQA,SAAS,oBACP,MACA,SACoB;CACpB,IAAI,SAAS,UAAa,QAAQ,iBAAiB,UAAU,QAC3D,OAAO,QAAQ,eAAe;CAGhC,OAAO,QAAQ;AACjB"}

package/esm/image/image.d.mts

@@ -0,0 +1,92 @@
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
+import { FlowObserveOption } from "../observe/resolve-observers.mjs";
+import { GeneratedImage, ImageModelContract } from "../contracts/image-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/image/image.d.ts
+/**
+ * Parameters for {@link image}. `model` comes from an adapter's
+ * `image()` factory (`openai.image({ name })` / `google.image({ name })`);
+ * the rest are provider-neutral generation knobs plus the standard
+ * observability seam every verb shares.
+ */
+type ImageParams = {
+  /** The image model to generate from (`sdk.image({ name })`). */model: ImageModelContract; /** Text description of the image(s) to generate. */
+  prompt: string; /** How many images to generate. Adapters clamp to the provider max. */
+  count?: number; /** Requested pixel size as `"WxH"` (e.g. `"1024x1024"`). */
+  size?: string; /** Quality tier (e.g. `"standard"` / `"hd"`). */
+  quality?: string; /** Aspect ratio (e.g. `"1:1"`, `"16:9"`) — ratio-based providers (Imagen). */
+  aspectRatio?: string; /** Concepts to steer 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;
+  /**
+   * Observability routing for this call — same `observe` seam as
+   * agents / workflows. `true` routes to the globally registered
+   * observers; an `Observer` object routes flow-locally; `false` opts
+   * out; omitted follows the global observe-all flag.
+   */
+  observe?: FlowObserveOption; /** Groups this call into a session for flat cost/trace queries. */
+  sessionId?: string; /** Report node name (defaults to `"image"`). */
+  name?: string; /** Provider-specific options forwarded verbatim to the adapter. */
+  options?: Record<string, unknown>;
+};
+/** Success payload of an {@link image} run. */
+type ImageData = {
+  /** The generated images, normalized to the discriminated shape. */images: GeneratedImage[];
+};
+/**
+ * The report node an {@link image} run produces — a {@link BaseReport}
+ * (`type: "image"`) plus which model ran and how many images came back,
+ * so panoptic and any flat-row consumer attribute the cost/latency
+ * without special-casing.
+ */
+type ImageReport = BaseReport & {
+  type: "image"; /** Identity of the image model this run used. */
+  model: {
+    name: string;
+    provider: string;
+  }; /** Number of images returned (0 on failure). */
+  imageCount: number;
+};
+/**
+ * Result envelope of {@link image} — the same uniform
+ * `{ data, error, usage, report }` every executable returns, narrowed
+ * with the `"image"` discriminant.
+ */
+type ImageResult = ExecuteResult<ImageData> & {
+  type: "image";
+  report: ImageReport;
+};
+/**
+ * Generate one or more images from a text prompt — the image-output
+ * counterpart to `ai.agent`, and the first verb of the output-modality
+ * track (Theme I). Wraps an {@link ImageModelContract} (from
+ * `openai.image(...)` / `google.image(...)`) in the framework's uniform
+ * result contract:
+ *
+ * - **Never throws.** Provider failures (auth, rate-limit,
+ *   content-filter, invalid request) surface as a typed `AIError` on
+ *   `result.error`; `result.data` is then `undefined`.
+ * - **Cost-truth.** When the model carries pricing, `result.usage.cost`
+ *   is filled in — per-token for gpt-image-1, per-image for
+ *   DALL·E / Imagen — folding into the same `Usage.cost` rollup as text.
+ * - **Observable.** The completed {@link ImageReport} routes to any
+ *   registered `Observer` (panoptic, OTel, …) via the shared `observe`
+ *   seam, exactly like an agent run.
+ *
+ * @example
+ * const openai = new OpenAISDK({ apiKey });
+ * const { data, error, usage } = await ai.image({
+ *   model: openai.image({ name: "gpt-image-1" }),
+ *   prompt: "an isometric office desk, soft studio lighting",
+ *   size: "1024x1024",
+ * });
+ *
+ * if (error) console.warn(error.code);
+ * else for (const img of data.images) save(img); // { type: "base64" | "url", ... }
+ */
+declare function image(params: ImageParams): Promise<ImageResult>;
+//#endregion
+export { ImageData, ImageParams, ImageReport, ImageResult, image };
+//# sourceMappingURL=image.d.mts.map

package/esm/image/image.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image.ts"],"mappings":";;;;;;;;AAsBA;;;;KAAY,WAAA;EAyBA,gEAvBV,KAAA,EAAO,kBAAA,EA6BS;EA3BhB,MAAA,UAFA;EAIA,KAAA,WAFA;EAIA,IAAA;EAEA,OAAA,WAEA;EAAA,WAAA,WAIA;EAFA,cAAA,WAIS;EAFT,MAAA,WASU;EAPV,MAAA,GAAS,WAAA;EAWT;;;;AAEgB;AAIlB;EAVE,OAAA,GAAU,iBAAA;EAEV,SAAA,WAUsB;EARtB,IAAA,WAiBqB;EAfrB,OAAA,GAAU,MAAA;AAAA;;KAIA,SAAA;EAcV,mEAZA,MAAA,EAAQ,cAAc;AAAA;;;AAcZ;AAQZ;;;KAbY,WAAA,GAAc,UAAU;EAClC,IAAA,WAcQ;EAZR,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA,GAWvB;EATA,UAAA;AAAA;;AAUmB;AA+BrB;;;KAjCY,WAAA,GAAc,aAAA,CAAc,SAAA;EACtC,IAAA;EACA,MAAA,EAAQ,WAAA;AAAA;;;;;;;AA+B2D;;;;;;;;;;;;;;;;;;;;;;iBAA/C,KAAA,CAAM,MAAA,EAAQ,WAAA,GAAc,OAAA,CAAQ,WAAA"}

package/esm/image/image.mjs

@@ -0,0 +1,113 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { ProviderError } from "../errors/provider-error.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
+import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import { notifyObservers } from "../observe/resolve-observers.mjs";
+import { computeImageCost } from "./image-cost.mjs";
+
+//#region ../@warlock.js/ai/src/image/image.ts
+/**
+* Generate one or more images from a text prompt — the image-output
+* counterpart to `ai.agent`, and the first verb of the output-modality
+* track (Theme I). Wraps an {@link ImageModelContract} (from
+* `openai.image(...)` / `google.image(...)`) in the framework's uniform
+* result contract:
+*
+* - **Never throws.** Provider failures (auth, rate-limit,
+*   content-filter, invalid request) surface as a typed `AIError` on
+*   `result.error`; `result.data` is then `undefined`.
+* - **Cost-truth.** When the model carries pricing, `result.usage.cost`
+*   is filled in — per-token for gpt-image-1, per-image for
+*   DALL·E / Imagen — folding into the same `Usage.cost` rollup as text.
+* - **Observable.** The completed {@link ImageReport} routes to any
+*   registered `Observer` (panoptic, OTel, …) via the shared `observe`
+*   seam, exactly like an agent run.
+*
+* @example
+* const openai = new OpenAISDK({ apiKey });
+* const { data, error, usage } = await ai.image({
+*   model: openai.image({ name: "gpt-image-1" }),
+*   prompt: "an isometric office desk, soft studio lighting",
+*   size: "1024x1024",
+* });
+*
+* if (error) console.warn(error.code);
+* else for (const img of data.images) save(img); // { type: "base64" | "url", ... }
+*/
+async function image(params) {
+	const { model, prompt } = params;
+	const runId = generateRunId("image");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let imageCount = 0;
+	try {
+		const response = await model.generate(prompt, {
+			count: params.count,
+			size: params.size,
+			quality: params.quality,
+			aspectRatio: params.aspectRatio,
+			negativePrompt: params.negativePrompt,
+			format: params.format,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		if (usage.cost === void 0) {
+			const cost = computeImageCost(usage, response.images.length, params.size, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
+		}
+		data = { images: response.images };
+		imageCount = response.images.length;
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
+	}
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "image",
+		type: "image",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		imageCount,
+		reportSchemaVersion: 1
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	await notifyObservers(params.observe, report);
+	return {
+		type: "image",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+export { image };
+//# sourceMappingURL=image.mjs.map

package/esm/image/image.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/image/image.ts"],"sourcesContent":["import type {\n  GeneratedImage,\n  ImageModelContract,\n} from \"../contracts/image-model.contract\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\nimport { computeImageCost } from \"./image-cost\";\n\n/**\n * Parameters for {@link image}. `model` comes from an adapter's\n * `image()` factory (`openai.image({ name })` / `google.image({ name })`);\n * the rest are provider-neutral generation knobs plus the standard\n * observability seam every verb shares.\n */\nexport type ImageParams = {\n  /** The image model to generate from (`sdk.image({ name })`). */\n  model: ImageModelContract;\n  /** Text description of the image(s) to generate. */\n  prompt: string;\n  /** How many images to generate. Adapters clamp to the provider max. */\n  count?: number;\n  /** Requested pixel size as `\"WxH\"` (e.g. `\"1024x1024\"`). */\n  size?: string;\n  /** Quality tier (e.g. `\"standard\"` / `\"hd\"`). */\n  quality?: string;\n  /** Aspect ratio (e.g. `\"1:1\"`, `\"16:9\"`) — ratio-based providers (Imagen). */\n  aspectRatio?: string;\n  /** Concepts to steer away from (Imagen `negativePrompt`). */\n  negativePrompt?: string;\n  /** Output container hint (`\"png\"` / `\"jpeg\"` / `\"webp\"`). */\n  format?: string;\n  /** Cancellation handle, wired into the provider request where supported. */\n  signal?: AbortSignal;\n  /**\n   * Observability routing for this call — same `observe` seam as\n   * agents / workflows. `true` routes to the globally registered\n   * observers; an `Observer` object routes flow-locally; `false` opts\n   * out; omitted follows the global observe-all flag.\n   */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"image\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of an {@link image} run. */\nexport type ImageData = {\n  /** The generated images, normalized to the discriminated shape. */\n  images: GeneratedImage[];\n};\n\n/**\n * The report node an {@link image} run produces — a {@link BaseReport}\n * (`type: \"image\"`) plus which model ran and how many images came back,\n * so panoptic and any flat-row consumer attribute the cost/latency\n * without special-casing.\n */\nexport type ImageReport = BaseReport & {\n  type: \"image\";\n  /** Identity of the image model this run used. */\n  model: { name: string; provider: string };\n  /** Number of images returned (0 on failure). */\n  imageCount: number;\n};\n\n/**\n * Result envelope of {@link image} — the same uniform\n * `{ data, error, usage, report }` every executable returns, narrowed\n * with the `\"image\"` discriminant.\n */\nexport type ImageResult = ExecuteResult<ImageData> & {\n  type: \"image\";\n  report: ImageReport;\n};\n\n/**\n * Generate one or more images from a text prompt — the image-output\n * counterpart to `ai.agent`, and the first verb of the output-modality\n * track (Theme I). Wraps an {@link ImageModelContract} (from\n * `openai.image(...)` / `google.image(...)`) in the framework's uniform\n * result contract:\n *\n * - **Never throws.** Provider failures (auth, rate-limit,\n *   content-filter, invalid request) surface as a typed `AIError` on\n *   `result.error`; `result.data` is then `undefined`.\n * - **Cost-truth.** When the model carries pricing, `result.usage.cost`\n *   is filled in — per-token for gpt-image-1, per-image for\n *   DALL·E / Imagen — folding into the same `Usage.cost` rollup as text.\n * - **Observable.** The completed {@link ImageReport} routes to any\n *   registered `Observer` (panoptic, OTel, …) via the shared `observe`\n *   seam, exactly like an agent run.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error, usage } = await ai.image({\n *   model: openai.image({ name: \"gpt-image-1\" }),\n *   prompt: \"an isometric office desk, soft studio lighting\",\n *   size: \"1024x1024\",\n * });\n *\n * if (error) console.warn(error.code);\n * else for (const img of data.images) save(img); // { type: \"base64\" | \"url\", ... }\n */\nexport async function image(params: ImageParams): Promise<ImageResult> {\n  const { model, prompt } = params;\n\n  const runId = generateRunId(\"image\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: ImageData | undefined;\n  let error: AIError | undefined;\n  let status: ImageReport[\"status\"] = \"completed\";\n  let imageCount = 0;\n\n  try {\n    const response = await model.generate(prompt, {\n      count: params.count,\n      size: params.size,\n      quality: params.quality,\n      aspectRatio: params.aspectRatio,\n      negativePrompt: params.negativePrompt,\n      format: params.format,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    // Preserve every usage channel the adapter reported (cached /\n    // reasoning / cache-write, and any adapter-supplied `cost`), mirroring\n    // how the agent path routes provider usage. Then honor a pre-priced\n    // response or compute image cost — `usage.cost ??= …` precedence, same\n    // as the agent path.\n    Object.assign(usage, response.usage);\n\n    if (usage.cost === undefined) {\n      const cost = computeImageCost(usage, response.images.length, params.size, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { images: response.images };\n    imageCount = response.images.length;\n  } catch (thrown) {\n    error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    // A caller-aborted run is \"cancelled\", not \"failed\" — keep the typed\n    // cause but distinguish the terminal status for dashboards/retry policy.\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: ImageReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"image\",\n    type: \"image\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    imageCount,\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"image\", data, error, usage, report };\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkHA,eAAsB,MAAM,QAA2C;CACrE,MAAM,EAAE,OAAO,WAAW;CAE1B,MAAM,QAAQ,cAAc,OAAO;CACnC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAgC;CACpC,IAAI,aAAa;CAEjB,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,SAAS,QAAQ;GAC5C,OAAO,OAAO;GACd,MAAM,OAAO;GACb,SAAS,OAAO;GAChB,aAAa,OAAO;GACpB,gBAAgB,OAAO;GACvB,QAAQ,OAAO;GACf,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAOD,OAAO,OAAO,OAAO,SAAS,KAAK;EAEnC,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,iBAAiB,OAAO,SAAS,OAAO,QAAQ,OAAO,MAAM,MAAM,OAAO;GACvF,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO,EAAE,QAAQ,SAAS,OAAO;EACjC,aAAa,SAAS,OAAO;CAC/B,SAAS,QAAQ;EACf,QAAQ,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAGnG,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAAsB;EAC1B;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD;EACA;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAS;EAAM;EAAO;EAAO;CAAO;AACrD;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}