@effect-uai/core 0.13.0 → 0.15.0

package/dist/testing/MockMessenger.mjs

@@ -0,0 +1,76 @@
+import { CurrentConversation, MessageId, Messenger } from "../messenger/Messenger.mjs";
+import { splitForLimit, streamViaEdits } from "../messenger/MessengerAdapter.mjs";
+import { Array, Data, Effect, Layer, Option, Ref, Stream } from "effect";
+//#region src/testing/MockMessenger.ts
+const Call = Data.taggedEnum();
+const defaultLimits = {
+	maxText: 4096,
+	maxCaption: 1024
+};
+const bodyText = (msg) => msg.body._tag === "Text" ? Option.some(msg.body.text) : Option.none();
+const buildService = (script, record, cursor, minted) => {
+	const limits = script.limits ?? defaultLimits;
+	const nextFailure = Ref.getAndUpdate(cursor, (n) => n + 1).pipe(Effect.flatMap((i) => Option.match(Option.fromNullishOr((script.failures ?? [])[i]), {
+		onNone: () => Effect.void,
+		onSome: Effect.fail
+	})));
+	const mint = Ref.updateAndGet(minted, (n) => n + 1).pipe(Effect.map((n) => MessageId(`m${n}`)));
+	const post = (msg) => Effect.gen(function* () {
+		const conversation = yield* CurrentConversation;
+		yield* record(Call.Post({
+			conversation,
+			message: msg
+		}));
+		yield* nextFailure;
+		const chunks = Option.match(bodyText(msg), {
+			onNone: () => 1,
+			onSome: (t) => splitForLimit(t, limits.maxText).length
+		});
+		return yield* Effect.map(Effect.forEach(Array.range(1, chunks), () => mint), Array.lastNonEmpty);
+	});
+	const edit = (msg, next) => record(Call.Edit({
+		message: msg,
+		next
+	})).pipe(Effect.andThen(nextFailure));
+	return {
+		events: script.events ?? Stream.empty,
+		post,
+		edit,
+		react: (msg, emoji) => record(Call.React({
+			message: msg,
+			emoji
+		})),
+		typing: Effect.gen(function* () {
+			const conversation = yield* CurrentConversation;
+			yield* record(Call.TypingStart({ conversation }));
+			yield* Effect.addFinalizer(() => record(Call.TypingStop({ conversation })));
+		}),
+		stream: streamViaEdits({
+			post,
+			edit,
+			limits
+		}, script.streamOptions),
+		limits
+	};
+};
+const makeUnsafe = (script) => {
+	const calls = Ref.makeUnsafe([]);
+	return {
+		service: buildService(script, (call) => Ref.update(calls, Array.append(call)), Ref.makeUnsafe(0), Ref.makeUnsafe(0)),
+		recorder: Ref.get(calls).pipe(Effect.map((c) => ({ calls: c })))
+	};
+};
+/** Layer registering the mock against the `Messenger` tag, plus its recorder. */
+const layer = (script = {}) => {
+	const { service, recorder } = makeUnsafe(script);
+	return {
+		layer: Layer.succeed(Messenger, service),
+		recorder
+	};
+};
+/** Bare service value + recorder. Use with `Effect.provideService`. */
+const make = (script = {}) => makeUnsafe(script);
+//#endregion
+export { Call, layer, make };
+
+//# sourceMappingURL=MockMessenger.mjs.map

