@opencode/ai 2.0.14 → 2.0.15

package/dist/image.js

@@ -1,5 +1,8 @@
-import { Effect, Schema } from "effect";
-import { HttpOptions, InvalidRequestError, AIError, ModelID, ProviderID, ProviderMetadata, Usage, } from "./schema/index.js";
+import { Effect, Schema, Stream } from "effect";
+import { Media } from "./media.js";
+import { Endpoint } from "./route/endpoint.js";
+import { MediaRoute } from "./route/media.js";
+import { AIError, HttpOptions, InvalidRequestError, MediaUsage, ModelID, ProviderID, ProviderMetadata, } from "./schema/index.js";
 import { ImageClient, Service } from "./image-client.js";
 export class ImageModel {
     id;
@@ -20,84 +23,109 @@ export class ImageModel {
             http: input.http,
         });
     }
+    /** Compose an inline image protocol with its canonical path into a model for one deployment. */
+    static fromRoute(route, input) {
+        return ImageModel.make({
+            id: input.id,
+            provider: route.provider,
+            http: input.http,
+            route: MediaRoute.make({
+                id: route.id,
+                provider: route.provider,
+                protocol: route.protocol,
+                endpoint: Endpoint.path(route.path, { baseURL: input.baseURL ?? route.baseURL }),
+                auth: input.auth,
+                headers: input.headers,
+            }),
+        });
+    }
 }
 export const ImageModelSchema = Schema.declare((value) => value instanceof ImageModel, {
     expected: "Image.Model",
 });
-const ImageBytesInput = Schema.Struct({
-    type: Schema.Literal("bytes"),
-    data: Schema.Uint8Array,
-    mediaType: Schema.String,
-});
-const ImageUrlInput = Schema.Struct({
-    type: Schema.Literal("url"),
-    url: Schema.String,
-});
-const ImageFileIDInput = Schema.Struct({
-    type: Schema.Literal("file-id"),
-    id: Schema.String,
-});
-const ImageFileURIInput = Schema.Struct({
-    type: Schema.Literal("file-uri"),
-    uri: Schema.String,
-    mediaType: Schema.String,
-});
-export const ImageInputSchema = Schema.Union([
-    ImageBytesInput,
-    ImageUrlInput,
-    ImageFileIDInput,
-    ImageFileURIInput,
-]).pipe(Schema.toTaggedUnion("type"));
-export const ImageInput = {
-    bytes: (data, mediaType) => ({ type: "bytes", data, mediaType }),
-    url: (url) => ({ type: "url", url }),
-    file: (id) => ({ type: "file-id", id }),
-    fileUri: (uri, mediaType) => ({ type: "file-uri", uri, mediaType }),
-};
+export const ImageSize = Schema.declare((value) => typeof value === "string" && /^\d+x\d+$/.test(value), { title: "ImageSize" });
+export const ImageAspectRatio = Schema.declare((value) => typeof value === "string" && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(value), { title: "ImageAspectRatio" });
 export class ImageRequest extends Schema.Class("Image.Request")({
     model: ImageModelSchema,
     prompt: Schema.String,
-    images: Schema.optional(Schema.Array(ImageInputSchema)),
-    options: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+    /** Edit sources or style/subject references, in order. */
+    images: Schema.optional(Schema.Array(Media.AssetSchema)),
+    /** Inpainting mask; routes that cannot honor it fail with `UnsupportedOperation`. */
+    mask: Schema.optional(Media.AssetSchema),
+    n: Schema.optional(Schema.Int),
+    size: Schema.optional(ImageSize),
+    aspectRatio: Schema.optional(ImageAspectRatio),
+    seed: Schema.optional(Schema.Number),
+    format: Schema.optional(Schema.String),
+    providerOptions: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
     http: Schema.optional(HttpOptions),
 }) {
 }
-export class GeneratedImage extends Schema.Class("Image.Generated")({
-    mediaType: Schema.String,
-    data: Schema.Union([Schema.String, Schema.Uint8Array]),
-    providerMetadata: Schema.optional(ProviderMetadata),
-}) {
-}
+// ---------------------------------------------------------------------------
+// Response and events
+// ---------------------------------------------------------------------------
 export class ImageResponse extends Schema.Class("Image.Response")({
-    images: Schema.Array(GeneratedImage),
-    usage: Schema.optional(Usage),
+    images: Schema.Array(Media.AssetSchema),
+    usage: Schema.optional(MediaUsage),
+    notices: Schema.optional(Schema.Array(Media.Notice)),
     providerMetadata: Schema.optional(ProviderMetadata),
 }) {
     get image() {
         return this.images[0];
     }
 }
