@effect-uai/core 0.12.1 → 0.14.0

package/dist/streaming/Multipart.d.mts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import { HttpClientRequest } from "effect/unstable/http";
+declare namespace Multipart_d_exports {
+  export { bodyMultipart };
+}
+/**
+ * Multipart body for an `HttpClientRequest`, encoded to bytes.
+ *
+ * Use this over `HttpClientRequest.bodyFormData`: the Undici client
+ * passes the `FormData` object straight to `dispatcher.request`, which
+ * cannot serialise it, so the request is never sent and the effect
+ * hangs with no error. Encoding here produces the same bytes every
+ * other client derives internally, so it works on all of them.
+ *
+ * The failure is whatever `Response.arrayBuffer` rejects with; map it
+ * to your provider's transport error at the call site.
+ */
+declare const bodyMultipart: (form: FormData) => Effect.Effect<(request: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest, unknown>;
+//#endregion
+export { bodyMultipart, Multipart_d_exports as t };
+//# sourceMappingURL=Multipart.d.mts.map

package/dist/streaming/Multipart.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Multipart.d.mts","names":[],"sources":["../../src/streaming/Multipart.ts"],"mappings":";;;;;;;;;;;;;;;;;cAea,gBAAa,MAClB,aACL,OAAO,QACP,SAAS,kBAAkB,sBAAsB,kBAAkB"}

package/dist/streaming/Multipart.mjs

@@ -0,0 +1,26 @@
+import { n as __exportAll } from "../rolldown-runtime-EAsCxrDo.mjs";
+import { Effect } from "effect";
+import { HttpClientRequest } from "effect/unstable/http";
+//#region src/streaming/Multipart.ts
+var Multipart_exports = /* @__PURE__ */ __exportAll({ bodyMultipart: () => bodyMultipart });
+/**
+* Multipart body for an `HttpClientRequest`, encoded to bytes.
+*
+* Use this over `HttpClientRequest.bodyFormData`: the Undici client
+* passes the `FormData` object straight to `dispatcher.request`, which
+* cannot serialise it, so the request is never sent and the effect
+* hangs with no error. Encoding here produces the same bytes every
+* other client derives internally, so it works on all of them.
+*
+* The failure is whatever `Response.arrayBuffer` rejects with; map it
+* to your provider's transport error at the call site.
+*/
+const bodyMultipart = (form) => Effect.gen(function* () {
+	const encoded = new Response(form);
+	const buffer = yield* Effect.tryPromise(() => encoded.arrayBuffer());
+	return HttpClientRequest.bodyUint8Array(new Uint8Array(buffer), encoded.headers.get("content-type") ?? "multipart/form-data");
+});
+//#endregion
+export { bodyMultipart, Multipart_exports as t };
+
+//# sourceMappingURL=Multipart.mjs.map

package/dist/streaming/Multipart.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Multipart.mjs","names":[],"sources":["../../src/streaming/Multipart.ts"],"sourcesContent":["import { Effect } from \"effect\"\nimport { HttpClientRequest } from \"effect/unstable/http\"\n\n/**\n * Multipart body for an `HttpClientRequest`, encoded to bytes.\n *\n * Use this over `HttpClientRequest.bodyFormData`: the Undici client\n * passes the `FormData` object straight to `dispatcher.request`, which\n * cannot serialise it, so the request is never sent and the effect\n * hangs with no error. Encoding here produces the same bytes every\n * other client derives internally, so it works on all of them.\n *\n * The failure is whatever `Response.arrayBuffer` rejects with; map it\n * to your provider's transport error at the call site.\n */\nexport const bodyMultipart = (\n  form: FormData,\n): Effect.Effect<\n  (request: HttpClientRequest.HttpClientRequest) => HttpClientRequest.HttpClientRequest,\n  unknown\n> =>\n  Effect.gen(function* () {\n    const encoded = new Response(form)\n    const buffer = yield* Effect.tryPromise(() => encoded.arrayBuffer())\n    return HttpClientRequest.bodyUint8Array(\n      new Uint8Array(buffer),\n      encoded.headers.get(\"content-type\") ?? \"multipart/form-data\",\n    )\n  })\n"],"mappings":";;;;;;;;;;;;;;;;;AAeA,MAAa,iBACX,SAKA,OAAO,IAAI,aAAa;CACtB,MAAM,UAAU,IAAI,SAAS,IAAI;CACjC,MAAM,SAAS,OAAO,OAAO,iBAAiB,QAAQ,YAAY,CAAC;CACnE,OAAO,kBAAkB,eACvB,IAAI,WAAW,MAAM,GACrB,QAAQ,QAAQ,IAAI,cAAc,KAAK,qBACzC;AACF,CAAC"}