package/dist/testing/MockMessenger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockMessenger.mjs","names":["Arr"],"sources":["../../src/testing/MockMessenger.ts"],"sourcesContent":["import { Array as Arr, Data, Effect, Layer, Option, Ref, Stream } from \"effect\"\nimport {\n  type ConversationRef,\n  CurrentConversation,\n  type InboundEvent,\n  MessageId,\n  type MessageRef,\n  Messenger,\n  type MessengerLimits,\n  type MessengerService,\n  type Outbound,\n} from \"../messenger/Messenger.js\"\nimport {\n  type StreamViaEditsOptions,\n  splitForLimit,\n  streamViaEdits,\n} from \"../messenger/MessengerAdapter.js\"\nimport * as MessengerError from \"../messenger/MessengerError.js\"\n\n// ---------------------------------------------------------------------------\n// Call log\n// ---------------------------------------------------------------------------\n\n/**\n * One entry per outbound call. `Post` is logged once even when the text was\n * long enough to split, so a caller that rolled over on its own is\n * distinguishable from one that leaned on `post` to do it.\n */\nexport type Call = Data.TaggedEnum<{\n  Post: { readonly conversation: ConversationRef; readonly message: Outbound }\n  Edit: { readonly message: MessageRef; readonly next: Outbound }\n  React: { readonly message: MessageRef; readonly emoji: string }\n  TypingStart: { readonly conversation: ConversationRef }\n  TypingStop: { readonly conversation: ConversationRef }\n}>\n\nexport const Call = Data.taggedEnum<Call>()\n\nexport type MockMessengerRecorder = {\n  readonly calls: ReadonlyArray<Call>\n}\n\n// ---------------------------------------------------------------------------\n// Script\n// ---------------------------------------------------------------------------\n\nexport type MockMessengerScript = {\n  /** Inbound events to replay. Empty by default. */\n  readonly events?: Stream.Stream<InboundEvent, MessengerError.MessengerError>\n  readonly limits?: MessengerLimits\n  /**\n   * Failures handed back one per `post` / `edit` call, in order; `undefined`\n   * entries succeed, and everything past the end succeeds.\n   */\n  readonly failures?: ReadonlyArray<MessengerError.MessengerError | undefined>\n  /** Passed through to `streamViaEdits`, which backs `stream`. */\n  readonly streamOptions?: StreamViaEditsOptions\n}\n\nconst defaultLimits: MessengerLimits = { maxText: 4096, maxCaption: 1024 }\n\nconst bodyText = (msg: Outbound): Option.Option<string> =>\n  msg.body._tag === \"Text\" ? Option.some(msg.body.text) : Option.none()\n\n// ---------------------------------------------------------------------------\n// Service builder\n// ---------------------------------------------------------------------------\n\nconst buildService = (\n  script: MockMessengerScript,\n  record: (call: Call) => Effect.Effect<void>,\n  cursor: Ref.Ref<number>,\n  minted: Ref.Ref<number>,\n): MessengerService => {\n  const limits = script.limits ?? defaultLimits\n\n  const nextFailure = Ref.getAndUpdate(cursor, (n) => n + 1).pipe(\n    Effect.flatMap((i) =>\n      Option.match(Option.fromNullishOr((script.failures ?? [])[i]), {\n        onNone: () => Effect.void,\n        onSome: Effect.fail<MessengerError.MessengerError>,\n      }),\n    ),\n  )\n\n  const mint = Ref.updateAndGet(minted, (n) => n + 1).pipe(Effect.map((n) => MessageId(`m${n}`)))\n\n  const post: MessengerService[\"post\"] = (msg) =>\n    Effect.gen(function* () {\n      const conversation = yield* CurrentConversation\n      yield* record(Call.Post({ conversation, message: msg }))\n      yield* nextFailure\n      // One id per chunk, mirroring an adapter that splits at the ceiling.\n      const chunks = Option.match(bodyText(msg), {\n        onNone: () => 1,\n        onSome: (t) => splitForLimit(t, limits.maxText).length,\n      })\n      return yield* Effect.map(\n        Effect.forEach(Arr.range(1, chunks), () => mint),\n        Arr.lastNonEmpty,\n      )\n    })\n\n  const edit: MessengerService[\"edit\"] = (msg, next) =>\n    record(Call.Edit({ message: msg, next })).pipe(Effect.andThen(nextFailure))\n\n  return {\n    events: script.events ?? Stream.empty,\n    post,\n    edit,\n    react: (msg, emoji) => record(Call.React({ message: msg, emoji })),\n    typing: Effect.gen(function* () {\n      const conversation = yield* CurrentConversation\n      yield* record(Call.TypingStart({ conversation }))\n      yield* Effect.addFinalizer(() => record(Call.TypingStop({ conversation })))\n    }),\n    stream: streamViaEdits({ post, edit, limits }, script.streamOptions),\n    limits,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\nconst makeUnsafe = (script: MockMessengerScript) => {\n  const calls = Ref.makeUnsafe<ReadonlyArray<Call>>([])\n  const service = buildService(\n    script,\n    (call) => Ref.update(calls, Arr.append(call)),\n    Ref.makeUnsafe(0),\n    Ref.makeUnsafe(0),\n  )\n  return {\n    service,\n    recorder: Ref.get(calls).pipe(Effect.map((c): MockMessengerRecorder => ({ calls: c }))),\n  }\n}\n\n/** Layer registering the mock against the `Messenger` tag, plus its recorder. */\nexport const layer = (script: MockMessengerScript = {}) => {\n  const { service, recorder } = makeUnsafe(script)\n  return { layer: Layer.succeed(Messenger, service), recorder }\n}\n\n/** Bare service value + recorder. Use with `Effect.provideService`. */\nexport const make = (script: MockMessengerScript = {}) => makeUnsafe(script)\n"],"mappings":";;;;AAoCA,MAAa,OAAO,KAAK,WAAiB;AAuB1C,MAAM,gBAAiC;CAAE,SAAS;CAAM,YAAY;AAAK;AAEzE,MAAM,YAAY,QAChB,IAAI,KAAK,SAAS,SAAS,OAAO,KAAK,IAAI,KAAK,IAAI,IAAI,OAAO,KAAK;AAMtE,MAAM,gBACJ,QACA,QACA,QACA,WACqB;CACrB,MAAM,SAAS,OAAO,UAAU;CAEhC,MAAM,cAAc,IAAI,aAAa,SAAS,MAAM,IAAI,CAAC,CAAC,CAAC,KACzD,OAAO,SAAS,MACd,OAAO,MAAM,OAAO,eAAe,OAAO,YAAY,CAAC,EAAA,CAAG,EAAE,GAAG;EAC7D,cAAc,OAAO;EACrB,QAAQ,OAAO;CACjB,CAAC,CACH,CACF;CAEA,MAAM,OAAO,IAAI,aAAa,SAAS,MAAM,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,KAAK,MAAM,UAAU,IAAI,GAAG,CAAC,CAAC;CAE9F,MAAM,QAAkC,QACtC,OAAO,IAAI,aAAa;EACtB,MAAM,eAAe,OAAO;EAC5B,OAAO,OAAO,KAAK,KAAK;GAAE;GAAc,SAAS;EAAI,CAAC,CAAC;EACvD,OAAO;EAEP,MAAM,SAAS,OAAO,MAAM,SAAS,GAAG,GAAG;GACzC,cAAc;GACd,SAAS,MAAM,cAAc,GAAG,OAAO,OAAO,CAAC,CAAC;EAClD,CAAC;EACD,OAAO,OAAO,OAAO,IACnB,OAAO,QAAQA,MAAI,MAAM,GAAG,MAAM,SAAS,IAAI,GAC/CA,MAAI,YACN;CACF,CAAC;CAEH,MAAM,QAAkC,KAAK,SAC3C,OAAO,KAAK,KAAK;EAAE,SAAS;EAAK;CAAK,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,QAAQ,WAAW,CAAC;CAE5E,OAAO;EACL,QAAQ,OAAO,UAAU,OAAO;EAChC;EACA;EACA,QAAQ,KAAK,UAAU,OAAO,KAAK,MAAM;GAAE,SAAS;GAAK;EAAM,CAAC,CAAC;EACjE,QAAQ,OAAO,IAAI,aAAa;GAC9B,MAAM,eAAe,OAAO;GAC5B,OAAO,OAAO,KAAK,YAAY,EAAE,aAAa,CAAC,CAAC;GAChD,OAAO,OAAO,mBAAmB,OAAO,KAAK,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC;EAC5E,CAAC;EACD,QAAQ,eAAe;GAAE;GAAM;GAAM;EAAO,GAAG,OAAO,aAAa;EACnE;CACF;AACF;AAMA,MAAM,cAAc,WAAgC;CAClD,MAAM,QAAQ,IAAI,WAAgC,CAAC,CAAC;CAOpD,OAAO;EACL,SAPc,aACd,SACC,SAAS,IAAI,OAAO,OAAOA,MAAI,OAAO,IAAI,CAAC,GAC5C,IAAI,WAAW,CAAC,GAChB,IAAI,WAAW,CAAC,CAGV;EACN,UAAU,IAAI,IAAI,KAAK,CAAC,CAAC,KAAK,OAAO,KAAK,OAA8B,EAAE,OAAO,EAAE,EAAE,CAAC;CACxF;AACF;;AAGA,MAAa,SAAS,SAA8B,CAAC,MAAM;CACzD,MAAM,EAAE,SAAS,aAAa,WAAW,MAAM;CAC/C,OAAO;EAAE,OAAO,MAAM,QAAQ,WAAW,OAAO;EAAG;CAAS;AAC9D;;AAGA,MAAa,QAAQ,SAA8B,CAAC,MAAM,WAAW,MAAM"}

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/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.13.0",
+  "version": "0.15.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -106,10 +106,26 @@
       "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"
     },