+export const ImageOutputEvent = Schema.Struct({
+    type: Schema.tag("image"),
+    index: Schema.Number,
+    image: Media.AssetSchema,
+}).annotate({ identifier: "Image.Event.Image" });
+export const ImageFinishEvent = Schema.Struct({
+    type: Schema.tag("finish"),
+    usage: Schema.optional(MediaUsage),
+    notices: Schema.optional(Schema.Array(Media.Notice)),
+    providerMetadata: Schema.optional(ProviderMetadata),
+}).annotate({ identifier: "Image.Event.Finish" });
+const imageEventTagged = Schema.Union([ImageOutputEvent, ImageFinishEvent]).pipe(Schema.toTaggedUnion("type"));
+export const ImageEvent = Object.assign(imageEventTagged, {
+    is: {
+        image: imageEventTagged.guards.image,
+        finish: imageEventTagged.guards.finish,
+    },
+});
+/** Inline routes produce every image at once; expand the response into the streaming event shape. */
+export const responseEvents = (response) => [
+    ...response.images.map((image, index) => ImageOutputEvent.make({ index, image })),
+    ImageFinishEvent.make({
+        usage: response.usage,
+        notices: response.notices,
+        providerMetadata: response.providerMetadata,
+    }),
+];
 export function request(input) {
     if (input instanceof ImageRequest)
         return input;
     return new ImageRequest({
         ...input,
-        model: input.model,
         http: input.http === undefined ? undefined : HttpOptions.make(input.http),
     });
 }
-export function generate(input) {
-    return Effect.try({
-        try: () => (input instanceof ImageRequest ? input : request(input)),
-        catch: (error) => new AIError({
-            reason: new InvalidRequestError({
-                message: error instanceof Error ? error.message : String(error),
-                cause: error,
-            }),
+const requestEffect = (input) => Effect.try({
+    try: () => request(input),
+    catch: (error) => new AIError({
+        reason: new InvalidRequestError({
+            message: error instanceof Error ? error.message : String(error),
+            cause: error,
         }),
-    }).pipe(Effect.flatMap((request) => ImageClient.generate(request)));
+    }),
+});
+export function generate(input) {
+    return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.generate(request)));
+}
+export function stream(input) {
+    return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => ImageClient.stream(request))));
 }
 export const Image = {
     request,
     generate,
+    stream,
 };

package/dist/index.d.ts

@@ -6,9 +6,12 @@ export { ProviderPackage } from "./provider-package.js";
 export { isContextOverflow, isContextOverflowFailure } from "./provider-error.js";
 export type { RouteLanguageModelInput, RouteRoutedLanguageModelInput, Interface as LLMClientShape, Service as LLMClientService, } from "./route/client.js";
 export * from "./schema/index.js";
-export { GeneratedImage, ImageInput, ImageInputSchema, ImageModel, ImageRequest, ImageResponse } from "./image.js";
-export type { ImageModelOptions, ImageOptions, ImageRequestFor, ImageRequestInput, ImageRoute } from "./image.js";
+export { ImageAspectRatio, ImageEvent, ImageModel, ImageModelSchema, ImageRequest, ImageResponse, ImageSize, } from "./image.js";
+export type { ImageFormat, ImageModelOptions, ImageOptions, ImageRequestFor, ImageRequestInput, ImageRoute, } from "./image.js";
 export { Image } from "./image.js";
+export { Media } from "./media.js";
+export { Generation } from "./generation.js";
+export type { Event as GenerationEvent, Poll, Route as GenerationRoute, Snapshot as GenerationSnapshot, Status as GenerationStatus } from "./generation.js";
 export { Tool, ToolFailure, toDefinitions } from "./tool.js";
 export { ToolRuntime } from "./tool-runtime.js";
 export type { DispatchResult as ToolDispatchResult, ToolSettlement } from "./tool-runtime.js";

package/dist/index.js

@@ -5,8 +5,10 @@ export { Provider } from "./provider.js";
 export { ProviderPackage } from "./provider-package.js";
 export { isContextOverflow, isContextOverflowFailure } from "./provider-error.js";
 export * from "./schema/index.js";