package/dist/testing/MockMusicGenerator.d.mts

@@ -1,4 +1,4 @@
-import { n as AudioChunk } from "../Audio-60lKKHxS.mjs";
+import { n as AudioChunk } from "../Audio-_nGR4V0X.mjs";
 import { CommonGenerateMusicRequest, CommonStreamGenerateMusicRequest, GenerateResult, MusicStreamEvent, audioEvent } from "../domain/Music.mjs";
 import { MusicGenerator, MusicInteractiveSession } from "../music-generator/MusicGenerator.mjs";
 import { Effect, Layer } from "effect";

package/dist/testing/MockProvider.d.mts

@@ -1,4 +1,4 @@
-import { o as HistoryItem } from "../Items-SfUabNuB.mjs";
+import { o as HistoryItem } from "../Items-C7MyrYPX.mjs";
 import { Turn } from "../domain/Turn.mjs";
 import { LanguageModel, LanguageModelService } from "../language-model/LanguageModel.mjs";
 import { Duration, Effect, Layer } from "effect";

package/dist/testing/MockSpeechSynthesizer.d.mts

@@ -1,4 +1,4 @@
-import { n as AudioChunk, t as AudioBlob } from "../Audio-60lKKHxS.mjs";
+import { n as AudioChunk, t as AudioBlob } from "../Audio-_nGR4V0X.mjs";
 import { CommonStreamSynthesizeRequest, CommonSynthesizeDialogueRequest, CommonSynthesizeRequest, MultiSpeakerTts, SpeechSynthesizer, TtsIncrementalText } from "../speech-synthesizer/SpeechSynthesizer.mjs";
 import { Effect, Layer } from "effect";
 //#region src/testing/MockSpeechSynthesizer.d.ts

package/dist/tokenizer/Tokenizer.d.mts

@@ -0,0 +1,22 @@
+import { Context } from "effect";
+declare namespace Tokenizer_d_exports {
+  export { Tokenizer, TokenizerService };
+}
+/**
+ * Turning text into tokens, for sizing chunks, budgeting context, and
+ * estimating usage a provider does not report. Count with `encode(text).length`.
+ *
+ * Implementor contract: both methods are synchronous, so counting inside a loop
+ * never awaits; loading a vocabulary is the layer's job. `decode` inverts
+ * `encode`. Implement this only over a real vocabulary, never a heuristic:
+ * a character-count estimate is a plain function, not a service.
+ */
+type TokenizerService = {
+  readonly encode: (text: string) => ReadonlyArray<number>;
+  readonly decode: (tokens: ReadonlyArray<number>) => string;
+};
+declare const Tokenizer_base: Context.ServiceClass<Tokenizer, "@betalyra/effect-uai/Tokenizer", TokenizerService>;
+declare class Tokenizer extends Tokenizer_base {}
+//#endregion
+export { Tokenizer, TokenizerService, Tokenizer_d_exports as t };
+//# sourceMappingURL=Tokenizer.d.mts.map

package/dist/tokenizer/Tokenizer.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tokenizer.d.mts","names":[],"sources":["../../src/tokenizer/Tokenizer.ts"],"mappings":";;;;;;;;;;;;;KAWY;WACD,SAAS,iBAAiB;WAC1B,SAAS,QAAQ;;;cAGf,kBAAkB"}

package/dist/tokenizer/Tokenizer.mjs

@@ -0,0 +1,9 @@
+import { n as __exportAll } from "../rolldown-runtime-EAsCxrDo.mjs";
+import { Context } from "effect";
+//#region src/tokenizer/Tokenizer.ts
+var Tokenizer_exports = /* @__PURE__ */ __exportAll({ Tokenizer: () => Tokenizer });
+var Tokenizer = class extends Context.Service()("@betalyra/effect-uai/Tokenizer") {};
+//#endregion
+export { Tokenizer, Tokenizer_exports as t };
+
+//# sourceMappingURL=Tokenizer.mjs.map