+    "./Messenger": {
+      "types": "./dist/messenger/Messenger.d.mts",
+      "import": "./dist/messenger/Messenger.mjs"
+    },
+    "./MessengerAdapter": {
+      "types": "./dist/messenger/MessengerAdapter.d.mts",
+      "import": "./dist/messenger/MessengerAdapter.mjs"
+    },
+    "./MessengerError": {
+      "types": "./dist/messenger/MessengerError.d.mts",
+      "import": "./dist/messenger/MessengerError.mjs"
+    },
     "./MusicGenerator": {
       "types": "./dist/music-generator/MusicGenerator.d.mts",
       "import": "./dist/music-generator/MusicGenerator.mjs"
@@ -162,6 +178,10 @@
       "types": "./dist/web-search/WebSearchTool.d.mts",
       "import": "./dist/web-search/WebSearchTool.mjs"
     },
+    "./Inbox": {
+      "types": "./dist/inbox/Inbox.d.mts",
+      "import": "./dist/inbox/Inbox.mjs"
+    },
     "./Loop": {
       "types": "./dist/loop/Loop.d.mts",
       "import": "./dist/loop/Loop.mjs"
@@ -214,6 +234,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"
@@ -230,6 +254,10 @@
       "types": "./dist/testing/MockProvider.d.mts",
       "import": "./dist/testing/MockProvider.mjs"
     },
+    "./testing/MockMessenger": {
+      "types": "./dist/testing/MockMessenger.d.mts",
+      "import": "./dist/testing/MockMessenger.mjs"
+    },
     "./testing/MockMusicGenerator": {
       "types": "./dist/testing/MockMusicGenerator.d.mts",
       "import": "./dist/testing/MockMusicGenerator.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/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