-export { GeneratedImage, ImageInput, ImageInputSchema, ImageModel, ImageRequest, ImageResponse } from "./image.js";
+export { ImageAspectRatio, ImageEvent, ImageModel, ImageModelSchema, ImageRequest, ImageResponse, ImageSize, } from "./image.js";
 export { Image } from "./image.js";
+export { Media } from "./media.js";
+export { Generation } from "./generation.js";
 export { Tool, ToolFailure, toDefinitions } from "./tool.js";
 export { ToolRuntime } from "./tool-runtime.js";
 export * as LLM from "./llm.js";

package/dist/llm.d.ts

@@ -191,6 +191,14 @@ export declare class GenerateObjectResponse<T> {
             };
         } | undefined;
         readonly namespace?: string | undefined;
+    } | {
+        readonly type: "media";
+        readonly media: import("./media.js").Asset;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
     } | {
         readonly type: "step-finish";
         readonly reason: {
@@ -219,12 +227,12 @@ export declare class GenerateObjectResponse<T> {
     } | {
         readonly type: "provider-error";
         readonly message: string;
+        readonly classification?: "context-overflow" | "payload-too-large" | undefined;
         readonly providerMetadata?: {
             readonly [x: string]: {
                 readonly [x: string]: unknown;
             };
         } | undefined;
-        readonly classification?: "context-overflow" | "payload-too-large" | undefined;
     })[];
     get usage(): import("./schema/events.js").Usage | undefined;
 }

package/dist/media.d.ts