package/dist/tokenizer/Tokenizer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tokenizer.mjs","names":[],"sources":["../../src/tokenizer/Tokenizer.ts"],"sourcesContent":["import { Context } from \"effect\"\n\n/**\n * Turning text into tokens, for sizing chunks, budgeting context, and\n * estimating usage a provider does not report. Count with `encode(text).length`.\n *\n * Implementor contract: both methods are synchronous, so counting inside a loop\n * never awaits; loading a vocabulary is the layer's job. `decode` inverts\n * `encode`. Implement this only over a real vocabulary, never a heuristic:\n * a character-count estimate is a plain function, not a service.\n */\nexport type TokenizerService = {\n  readonly encode: (text: string) => ReadonlyArray<number>\n  readonly decode: (tokens: ReadonlyArray<number>) => string\n}\n\nexport class Tokenizer extends Context.Service<Tokenizer, TokenizerService>()(\n  \"@betalyra/effect-uai/Tokenizer\",\n) {}\n"],"mappings":";;;;AAgBA,IAAa,YAAb,cAA+B,QAAQ,QAAqC,CAAC,CAC3E,gCACF,CAAC,CAAC,CAAC"}

package/dist/tool/Approval.d.mts

@@ -1,6 +1,6 @@
-import { v as ToolCall } from "../Items-SfUabNuB.mjs";
-import { t as ToolResult } from "../ToolResult-Cj8ChodL.mjs";
-import { t as ToolEvent } from "../ToolEvent-D99MGQYH.mjs";
+import { y as ToolCall } from "../Items-C7MyrYPX.mjs";
+import { t as ToolResult } from "../ToolResult-BsYQRjmW.mjs";
+import { t as ToolEvent } from "../ToolEvent-Di4a723B.mjs";
 import { Data, Duration, Effect, Queue, Scope, Stream } from "effect";
 declare namespace Approval_d_exports {
   export { ApprovalDecision, ApprovalMapEntry, FromQueueOptions, ToolCallPlan, Verdict, approvalRequested, approve, fromMap, fromQueue, reject, splitApprovalDecisions };

package/dist/tool/HistoryCheck.d.mts

@@ -1,5 +1,5 @@
-import { o as HistoryItem, v as ToolCall } from "../Items-SfUabNuB.mjs";
-import { t as ToolResult } from "../ToolResult-Cj8ChodL.mjs";
+import { o as HistoryItem, y as ToolCall } from "../Items-C7MyrYPX.mjs";
+import { t as ToolResult } from "../ToolResult-BsYQRjmW.mjs";
 declare namespace HistoryCheck_d_exports {
   export { cancelAllPending, findUnansweredCalls, isReconciled };
 }

package/dist/tool/Tool.d.mts

@@ -1,2 +1,2 @@
-import { A as providerToolsOf, C as fromEffectSchema, D as make, E as isProviderTool, M as toDescriptors, N as withName, O as noInput, P as withRun, S as fail, T as interaction, a as Emit, b as descriptorsOf, c as SignalTool, d as ToolE, f as ToolError, g as ToolValidationError, h as ToolR, i as DecodeResult, j as signal, k as provider, l as Tool, m as ToolInputSchema, n as AnyTool, o as InteractionTool, p as ToolFailed, r as DecodableTool, s as ProviderTool, t as AnyLocalTool, u as ToolDescriptor, v as decodeArgs, w as fromStandardSchema, x as execute, y as decodeCallInput } from "../Tool-DE-rnvkw.mjs";
+import { A as providerToolsOf, C as fromEffectSchema, D as make, E as isProviderTool, M as toDescriptors, N as withName, O as noInput, P as withRun, S as fail, T as interaction, a as Emit, b as descriptorsOf, c as SignalTool, d as ToolE, f as ToolError, g as ToolValidationError, h as ToolR, i as DecodeResult, j as signal, k as provider, l as Tool, m as ToolInputSchema, n as AnyTool, o as InteractionTool, p as ToolFailed, r as DecodableTool, s as ProviderTool, t as AnyLocalTool, u as ToolDescriptor, v as decodeArgs, w as fromStandardSchema, x as execute, y as decodeCallInput } from "../Tool-BF78QWtn.mjs";
 export { AnyLocalTool, AnyTool, DecodableTool, DecodeResult, Emit, InteractionTool, ProviderTool, SignalTool, Tool, ToolDescriptor, ToolE, ToolError, ToolFailed, ToolInputSchema, ToolR, ToolValidationError, decodeArgs, decodeCallInput, descriptorsOf, execute, fail, fromEffectSchema, fromStandardSchema, interaction, isProviderTool, make, noInput, provider, providerToolsOf, signal, toDescriptors, withName, withRun };

package/dist/tool/ToolEvent.d.mts

@@ -1,2 +1,2 @@
-import { a as isProgress, i as isOutput, r as isApprovalRequested, t as ToolEvent } from "../ToolEvent-D99MGQYH.mjs";
+import { a as isProgress, i as isOutput, r as isApprovalRequested, t as ToolEvent } from "../ToolEvent-Di4a723B.mjs";
 export { ToolEvent, isApprovalRequested, isOutput, isProgress };

package/dist/tool/ToolResult.d.mts

@@ -1,2 +1,2 @@
-import { a as executionError, c as isOk, d as toToolCallOutput, f as validationError, i as denied, l as nonLocalTool, o as failed, r as cancelled, s as isFailure, t as ToolResult, u as serializeValue } from "../ToolResult-Cj8ChodL.mjs";
+import { a as executionError, c as isOk, d as toToolCallOutput, f as validationError, i as denied, l as nonLocalTool, o as failed, r as cancelled, s as isFailure, t as ToolResult, u as serializeValue } from "../ToolResult-BsYQRjmW.mjs";
 export { ToolResult, cancelled, denied, executionError, failed, isFailure, isOk, nonLocalTool, serializeValue, toToolCallOutput, validationError };

package/dist/tool/Toolkit.d.mts

@@ -1,2 +1,2 @@
-import { S as wrap, _ as fromArray, a as ToolMap, b as namespace, c as ToolkitR, d as appendToolResults, f as collectResults, g as descriptors, h as describeFailures, i as NoDuplicateNames, m as continueWithResults, n as ExecuteOptions, o as Toolkit, p as compose, r as Middleware, s as ToolkitE, t as DuplicateToolName, u as UniqueTools, v as make, x as run, y as makeNamespaced } from "../Toolkit-BEZrNPTI.mjs";
+import { S as wrap, _ as fromArray, a as ToolMap, b as namespace, c as ToolkitR, d as appendToolResults, f as collectResults, g as descriptors, h as describeFailures, i as NoDuplicateNames, m as continueWithResults, n as ExecuteOptions, o as Toolkit, p as compose, r as Middleware, s as ToolkitE, t as DuplicateToolName, u as UniqueTools, v as make, x as run, y as makeNamespaced } from "../Toolkit-DAjJ9Tvl.mjs";
 export { DuplicateToolName, ExecuteOptions, Middleware, NoDuplicateNames, ToolMap, Toolkit, ToolkitE, ToolkitR, UniqueTools, appendToolResults, collectResults, compose, continueWithResults, describeFailures, descriptors, fromArray, make, makeNamespaced, namespace, run, wrap };

package/dist/transcriber/Transcriber.d.mts

@@ -1,5 +1,5 @@
 import { t as AiError } from "../AiError-eLV9t1lU.mjs";
-import { a as AudioSource, r as AudioFormat } from "../Audio-60lKKHxS.mjs";
+import { a as AudioSource, r as AudioFormat } from "../Audio-_nGR4V0X.mjs";
 import { TranscriptEvent, TranscriptResult } from "../domain/Transcript.mjs";
 import { Context, Effect, Stream } from "effect";
 declare namespace Transcriber_d_exports {

package/dist/web-read/WebReadTool.d.mts

@@ -1,4 +1,4 @@
-import { l as Tool } from "../Tool-DE-rnvkw.mjs";
+import { l as Tool } from "../Tool-BF78QWtn.mjs";
 import { t as AiError } from "../AiError-eLV9t1lU.mjs";
 import { ReadFormat, ReadResponse, WebRead } from "./WebRead.mjs";
 import { Schema } from "effect";

package/dist/web-search/WebSearchTool.d.mts

@@ -1,4 +1,4 @@
-import { l as Tool } from "../Tool-DE-rnvkw.mjs";
+import { l as Tool } from "../Tool-BF78QWtn.mjs";
 import { t as AiError } from "../AiError-eLV9t1lU.mjs";
 import { SearchResult, WebSearch } from "./WebSearch.mjs";
 import { Schema } from "effect";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -42,6 +42,10 @@
       "types": "./dist/domain/Audio.d.mts",
       "import": "./dist/domain/Audio.mjs"
     },
+    "./Chunker": {
+      "types": "./dist/chunker/Chunker.d.mts",
+      "import": "./dist/chunker/Chunker.mjs"
+    },
     "./Citation": {
       "types": "./dist/domain/Citation.d.mts",
       "import": "./dist/domain/Citation.mjs"
@@ -102,6 +106,10 @@
       "types": "./dist/embedding-model/EmbeddingModel.d.mts",
       "import": "./dist/embedding-model/EmbeddingModel.mjs"
     },
+    "./ImageGenerator": {
+      "types": "./dist/image-generator/ImageGenerator.d.mts",
+      "import": "./dist/image-generator/ImageGenerator.mjs"
+    },
     "./LanguageModel": {
       "types": "./dist/language-model/LanguageModel.d.mts",
       "import": "./dist/language-model/LanguageModel.mjs"
@@ -110,6 +118,10 @@
       "types": "./dist/music-generator/MusicGenerator.d.mts",
       "import": "./dist/music-generator/MusicGenerator.mjs"
     },
+    "./Reranker": {
+      "types": "./dist/reranker/Reranker.d.mts",
+      "import": "./dist/reranker/Reranker.mjs"
+    },
     "./Memory": {
       "types": "./dist/sandbox/Memory.d.mts",
       "import": "./dist/sandbox/Memory.mjs"
@@ -166,6 +178,10 @@
       "types": "./dist/math/Vector.d.mts",
       "import": "./dist/math/Vector.mjs"
     },
+    "./Tokenizer": {
+      "types": "./dist/tokenizer/Tokenizer.d.mts",
+      "import": "./dist/tokenizer/Tokenizer.mjs"
+    },
     "./Tool": {
       "types": "./dist/tool/Tool.d.mts",
       "import": "./dist/tool/Tool.mjs"
@@ -202,6 +218,10 @@
       "types": "./dist/streaming/Lines.d.mts",
       "import": "./dist/streaming/Lines.mjs"
     },
+    "./Multipart": {
+      "types": "./dist/streaming/Multipart.d.mts",
+      "import": "./dist/streaming/Multipart.mjs"
+    },
     "./SSE": {
       "types": "./dist/streaming/SSE.d.mts",
       "import": "./dist/streaming/SSE.mjs"

package/src/capabilities/Capabilities.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import type { ContentBlock, HistoryItem } from "../domain/Items.js"
 
 /**
  * Structured event emitted when a provider adapter drops a Common
@@ -79,3 +80,40 @@ export const warnDroppedWhen = <T>(
   value: T | undefined,
   warning: Omit<CapabilityWarning, "_tag" | "value">,
 ): Effect.Effect<void> => (value === undefined ? Effect.void : warnDropped({ ...warning, value }))
+
+/**
+ * Warn when history carries a content block this provider's wire has no
+ * place for, which its encoder therefore omits.
+ *
+ * History is provider-agnostic, so a turn one provider produced can be
+ * replayed into another. A block only one provider can express
+ * (`output_image`, which needs an assistant-role image part) then reaches
+ * an encoder with nothing to map it to. Omitting is right, since failing
+ * would break replaying a mixed history just to continue the text, but it
+ * should not be silent.
+ *
+ * Call once from the effectful request path; the block encoders stay pure.
+ *
+ * @example
+ * ```ts
+ * yield* warnDroppedBlocks(history, "output_image", {
+ *   provider: "anthropic",
+ *   capability: "output_image",
+ *   reason: "Assistant messages carry no image here. Convert with `imagesAsInput` to send it as user content.",
+ * })
+ * ```
+ */
+export const warnDroppedBlocks = (
+  history: ReadonlyArray<HistoryItem>,
+  type: ContentBlock["type"],
+  warning: Omit<CapabilityWarning, "_tag" | "field" | "value">,
+): Effect.Effect<void> => {
+  const count = history.reduce(
+    (n, item) =>
+      n + (item.type === "message" ? item.content.filter((b) => b.type === type).length : 0),
+    0,
+  )
+  return count === 0
+    ? Effect.void
+    : warnDropped({ ...warning, field: type, value: `${count} block(s)` })
+}

package/src/chunker/Chunker.ts

@@ -0,0 +1,34 @@
+import { Context, Effect } from "effect"
+import type * as AiError from "../domain/AiError.js"
+
+/**
+ * A passage of a document, with the character offsets it came from.
+ *
+ * Implementor contract: `text` is the input's `[start, end)` slice verbatim,
+ * so a retrieved passage can be traced back to its source and enriched with
+ * what surrounds it. Chunks may overlap.
+ */
+export type Chunk = {
+  readonly text: string
+  readonly start: number
+  readonly end: number
+}
+
+/**
+ * Splitting a document into retrievable passages. Strategy and sizing are
+ * fixed when the layer is built, so callers stay portable across a local
+ * splitter and a hosted chunking service.
+ */
+export type ChunkerService = {
+  readonly chunk: (text: string) => Effect.Effect<ReadonlyArray<Chunk>, AiError.AiError>
+}
+
+export class Chunker extends Context.Service<Chunker, ChunkerService>()(
+  "@betalyra/effect-uai/Chunker",
+) {}
+
+/** Split a document into passages. */
+export const chunk = (
+  text: string,
+): Effect.Effect<ReadonlyArray<Chunk>, AiError.AiError, Chunker> =>
+  Effect.flatMap(Chunker, (chunker) => chunker.chunk(text))

package/src/domain/Image.ts

@@ -1,5 +1,14 @@
-import { Schema } from "effect"
-import type { MediaBase64, MediaBytes, MediaSource, MediaUrl } from "./Media.js"
+import { Result, Schema } from "effect"
+import type {
+  AspectRatio,
+  Dimensions,
+  MediaBase64,
+  MediaBytes,
+  MediaSource,
+  MediaUrl,
+  Watermark,
+} from "./Media.js"
+import { parseAspectRatio, round16 } from "./Media.js"
 
 /**
  * Image MIME types AI providers typically accept. The first four are the
@@ -70,6 +79,63 @@ export const imageBytes = (bytes: Uint8Array, mimeType: ImageMimeType): ImageByt
   mimeType,
 })
 
+/** Cross-modality; lives in `Media.ts` because video generation shares it. */
+export type { AspectRatio, Dimensions } from "./Media.js"
+
+/**
+ * Resolution tier, roughly the short edge in pixels. A tier rather than
+ * a pixel pair: adapters whose wire takes exact dimensions derive them
+ * from the tier and the aspect ratio. Image-typed on purpose, video
+ * models tier by scan height instead.
+ */
+export type ImageResolution = "1K" | "2K" | "4K"
+
+const SHORT_EDGE: Record<ImageResolution, number> = { "1K": 1024, "2K": 2048, "4K": 4096 }
+
+/**
+ * Turn the portable ratio and tier into pixels: the tier is the short
+ * edge, the long edge follows the ratio. `undefined` when neither was
+ * asked for, which the caller sends as "no size" so the endpoint picks.
+ *
+ * Adapters whose wire wants `"WxH"` format the pair; those wanting an
+ * object send it as is. Whether the result is in range for a given model
+ * is the server's call: per-model limits churn and we do not table them.
+ */
+export const pixelsOf = (request: {
+  readonly aspectRatio?: AspectRatio
+  readonly resolution?: ImageResolution
+}): Result.Result<Dimensions | undefined, string> =>
+  request.aspectRatio === undefined && request.resolution === undefined
+    ? Result.succeed(undefined)
+    : Result.map(parseAspectRatio(request.aspectRatio ?? "1:1"), ([w, h]) => {
+        const short = SHORT_EDGE[request.resolution ?? "1K"]
+        return w >= h
+          ? { width: round16((short * w) / h), height: short }
+          : { width: short, height: round16((short * h) / w) }
+      })
+
+/**
+ * Per-image extras a provider reported and this type has no field for:
+ * pixel dimensions, a file name, a revised prompt. Opaque here, and a
+ * shared slot, so a provider keys its data under its own name
+ * (`{ fal: … }`, `{ openai: … }`) and reads only that key. Each provider
+ * package ships a typed reader; the framework never interprets it.
+ *
+ * Not promoted to real fields because the providers disagree on what
+ * they report. Only some fal endpoints return dimensions, and neither
+ * OpenAI's Images API nor Gemini returns them at all.
+ */
+export type ProviderData = unknown
+
+/** One image off a generation call, plus what the provider stamped into it. */
+export type GeneratedImage = {
+  readonly image: ImageSource
+  /** Set only when the provider applies one. */
+  readonly watermark?: Watermark
+  /** {@link ProviderData}: per-image extras, keyed by provider name. */
+  readonly providerData?: ProviderData
+}
+
 export const isImageUrl = Schema.is(ImageUrlSource)
 export const isImageBase64 = Schema.is(ImageBase64Source)
 export const isImageBytes = Schema.is(ImageBytesSource)

package/src/domain/Items.ts

@@ -88,6 +88,22 @@ export const OutputText = Schema.Struct({
 })
 export type OutputText = typeof OutputText.Type
 
+/**
+ * Model-emitted image. The counterpart to {@link InputImage}: same
+ * `ImageSource`, so an image the model drew goes straight back into the
+ * next turn with no conversion.
+ *
+ * How the pixels were produced is not modelled here. A provider may draw
+ * them itself, as an image part of the turn, or reach a hosted tool that
+ * draws them; either way the fact is the same, and enabling it is
+ * provider-specific.
+ */
+export const OutputImage = Schema.Struct({
+  type: Schema.Literal("output_image"),
+  source: ImageSource,
+})
+export type OutputImage = typeof OutputImage.Type
+
 /**
  * Model-emitted refusal. Distinct from `output_text`: the model declined
  * to answer rather than producing normal output. Pair with
@@ -100,7 +116,7 @@ export const Refusal = Schema.Struct({
 })
 export type Refusal = typeof Refusal.Type
 
-export const ContentBlock = Schema.Union([InputText, InputImage, OutputText, Refusal])
+export const ContentBlock = Schema.Union([InputText, InputImage, OutputText, OutputImage, Refusal])
 export type ContentBlock = typeof ContentBlock.Type
 
 export const Role = Schema.Literals(["user", "assistant", "system"])
@@ -176,6 +192,7 @@ export type HistoryItem = typeof HistoryItem.Type
 export const isInputText = Schema.is(InputText)
 export const isInputImage = Schema.is(InputImage)
 export const isOutputText = Schema.is(OutputText)
+export const isOutputImage = Schema.is(OutputImage)
 export const isRefusal = Schema.is(Refusal)
 
 export const isMessage = Schema.is(Message)

package/src/domain/Media.ts

@@ -31,6 +31,72 @@
  * they're a separate union (`FileRef`) added when needed.
  */
 
+import { Result } from "effect"
+
+/**
+ * Watermark kind a provider embedded in generated media. Shared across
+ * modalities (audio, image). No provider exposes metadata beyond the
+ * kind, so a bare literal union is enough.
+ */
+export type Watermark = "synthid" | "c2pa" | (string & {})
+
+/**
+ * Requested shape of generated visual media, width to height. Shared by
+ * image and video generation: the listed ratios are the ones providers
+ * accept as literals, and the `(string & {})` tail keeps a
+ * newly-supported ratio working without an SDK update. Which ratios a
+ * given model accepts is not checked here; the provider rejects what it
+ * cannot render and the adapter translates that error.
+ *
+ * Resolution is NOT shared: image models tier by short edge
+ * (`ImageResolution`), video models by scan height. Each modality types
+ * its own.
+ */
+export type AspectRatio =
+  | "1:1"
+  | "2:3"
+  | "3:2"
+  | "3:4"
+  | "4:3"
+  | "4:5"
+  | "5:4"
+  | "9:16"
+  | "16:9"
+  | "21:9"
+  | "1:4"
+  | "4:1"
+  | "1:8"
+  | "8:1"
+  | (string & {})
+
+/** Exact pixels, for adapters whose wire takes dimensions rather than a ratio. */
+export type Dimensions = {
+  readonly width: number
+  readonly height: number
+}
+
+const positive = (n: number | undefined): n is number =>
+  n !== undefined && Number.isFinite(n) && n > 0
+
+/**
+ * Read `"W:H"` as a pair. Fails when the ratio is not arithmetic, which
+ * the `(string & {})` tail on {@link AspectRatio} lets through: a caller
+ * asking for `"cinematic"` gets a message rather than NaN pixels. The
+ * failure is a plain string so this file stays free of provider
+ * vocabulary; each adapter wraps it in its own error.
+ */
+export const parseAspectRatio = (
+  ratio: AspectRatio,
+): Result.Result<readonly [number, number], string> => {
+  const [w, h, ...rest] = ratio.split(":").map(Number)
+  return positive(w) && positive(h) && rest.length === 0
+    ? Result.succeed([w, h] as const)
+    : Result.fail(`aspectRatio "${ratio}" must read "W:H" with positive numbers.`)
+}
+
+/** Several image endpoints require both edges to be multiples of 16. */
+export const round16 = (n: number): number => Math.max(16, Math.round(n / 16) * 16)
+
 export type MediaUrl<M extends string = string> = {
   readonly _tag: "url"
   readonly url: string

package/src/domain/Music.ts

@@ -1,5 +1,6 @@
 import type { Duration } from "effect"
 import type { AudioBlob, AudioChunk, AudioFormat } from "./Audio.js"
+import type { Watermark } from "./Media.js"
 
 /**
  * Prompt fragment with a relative weight. Native to Lyria RealTime
@@ -95,10 +96,10 @@ export const controlInput = (action: MusicSessionControl): MusicSessionInput =>
 
 /**
  * Watermark kind on the response. SynthID is mandatory on Lyria; C2PA
- * is opt-in on ElevenLabs. No provider exposes additional metadata
- * about the watermark itself, so a bare literal-union is enough.
+ * is opt-in on ElevenLabs. Lives in `Media.ts` since image providers
+ * report the same kinds; re-exported here unchanged.
  */
-export type Watermark = "synthid" | "c2pa" | (string & {})
+export type { Watermark } from "./Media.js"
 
 /**
  * Labelled section with absolute timing. Populated when the provider

package/src/domain/Turn.ts

@@ -1,5 +1,6 @@
 import { Data, Effect, Result, Schema, Stream, pipe } from "effect"
 import * as StructuredFormat from "../structured-format/StructuredFormat.js"
+import type { ImageSource } from "./Image.js"
 import {
   type Annotation,
   HistoryItem,
@@ -9,6 +10,7 @@ import {
   ToolCall,
   ToolCallOutput,
   Usage,
+  isOutputImage,
   isOutputText,
   isReasoning,
   isRefusal,
@@ -49,6 +51,12 @@ export type Turn = typeof Turn.Type
  * `WebSearchCall`: lifecycle of a provider-executed web search within the
  * turn. Fires only when the turn grounds against search; absent otherwise.
  *
+ * `ImageOutput`: an image the model produced, whether it drew it as part
+ * of its turn or reached a hosted tool for it. `partialIndex` marks a
+ * preview frame from providers that stream them; the finished image
+ * arrives without one and is also on `TurnComplete.turn` as an
+ * `OutputImage` block.
+ *
  * `CitationAdded`: a citation attached to the answer, emitted incrementally
  * where the provider streams citations. Providers that bundle citations emit
  * none of these; their citations still arrive on `TurnComplete.turn`
@@ -66,6 +74,11 @@ export type TurnEvent = Data.TaggedEnum<{
     readonly query?: string
     readonly action?: "search" | "open_page" | "find_in_page"
   }
+  ImageOutput: {
+    readonly image: ImageSource
+    /** Set only on a preview frame, counting from 0. Absent means finished. */
+    readonly partialIndex?: number
+  }
   CitationAdded: { readonly annotation: Annotation }
   TurnComplete: { readonly turn: Turn }
 }>
@@ -109,6 +122,49 @@ export const assistantTexts = (turn: Turn): ReadonlyArray<string> =>
  */
 export const assistantText = (turn: Turn): string => assistantTexts(turn).join("")
 
+/**
+ * Every image the model produced this turn, in order. The counterpart to
+ * {@link assistantTexts}: each is an `ImageSource`, so it can be written
+ * to disk or passed straight back as an `input_image` on the next turn.
+ */
+export const assistantImages = (turn: Turn): ReadonlyArray<ImageSource> =>
+  assistantMessages(turn)
+    .flatMap((m) => m.content)
+    .filter(isOutputImage)
+    .map((b) => b.source)
+
+/**
+ * Rewrite assistant `output_image` blocks into a user message carrying
+ * the same pictures as `input_image`, so another provider can look at
+ * what this one drew.
+ *
+ * Only Gemini's wire has an assistant-role image part; every other
+ * adapter omits an `output_image` on replay and says so. Moving it to a
+ * user message is the conversion that makes it portable, and it is
+ * yours to make rather than the adapter's: "the assistant drew this" and
+ * "here is an image, look at it" are different claims, and silently
+ * swapping one for the other behind your back would be the wrong kind of
+ * helpful.
+ *
+ * Items with no images pass through untouched, and the new user message
+ * follows the assistant message it came from.
+ */
+export const imagesAsInput = (history: ReadonlyArray<HistoryItem>): ReadonlyArray<HistoryItem> =>
+  history.flatMap((item) => {
+    if (item.type !== "message" || item.role !== "assistant") return [item]
+    const images = item.content.filter(isOutputImage)
+    return images.length === 0
+      ? [item]
+      : [
+          item,
+          {
+            type: "message" as const,
+            role: "user" as const,
+            content: images.map((b) => ({ type: "input_image" as const, source: b.source })),
+          },
+        ]
+  })
+
 /**
  * Every citation annotation attached to the turn's assistant `output_text`
  * blocks, in order. The flat view of a grounded turn's sources, whether the