@@ -0,0 +1,212 @@
+export * as Media from "./media.js";
+import { Effect, FileSystem, Schema } from "effect";
+import { ProviderID } from "./schema/ids.js";
+import { AIError } from "./schema/errors.js";
+import { ProviderMetadata } from "./schema/options.js";
+import { Service } from "./route/executor-service.js";
+export { detectMediaType } from "./utils/media-type.js";
+export declare const Source: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"bytes">;
+    readonly data: Schema.Uint8Array;
+    readonly mediaType: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"base64">;
+    readonly data: Schema.String;
+    readonly mediaType: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"url">;
+    readonly url: Schema.String;
+    readonly mediaType: Schema.optional<Schema.String>;
+    /** Epoch milliseconds after which the provider no longer serves the URL. */
+    readonly expiresAt: Schema.optional<Schema.Number>;
+    /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
+    readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"ref">;
+    readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
+    readonly id: Schema.String;
+    readonly mediaType: Schema.optional<Schema.String>;
+}>]>;
+export type Source = Schema.Schema.Type<typeof Source>;
+export declare const Kind: Schema.Literals<readonly ["image", "video", "audio", "document", "other"]>;
+export type Kind = Schema.Schema.Type<typeof Kind>;
+export declare const kindOf: (mediaType: string) => Kind;
+/** Container-independent facts about the payload; raw PCM audio relies on these because it has no header. */
+export declare const Info: Schema.Struct<{
+    readonly width: Schema.optional<Schema.Number>;
+    readonly height: Schema.optional<Schema.Number>;
+    readonly durationSeconds: Schema.optional<Schema.Number>;
+    readonly sampleRate: Schema.optional<Schema.Number>;
+    readonly channels: Schema.optional<Schema.Number>;
+    readonly encoding: Schema.optional<Schema.String>;
+    readonly format: Schema.optional<Schema.String>;
+}>;
+export type Info = Schema.Schema.Type<typeof Info>;
+/** A provider-side partial result such as stripped audio or a moderated sample; never a silent drop. */
+export declare const Notice: Schema.Struct<{
+    readonly type: Schema.Literals<readonly ["moderated", "filtered", "other"]>;
+    readonly message: Schema.String;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+}>;
+export type Notice = Schema.Schema.Type<typeof Notice>;
+/** Synchronous view of an inline payload; `undefined` for `url` and `ref` sources, which carry no local bytes. */
+export interface Inline {
+    readonly mime: string;
+    readonly base64: string;
+    readonly dataUrl: string;
+}
+export declare class Asset {
+    #private;
+    readonly source: Source;
+    /** Derived from the source: declared type, sniffed magic bytes, then `application/octet-stream`. */
+    readonly mediaType: string;
+    readonly kind: Kind;
+    readonly info?: Info;
+    /** Epoch milliseconds after which a `url` source stops resolving. */
+    readonly expiresAt?: number;
+    readonly providerMetadata?: ProviderMetadata;
+    constructor(input: Asset.Input);
+    /** Inline payload without effects, for protocols that embed base64 or data URLs directly. */
+    inline(): Inline | undefined;
+    /** Decoded payload; downloads `url` sources through the request executor and caches the result. */
+    bytes(): Effect.Effect<Uint8Array, AIError, Service>;
+    base64(): Effect.Effect<string, AIError, Service>;
+    dataUrl(): Effect.Effect<string, AIError, Service>;
+    /**
+     * The `AssetEncoded` JSON form with `bytes` sources as base64, matching `Schema.toCodecJson(AssetSchema)`, so a
+     * plain `JSON.stringify` of messages or events stays lossless and decodes back through the JSON codec.
+     */
+    toJSON(): {
+        source: {
+            readonly type: "base64";
+            readonly data: string;
+            readonly mediaType: string;
+        } | {
+            readonly type: "url";
+            readonly url: string;
+            readonly headers?: {
+                readonly [x: string]: string;
+            } | undefined;
+            readonly mediaType?: string | undefined;
+            readonly expiresAt?: number | undefined;
+        } | {
+            readonly id: string;
+            readonly type: "ref";
+            readonly provider: string & import("effect/Brand").Brand<"AI.ProviderID">;
+            readonly mediaType?: string | undefined;
+        } | {
+            data: string;
+            type: "bytes";
+            mediaType: string;
+        };
+        info: {
+            readonly format?: string | undefined;
+            readonly width?: number | undefined;
+            readonly height?: number | undefined;
+            readonly durationSeconds?: number | undefined;
+            readonly sampleRate?: number | undefined;
+            readonly channels?: number | undefined;
+            readonly encoding?: string | undefined;
+        } | undefined;
+        providerMetadata: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    };
+    /** Pull `url` sources into owned bytes before the URL expires. Inline sources return themselves. */
+    materialize(): Effect.Effect<Asset, AIError, Service>;
+}
+export declare namespace Asset {
+    interface Input {
+        readonly source: Source;
+        readonly info?: Info;
+        readonly providerMetadata?: ProviderMetadata;
+    }
+}
+/** JSON form of an asset: the serializable `Source` plus caller-supplied metadata. `bytes` sources encode as base64. */
+export declare const AssetEncoded: Schema.Struct<{
+    readonly source: Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"bytes">;
+        readonly data: Schema.Uint8Array;
+        readonly mediaType: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"base64">;
+        readonly data: Schema.String;
+        readonly mediaType: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"url">;
+        readonly url: Schema.String;
+        readonly mediaType: Schema.optional<Schema.String>;
+        /** Epoch milliseconds after which the provider no longer serves the URL. */
+        readonly expiresAt: Schema.optional<Schema.Number>;
+        /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
+        readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"ref">;
+        readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
+        readonly id: Schema.String;
+        readonly mediaType: Schema.optional<Schema.String>;
+    }>]>;
+    readonly info: Schema.optional<Schema.Struct<{
+        readonly width: Schema.optional<Schema.Number>;
+        readonly height: Schema.optional<Schema.Number>;
+        readonly durationSeconds: Schema.optional<Schema.Number>;
+        readonly sampleRate: Schema.optional<Schema.Number>;
+        readonly channels: Schema.optional<Schema.Number>;
+        readonly encoding: Schema.optional<Schema.String>;
+        readonly format: Schema.optional<Schema.String>;
+    }>>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+}>;
+/** `Asset` in the type domain and `AssetEncoded` on the wire, so messages and events holding assets serialize. */
+export declare const AssetSchema: Schema.decodeTo<Schema.declare<Asset, Asset>, Schema.Struct<{
+    readonly source: Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"bytes">;
+        readonly data: Schema.Uint8Array;
+        readonly mediaType: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"base64">;
+        readonly data: Schema.String;
+        readonly mediaType: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"url">;
+        readonly url: Schema.String;
+        readonly mediaType: Schema.optional<Schema.String>;
+        /** Epoch milliseconds after which the provider no longer serves the URL. */
+        readonly expiresAt: Schema.optional<Schema.Number>;
+        /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
+        readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"ref">;
+        readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
+        readonly id: Schema.String;
+        readonly mediaType: Schema.optional<Schema.String>;
+    }>]>;
+    readonly info: Schema.optional<Schema.Struct<{
+        readonly width: Schema.optional<Schema.Number>;
+        readonly height: Schema.optional<Schema.Number>;
+        readonly durationSeconds: Schema.optional<Schema.Number>;
+        readonly sampleRate: Schema.optional<Schema.Number>;
+        readonly channels: Schema.optional<Schema.Number>;
+        readonly encoding: Schema.optional<Schema.String>;
+        readonly format: Schema.optional<Schema.String>;
+    }>>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+}>, never, never>;
+export type AssetOptions = Omit<Asset.Input, "source">;
+export declare const from: (source: Source, options?: AssetOptions) => Asset;
+export declare const bytes: (data: Uint8Array, mediaType?: string, options?: AssetOptions) => Asset;
+export declare const base64: (data: string, mediaType: string, options?: AssetOptions) => Asset;
+export declare const url: (value: string, options?: AssetOptions & Omit<Extract<Source, {
+    readonly type: "url";
+}>, "type" | "url">) => Asset;
+export declare const ref: (provider: string | ProviderID, id: string, mediaType?: string, options?: AssetOptions) => Asset;
+/** Parse a `data:<mime>;base64,<data>` URL, or `undefined` when the value is not a base64 data URL. */
+export declare const parseDataUrl: (value: string, options?: AssetOptions) => Asset | undefined;
+/** Parse a `data:<mime>;base64,<data>` URL. Malformed input throws a typed `AIError` because constructors are sync. */
+export declare const fromDataUrl: (dataUrl: string, options?: AssetOptions) => Asset;
+/** Read a file through `FileSystem` and sniff its media type from magic bytes, then the extension. */
+export declare const file: (path: string, options?: AssetOptions) => Effect.Effect<Asset, AIError, FileSystem.FileSystem>;
+/** Materialize an asset and write its bytes through `FileSystem`. */
+export declare const write: (asset: Asset, path: string) => Effect.Effect<void, AIError, FileSystem.FileSystem | Service>;

package/dist/media.js

@@ -0,0 +1,228 @@
+export * as Media from "./media.js";
+import { Effect, Encoding, FileSystem, Schema, SchemaGetter } from "effect";
+import { HttpClientRequest } from "effect/unstable/http";
+import { ProviderID } from "./schema/ids.js";
+import { AIError, HttpContext, InvalidProviderOutputError, InvalidRequestError } from "./schema/errors.js";
+import { ProviderMetadata } from "./schema/options.js";
+import { Service } from "./route/executor-service.js";
+import { detectMediaType, extensionMediaType } from "./utils/media-type.js";
+export { detectMediaType } from "./utils/media-type.js";
+const OCTET_STREAM = "application/octet-stream";
+// ---------------------------------------------------------------------------
+// Source — the serializable wire/persistence form of a media asset
+// ---------------------------------------------------------------------------
+const BytesSource = Schema.Struct({
+    type: Schema.Literal("bytes"),
+    data: Schema.Uint8Array,
+    mediaType: Schema.String,
+});
+const Base64Source = Schema.Struct({
+    type: Schema.Literal("base64"),
+    data: Schema.String,
+    mediaType: Schema.String,
+});
+const UrlSource = Schema.Struct({
+    type: Schema.Literal("url"),
+    url: Schema.String,
+    mediaType: Schema.optional(Schema.String),
+    /** Epoch milliseconds after which the provider no longer serves the URL. */
+    expiresAt: Schema.optional(Schema.Number),
+    /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
+    headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+});
+/** A provider-side handle: OpenAI `file_id`, Gemini file URI, `gs://`, `runway://`, or a prior generation id. */
+const RefSource = Schema.Struct({
+    type: Schema.Literal("ref"),
+    provider: ProviderID,
+    id: Schema.String,
+    mediaType: Schema.optional(Schema.String),
+});
+export const Source = Schema.Union([BytesSource, Base64Source, UrlSource, RefSource])
+    .pipe(Schema.toTaggedUnion("type"))
+    .annotate({ identifier: "Media.Source" });
+// ---------------------------------------------------------------------------
+// Kind, Info, Notice
+// ---------------------------------------------------------------------------
+export const Kind = Schema.Literals(["image", "video", "audio", "document", "other"]);
+export const kindOf = (mediaType) => {
+    const lower = mediaType.toLowerCase();
+    if (lower.startsWith("image/"))
+        return "image";
+    if (lower.startsWith("video/"))
+        return "video";
+    if (lower.startsWith("audio/"))
+        return "audio";
+    if (lower === "application/pdf" || lower.startsWith("text/"))
+        return "document";
+    return "other";
+};
+/** Container-independent facts about the payload; raw PCM audio relies on these because it has no header. */
+export const Info = Schema.Struct({
+    width: Schema.optional(Schema.Number),
+    height: Schema.optional(Schema.Number),
+    durationSeconds: Schema.optional(Schema.Number),
+    sampleRate: Schema.optional(Schema.Number),
+    channels: Schema.optional(Schema.Number),
+    encoding: Schema.optional(Schema.String),
+    format: Schema.optional(Schema.String),
+}).annotate({ identifier: "Media.Info" });
+/** A provider-side partial result such as stripped audio or a moderated sample; never a silent drop. */
+export const Notice = Schema.Struct({
+    type: Schema.Literals(["moderated", "filtered", "other"]),
+    message: Schema.String,
+    providerMetadata: Schema.optional(ProviderMetadata),
+}).annotate({ identifier: "Media.Notice" });
+// ---------------------------------------------------------------------------
+// Asset
+// ---------------------------------------------------------------------------
+const invalid = (message, cause) => new AIError({ reason: new InvalidRequestError({ message, cause }) });
+export class Asset {
+    source;
+    /** Derived from the source: declared type, sniffed magic bytes, then `application/octet-stream`. */
+    mediaType;
+    kind;
+    info;
+    /** Epoch milliseconds after which a `url` source stops resolving. */
+    expiresAt;
+    providerMetadata;
+    // Derived payload forms are cached on the instance because every protocol lowering re-reads the same payload. The
+    // cache is check-then-set (concurrent first reads of a `url` source may both download) and is never observable
+    // through `source`, so round-tripping through `Media.from(asset.source)` stays lossless.
+    #bytes;
+    #base64;
+    constructor(input) {
+        this.source = input.source;
+        this.mediaType =
+            input.source.mediaType ??
+                (input.source.type === "bytes" ? detectMediaType(input.source.data) : undefined) ??
+                OCTET_STREAM;
+        this.kind = kindOf(this.mediaType);
+        this.info = input.info;
+        this.expiresAt = input.source.type === "url" ? input.source.expiresAt : undefined;
+        this.providerMetadata = input.providerMetadata;
+    }
+    /** Inline payload without effects, for protocols that embed base64 or data URLs directly. */
+    inline() {
+        const source = this.source;
+        if (source.type !== "bytes" && source.type !== "base64")
+            return undefined;
+        const base64 = source.type === "base64" ? source.data : (this.#base64 ??= Encoding.encodeBase64(source.data));
+        const mime = this.mediaType.toLowerCase();
+        return { mime, base64, dataUrl: `data:${mime};base64,${base64}` };
+    }
+    /** Decoded payload; downloads `url` sources through the request executor and caches the result. */
+    bytes() {
+        return Effect.suspend(() => {
+            const source = this.source;
+            if (source.type === "bytes")
+                return Effect.succeed(source.data);
+            if (this.#bytes !== undefined)
+                return Effect.succeed(this.#bytes);
+            if (source.type === "ref")
+                return Effect.fail(invalid(`Cannot materialize provider ref ${source.provider}:${source.id}`));
+            const decoded = source.type === "base64"
+                ? Effect.fromResult(Encoding.decodeBase64(source.data)).pipe(Effect.mapError((cause) => invalid(`Media asset contains invalid base64 data`, cause)))
+                : download(source);
+            return decoded.pipe(Effect.tap((data) => Effect.sync(() => (this.#bytes = data))));
+        });
+    }
+    base64() {
+        return Effect.suspend(() => {
+            const source = this.source;
+            if (source.type === "base64")
+                return Effect.succeed(source.data);
+            if (this.#base64 !== undefined)
+                return Effect.succeed(this.#base64);
+            return this.bytes().pipe(Effect.map((data) => (this.#base64 = Encoding.encodeBase64(data))));
+        });
+    }
+    dataUrl() {
+        return this.base64().pipe(Effect.map((data) => `data:${this.mediaType};base64,${data}`));
+    }
+    /**
+     * The `AssetEncoded` JSON form with `bytes` sources as base64, matching `Schema.toCodecJson(AssetSchema)`, so a
+     * plain `JSON.stringify` of messages or events stays lossless and decodes back through the JSON codec.
+     */
+    toJSON() {
+        const source = this.source;
+        return {
+            source: source.type === "bytes" ? { ...source, data: Encoding.encodeBase64(source.data) } : source,
+            info: this.info,
+            providerMetadata: this.providerMetadata,
+        };
+    }
+    /** Pull `url` sources into owned bytes before the URL expires. Inline sources return themselves. */
+    materialize() {
+        if (this.source.type === "bytes" || this.source.type === "base64")
+            return Effect.succeed(this);
+        return this.bytes().pipe(Effect.map((data) => bytes(data, this.source.mediaType, { info: this.info, providerMetadata: this.providerMetadata })));
+    }
+}
+/** JSON form of an asset: the serializable `Source` plus caller-supplied metadata. `bytes` sources encode as base64. */
+export const AssetEncoded = Schema.Struct({
+    source: Source,
+    info: Schema.optional(Info),
+    providerMetadata: Schema.optional(ProviderMetadata),
+}).annotate({ identifier: "Media.AssetEncoded" });
+const encodeAsset = (asset) => ({
+    source: asset.source,
+    info: asset.info,
+    providerMetadata: asset.providerMetadata,
+});
+const AssetInstance = Schema.declare((value) => value instanceof Asset, {
+    expected: "Media.Asset",
+});
+/** `Asset` in the type domain and `AssetEncoded` on the wire, so messages and events holding assets serialize. */
+export const AssetSchema = AssetEncoded.pipe(Schema.decodeTo(AssetInstance, {
+    decode: SchemaGetter.transform((encoded) => new Asset(encoded)),
+    encode: SchemaGetter.transform(encodeAsset),
+}));
+const download = Effect.fn("Media.download")(function* (source) {
+    const executor = yield* Service;
+    const response = yield* executor.execute(HttpClientRequest.get(source.url).pipe(HttpClientRequest.setHeaders(source.headers ?? {})));
+    const buffer = yield* response.arrayBuffer.pipe(Effect.mapError((cause) => new AIError({
+        reason: new InvalidProviderOutputError({
+            message: `Failed to read media from ${source.url}`,
+            http: new HttpContext({ url: response.request.url, status: response.status, headers: response.headers }),
+            cause,
+        }),
+    })));
+    return new Uint8Array(buffer);
+});
+export const from = (source, options) => new Asset({ ...options, source });
+export const bytes = (data, mediaType, options) => from({ type: "bytes", data, mediaType: mediaType ?? detectMediaType(data) ?? OCTET_STREAM }, options);
+export const base64 = (data, mediaType, options) => from({ type: "base64", data, mediaType }, options);
+export const url = (value, options) => {
+    const { mediaType, expiresAt, headers, ...rest } = options ?? {};
+    return from({ type: "url", url: value, mediaType, expiresAt, headers }, rest);
+};
+export const ref = (provider, id, mediaType, options) => from({ type: "ref", provider: ProviderID.make(provider), id, mediaType }, options);
+const DATA_URL = /^data:([^;,]+)(?:;[^,]*)*;base64,(.*)$/s;
+/** Parse a `data:<mime>;base64,<data>` URL, or `undefined` when the value is not a base64 data URL. */
+export const parseDataUrl = (value, options) => {
+    const match = DATA_URL.exec(value);
+    return match === null ? undefined : base64(match[2], match[1], options);
+};
+/** Parse a `data:<mime>;base64,<data>` URL. Malformed input throws a typed `AIError` because constructors are sync. */
+export const fromDataUrl = (dataUrl, options) => {
+    const asset = parseDataUrl(dataUrl, options);
+    if (asset === undefined)
+        throw invalid("Media data URLs must contain a MIME type and base64 data");
+    return asset;
+};
+/** Read a file through `FileSystem` and sniff its media type from magic bytes, then the extension. */
+export const file = (path, options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const data = yield* fs
+        .readFile(path)
+        .pipe(Effect.mapError((cause) => invalid(`Failed to read media file ${path}`, cause)));
+    return bytes(data, detectMediaType(data) ?? extensionMediaType(path), options);
+});
+/** Materialize an asset and write its bytes through `FileSystem`. */
+export const write = (asset, path) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const data = yield* asset.bytes();
+    yield* fs
+        .writeFile(path, data)
+        .pipe(Effect.mapError((cause) => invalid(`Failed to write media file ${path}`, cause)));
+});