@opencode/ai 2.0.15 → 2.0.17

package/dist/image.js

@@ -1,42 +1,17 @@
 import { Effect, Schema, Stream } from "effect";
+import { Generation, ProgressEvent, QueuedEvent } from "./generation.js";
 import { Media } from "./media.js";
-import { Endpoint } from "./route/endpoint.js";
+import { MediaModel, composeRoute, tryRequest } from "./media-model.js";
 import { MediaRoute } from "./route/media.js";
-import { AIError, HttpOptions, InvalidRequestError, MediaUsage, ModelID, ProviderID, ProviderMetadata, } from "./schema/index.js";
+import { AIError, HttpOptions, MediaUsage, ProviderMetadata } from "./schema/index.js";
 import { ImageClient, Service } from "./image-client.js";
-export class ImageModel {
-    id;
-    provider;
-    route;
-    http;
-    constructor(input) {
-        this.id = input.id;
-        this.provider = input.provider;
-        this.route = input.route;
-        this.http = input.http;
-    }
-    static make(input) {
-        return new ImageModel({
-            id: ModelID.make(input.id),
-            provider: ProviderID.make(input.provider),
-            route: input.route,
-            http: input.http,
-        });
-    }
-    /** Compose an inline image protocol with its canonical path into a model for one deployment. */
+export class ImageModel extends MediaModel {
     static fromRoute(route, input) {
-        return ImageModel.make({
+        return new ImageModel({
             id: input.id,
-            provider: route.provider,
+            provider: route.protocol.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,
-            }),
+            route: composeRoute(route, input, collectResponse),
         });
     }
 }
@@ -44,7 +19,7 @@ export const ImageModelSchema = Schema.declare((value) => value instanceof Image
     expected: "Image.Model",
 });
 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 const ImageAspectRatio = Media.AspectRatio;
 export class ImageRequest extends Schema.Class("Image.Request")({
     model: ImageModelSchema,
     prompt: Schema.String,
@@ -74,6 +49,12 @@ export class ImageResponse extends Schema.Class("Image.Response")({
         return this.images[0];
     }
 }
+/** The `index`-th lower-fidelity preview of an image still generating; the `image` event supersedes it. */
+export const ImagePartialEvent = Schema.Struct({
+    type: Schema.tag("image-partial"),
+    index: Schema.Number,
+    image: Media.AssetSchema,
+}).annotate({ identifier: "Image.Event.Partial" });
 export const ImageOutputEvent = Schema.Struct({
     type: Schema.tag("image"),
     index: Schema.Number,
@@ -85,47 +66,57 @@ export const ImageFinishEvent = Schema.Struct({
     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"));
+const imageEventTagged = Schema.Union([
+    QueuedEvent,
+    ProgressEvent,
+    ImagePartialEvent,
+    ImageOutputEvent,
+    ImageFinishEvent,
+]).pipe(Schema.toTaggedUnion("type"));
 export const ImageEvent = Object.assign(imageEventTagged, {
     is: {
+        generationQueued: imageEventTagged.guards["generation-queued"],
+        generationProgress: imageEventTagged.guards["generation-progress"],
+        imagePartial: imageEventTagged.guards["image-partial"],
         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,
-    }),
-];
+const collectResponse = (events) => {
+    const finish = events.find(ImageEvent.is.finish);
+    // Every image protocol's `finish` emits the terminal event or fails, so a completed stream always has one.
+    if (finish === undefined)
+        return Effect.die(new Error("The image stream completed without a finish event"));
+    return Effect.succeed(new ImageResponse({
+        images: events.filter(ImageEvent.is.image).map((event) => event.image),
+        usage: finish.usage,
+        notices: finish.notices,
+        providerMetadata: finish.providerMetadata,
+    }));
+};
 export function request(input) {
     if (input instanceof ImageRequest)
         return input;
     return new ImageRequest({
         ...input,
-        http: input.http === undefined ? undefined : HttpOptions.make(input.http),
+        http: HttpOptions.make(input.http),
     });
 }
-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,
-        }),
-    }),
-});
-export function generate(input) {
-    return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.generate(request)));
+const requestEffect = (input) => tryRequest(() => request(input));
+export function generate(input, options) {
+    return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.generate(request, options)));
+}
+export function stream(input, options) {
+    return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => ImageClient.stream(request, options))));
 }
-export function stream(input) {
-    return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => ImageClient.stream(request))));
+export function start(input) {
+    return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.start(request)));
 }
+export const resume = (model, token) => ImageClient.resume(model, token);
 export const Image = {
     request,
     generate,
     stream,
+    start,
+    resume,
 };

package/dist/index.d.ts

@@ -1,17 +1,30 @@
+export { AIClient } from "./ai-client.js";
 export { LLMClient } from "./route/client.js";
 export { ImageClient } from "./image-client.js";
 export { Auth } from "./route/auth.js";
 export { Provider } from "./provider.js";
 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 type { RouteLanguageModelInput, RouteRoutedLanguageModelInput, Interface as LLMClientShape, LLMClientService, } from "./route/client.js";
 export * from "./schema/index.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 { VideoClient } from "./video-client.js";
+export { VideoAspectRatio, VideoEvent, VideoFrames, VideoModel, VideoModelSchema, VideoRequest, VideoResponse, } from "./video.js";
+export type { VideoModelOptions, VideoOptions, VideoRequestFor, VideoRequestInput, VideoResolution, VideoRoute, } from "./video.js";
+export { Video } from "./video.js";
+export { SpeechClient } from "./speech-client.js";
+export { SpeechEvent, SpeechModel, SpeechModelSchema, SpeechRequest, SpeechResponse, SpeechTimestamp, SpeechVoice, } from "./speech.js";
+export type { SpeechFormat, SpeechModelOptions, SpeechOptions, SpeechRequestFor, SpeechRequestInput, SpeechRoute, } from "./speech.js";
+export { Speech } from "./speech.js";
+export { TranscriptionClient } from "./transcription-client.js";
+export { TranscriptionEvent, TranscriptionModel, TranscriptionModelSchema, TranscriptionRequest, TranscriptionResponse, TranscriptionSegment, TranscriptionTimestamps, TranscriptionWord, } from "./transcription.js";
+export type { TranscriptionModelOptions, TranscriptionOptions, TranscriptionRequestFor, TranscriptionRequestInput, TranscriptionRoute, } from "./transcription.js";
+export { Transcription } from "./transcription.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 type { AwaitOptions as GenerationAwaitOptions, 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

@@ -1,3 +1,4 @@
+export { AIClient } from "./ai-client.js";
 export { LLMClient } from "./route/client.js";
 export { ImageClient } from "./image-client.js";
 export { Auth } from "./route/auth.js";
@@ -7,6 +8,15 @@ export { isContextOverflow, isContextOverflowFailure } from "./provider-error.js
 export * from "./schema/index.js";
 export { ImageAspectRatio, ImageEvent, ImageModel, ImageModelSchema, ImageRequest, ImageResponse, ImageSize, } from "./image.js";
 export { Image } from "./image.js";
+export { VideoClient } from "./video-client.js";
+export { VideoAspectRatio, VideoEvent, VideoFrames, VideoModel, VideoModelSchema, VideoRequest, VideoResponse, } from "./video.js";
+export { Video } from "./video.js";
+export { SpeechClient } from "./speech-client.js";
+export { SpeechEvent, SpeechModel, SpeechModelSchema, SpeechRequest, SpeechResponse, SpeechTimestamp, SpeechVoice, } from "./speech.js";
+export { Speech } from "./speech.js";
+export { TranscriptionClient } from "./transcription-client.js";
+export { TranscriptionEvent, TranscriptionModel, TranscriptionModelSchema, TranscriptionRequest, TranscriptionResponse, TranscriptionSegment, TranscriptionTimestamps, TranscriptionWord, } from "./transcription.js";
+export { Transcription } from "./transcription.js";
 export { Media } from "./media.js";
 export { Generation } from "./generation.js";
 export { Tool, ToolFailure, toDefinitions } from "./tool.js";

package/dist/llm.d.ts

@@ -1,6 +1,6 @@
-import { Effect, JsonSchema, Schema } from "effect";
-import { Service } from "./route/client.js";
-import { GenerationOptions, HttpOptions, AIError, LLMRequest, LLMResponse, Message, LanguageModel, SystemPart, ToolChoice, type ContentPart, type LanguageModelProviderOptions, type ToolEntryInput } from "./schema/index.js";
+import { Effect, JsonSchema, Schema, Stream } from "effect";
+import { Service, type StreamOptions } from "./route/client.js";
+import { GenerationOptions, HttpOptions, AIError, LLMEvent, LLMRequest, LLMResponse, Message, LanguageModel, SystemPart, ToolChoice, type ContentPart, type LanguageModelProviderOptions, type ToolEntryInput } from "./schema/index.js";
 import { type ToolSchema } from "./tool.js";
 /** Input accepted by `LLM.request`, normalized into the canonical `LLMRequest` class. */
 export type RequestInput<SelectedLanguageModel extends LanguageModel = LanguageModel> = Omit<ConstructorParameters<typeof LLMRequest>[0], "model" | "system" | "messages" | "tools" | "toolChoice" | "generation" | "http" | "providerOptions"> & {
@@ -14,8 +14,10 @@ export type RequestInput<SelectedLanguageModel extends LanguageModel = LanguageM
     readonly providerOptions?: NoInfer<LanguageModelProviderOptions<SelectedLanguageModel>>;
     readonly http?: HttpOptions.Input;
 };
-export declare const generate: typeof import("./route/client.js").generate;
-export declare const stream: typeof import("./route/client.js").stream;
+export declare function generate<const Model extends LanguageModel>(input: RequestInput<Model>, options?: StreamOptions): Effect.Effect<LLMResponse, AIError, Service>;
+export declare function generate(input: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, AIError, Service>;
+export declare function stream<const Model extends LanguageModel>(input: RequestInput<Model>, options?: StreamOptions): Stream.Stream<LLMEvent, AIError, Service>;
+export declare function stream(input: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, AIError, Service>;
 export declare const request: <const SelectedLanguageModel extends LanguageModel>(input: RequestInput<SelectedLanguageModel>) => LLMRequest<SelectedLanguageModel>;
 type GenerateObjectBase<SelectedLanguageModel extends LanguageModel = LanguageModel> = Omit<RequestInput<SelectedLanguageModel>, "tools" | "toolChoice">;
 export declare class GenerateObjectResponse<T> {

package/dist/llm.js

@@ -1,9 +1,15 @@
-import { Effect, JsonSchema, Schema } from "effect";
+import { Effect, JsonSchema, Schema, Stream } from "effect";
+import { tryRequest } from "./media-model.js";
 import { LLMClient, Service } from "./route/client.js";
 import { GenerationOptions, HttpOptions, InvalidProviderOutputError, AIError, LLMEvent, LLMRequest, LLMResponse, Message, LanguageModel, SystemPart, ToolChoice, ToolEntry, } from "./schema/index.js";
 import { make as makeTool, toDefinitions } from "./tool.js";
-export const generate = LLMClient.generate;
-export const stream = LLMClient.stream;
+export function generate(input, options) {
+    return requestEffect(input).pipe(Effect.flatMap((request) => LLMClient.generate(request, options)));
+}
+export function stream(input, options) {
+    return Stream.unwrap(requestEffect(input).pipe(Effect.map((request) => LLMClient.stream(request, options))));
+}
+const requestEffect = (input) => input instanceof LLMRequest ? Effect.succeed(input) : tryRequest(() => request(input));
 export const request = (input) => {
     const { system: requestSystem, prompt, messages, tools, toolChoice: requestToolChoice, generation: requestGeneration, providerOptions: requestProviderOptions, http: requestHttp, ...rest } = input;
     return new LLMRequest({
@@ -14,7 +20,7 @@ export const request = (input) => {
         toolChoice: requestToolChoice ? ToolChoice.make(requestToolChoice) : undefined,
         generation: requestGeneration === undefined ? undefined : GenerationOptions.make(requestGeneration),
         providerOptions: requestProviderOptions,
-        http: requestHttp === undefined ? undefined : HttpOptions.make(requestHttp),
+        http: HttpOptions.make(requestHttp),
     });
 };
 const GENERATE_OBJECT_TOOL_NAME = "generate_object";

package/dist/media-client.d.ts

@@ -0,0 +1,30 @@
+import { type Context, Effect, Layer, Stream } from "effect";
+import { type AwaitOptions, type Generation, type Observation } from "./generation.js";
+import type { MediaRoute } from "./route/media.js";
+import { AIError } from "./schema/index.js";
+/** A media request whose model carries the route that executes it. */
+export interface RoutedRequest<Self extends MediaRoute.MediaRequest, Event, Response> extends MediaRoute.MediaRequest {
+    readonly model: MediaRoute.MediaRequest["model"] & {
+        readonly route: MediaRoute.AnyRoute<Self, Event, Response>;
+    };
+}
+/** `start` and `resume` fail with `UnsupportedOperation` on inline and stream routes. */
+export interface Interface<Req extends RoutedRequest<Req, Event, Response>, Event, Response> {
+    readonly generate: (request: Req, options?: AwaitOptions) => Effect.Effect<Response, AIError>;
+    readonly stream: (request: Req, options?: AwaitOptions) => Stream.Stream<Event | Observation, AIError>;
+    readonly start: (request: Req) => Effect.Effect<Generation<Response>, AIError>;
+    readonly resume: (model: Req["model"], token: unknown) => Effect.Effect<Generation<Response>, AIError>;
+}
+/** One modality's layer and service accessors, dispatching each request on its route's `kind`. */
+export declare const make: <Self, Req extends RoutedRequest<Req, Event, Response>, Event, Response>(service: Context.Service<Self, Interface<Req, Event, Response>>, input: {
+    readonly modality: string;
+    /** A completed response expanded into the streaming event shape. */
+    readonly responseEvents: (response: Response) => ReadonlyArray<Event>;
+}) => {
+    layer: Layer.Layer<Self, never, import("./route/executor-service.js").RequestExecutorService>;
+    generate: (request: Req, options?: AwaitOptions) => Effect.Effect<Response, AIError, Self>;
+    stream: (request: Req, options?: AwaitOptions) => Stream.Stream<Observation | Event, AIError, Exclude<Self, import("effect/Scope").Scope>>;
+    start: (request: Req) => Effect.Effect<Generation<Response>, AIError, Self>;
+    resume: (model: Req["model"], token: unknown) => Effect.Effect<Generation<Response>, AIError, Self>;
+};
+export * as MediaClient from "./media-client.js";

package/dist/media-client.js

@@ -0,0 +1,51 @@
+import { Effect, Layer, Stream } from "effect";
+import { resultEvents } from "./generation.js";
+import { RequestExecutor } from "./route/executor.js";
+import { AIError, UnsupportedOperationError } from "./schema/index.js";
+/** One modality's layer and service accessors, dispatching each request on its route's `kind`. */
+export const make = (service, input) => ({
+    layer: Layer.effect(service, Effect.gen(function* () {
+        const executor = yield* RequestExecutor.Service;
+        const notQueued = (route, operation) => new AIError({
+            reason: new UnsupportedOperationError({
+                operation: `${input.modality}.${operation}`,
+                provider: route.provider,
+                route: route.id,
+                message: `${route.provider}/${route.id} is not a queued route; use generate or stream`,
+            }),
+        });
+        const start = (request) => {
+            const route = request.model.route;
+            if (route.kind !== "queued")
+                return Effect.fail(notQueued(route, "start"));
+            return route.start(request, executor.execute);
+        };
+        return service.of({
+            start,
+            resume: (model, token) => {
+                if (model.route.kind !== "queued")
+                    return Effect.fail(notQueued(model.route, "resume"));
+                return model.route.resume(model, token, executor.execute);
+            },
+            generate: (request, options) => {
+                const route = request.model.route;
+                if (route.kind !== "queued")
+                    return route.generate(request, executor.execute);
+                return start(request).pipe(Effect.flatMap((generation) => generation.await(options)));
+            },
+            stream: (request, options) => {
+                const route = request.model.route;
+                if (route.kind === "stream")
+                    return route.stream(request, executor.execute);
+                if (route.kind === "queued")
+                    return Stream.unwrap(start(request).pipe(Effect.map((generation) => resultEvents(generation, input.responseEvents, options))));
+                return Stream.fromIterableEffect(Effect.map(route.generate(request, executor.execute), input.responseEvents));
+            },
+        });
+    })),
+    generate: (request, options) => service.use((client) => client.generate(request, options)),
+    stream: (request, options) => Stream.unwrap(service.useSync((client) => client.stream(request, options))),
+    start: (request) => service.use((client) => client.start(request)),
+    resume: (model, token) => service.use((client) => client.resume(model, token)),
+});
+export * as MediaClient from "./media-client.js";

package/dist/media-model.d.ts

@@ -0,0 +1,43 @@
+import { Effect } from "effect";
+import { Endpoint } from "./route/endpoint.js";
+import { MediaRoute } from "./route/media.js";
+import type { MediaProtocol } from "./route/media-protocol.js";
+import { AIError, HttpOptions, ModelID, ProviderID } from "./schema/index.js";
+/**
+ * What every media model carries: ids, the configured route, and deployment `http` overlays. Modality classes
+ * (`ImageModel`, `VideoModel`, `SpeechModel`, `TranscriptionModel`) extend it with their route type and a nominal
+ * marker so one cannot stand in for the other in requests.
+ */
+export declare class MediaModel<Route, Options> {
+    protected readonly _Options: Options;
+    readonly id: ModelID;
+    readonly provider: ProviderID;
+    readonly route: Route;
+    readonly http?: HttpOptions;
+    constructor(input: MediaModel.Input<Route>);
+}
+export declare namespace MediaModel {
+    type Options = Record<string, unknown>;
+    interface Input<Route> {
+        readonly id: string | ModelID;
+        readonly provider: string | ProviderID;
+        readonly route: Route;
+        readonly http?: HttpOptions;
+    }
+    /** A protocol plus its canonical start path; `ModelInput.baseURL` overrides `baseURL` per deployment. */
+    interface RouteInput<Request extends MediaRoute.MediaRequest, Protocol> {
+        readonly protocol: Protocol;
+        readonly path: Endpoint.EndpointPart<MediaProtocol.Body, Request>;
+        readonly baseURL?: string;
+        /** Headers the protocol requires on every call, such as a pinned API version; deployment headers win. */
+        readonly headers?: Record<string, string>;
+    }
+    type InlineRouteInput<Request extends MediaRoute.MediaRequest, Response> = RouteInput<Request, MediaProtocol.Inline<Request, Response>>;
+    type StreamRouteInput<Request extends MediaRoute.MediaRequest, Event, Frame, State> = RouteInput<MediaProtocol.Addressed<Request>, MediaProtocol.Streamed<Request, Event, Frame, State>>;
+    type QueuedRouteInput<Request extends MediaRoute.MediaRequest, Response, Token> = RouteInput<Request, MediaProtocol.Queued<Request, Response, Token>>;
+    type AnyRouteInput<Request extends MediaRoute.MediaRequest, Event, Response, Frame, State, Token> = InlineRouteInput<Request, Response> | StreamRouteInput<Request, Event, Frame, State> | QueuedRouteInput<Request, Response, Token>;
+}
+/** Compose a protocol route input with one deployment through `MediaRoute.inline`, `queued`, or `stream`. */
+export declare const composeRoute: <Request extends MediaRoute.MediaRequest, Event, Response, Frame, State, Token>(route: MediaModel.AnyRouteInput<Request, Event, Response, Frame, State, Token>, input: MediaRoute.ModelInput, collect: (events: ReadonlyArray<Event>) => Effect.Effect<Response, AIError>) => MediaRoute.AnyRoute<Request, Event, Response>;
+/** Lift a synchronous Schema-class constructor into a typed `InvalidRequest` failure. */
+export declare const tryRequest: <A>(make: () => A) => Effect.Effect<A, AIError>;

package/dist/media-model.js

@@ -0,0 +1,47 @@
+import { Effect } from "effect";
+import { Endpoint } from "./route/endpoint.js";
+import { MediaRoute } from "./route/media.js";
+import { AIError, HttpOptions, InvalidRequestError, ModelID, ProviderID } from "./schema/index.js";
+/**
+ * What every media model carries: ids, the configured route, and deployment `http` overlays. Modality classes
+ * (`ImageModel`, `VideoModel`, `SpeechModel`, `TranscriptionModel`) extend it with their route type and a nominal
+ * marker so one cannot stand in for the other in requests.
+ */
+export class MediaModel {
+    id;
+    provider;
+    route;
+    http;
+    constructor(input) {
+        this.id = ModelID.make(input.id);
+        this.provider = ProviderID.make(input.provider);
+        this.route = input.route;
+        this.http = input.http;
+    }
+}
+/** Compose a protocol route input with one deployment through `MediaRoute.inline`, `queued`, or `stream`. */
+export const composeRoute = (route, input, collect) => {
+    if (isStreamInput(route))
+        return MediaRoute.stream({ ...composition(route, input), collect });
+    if (isQueuedInput(route))
+        return MediaRoute.queued(composition(route, input));
+    return MediaRoute.inline(composition(route, input));
+};
+const composition = (route, input) => ({
+    protocol: route.protocol,
+    endpoint: Endpoint.path(route.path, { baseURL: input.baseURL ?? route.baseURL }),
+    auth: input.auth,
+    headers: route.headers === undefined && input.headers === undefined ? undefined : { ...route.headers, ...input.headers },
+});
+const isStreamInput = (route) => route.protocol.kind === "stream";
+const isQueuedInput = (route) => route.protocol.kind === "queued";
+/** Lift a synchronous Schema-class constructor into a typed `InvalidRequest` failure. */
+export const tryRequest = (make) => Effect.try({
+    try: make,
+    catch: (error) => new AIError({
+        reason: new InvalidRequestError({
+            message: error instanceof Error ? error.message : String(error),
+            cause: error,
+        }),
+    }),
+});

package/dist/media.d.ts

@@ -19,8 +19,6 @@ export declare const Source: Schema.Union<readonly [Schema.Struct<{
     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">;
@@ -28,6 +26,8 @@ export declare const Source: Schema.Union<readonly [Schema.Struct<{
     readonly mediaType: Schema.optional<Schema.String>;
 }>]>;
 export type Source = Schema.Schema.Type<typeof Source>;
+export type AspectRatio = `${number}:${number}`;
+export declare const AspectRatio: Schema.declare<`${number}:${number}`, `${number}:${number}`>;
 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;
@@ -65,6 +65,8 @@ export declare class Asset {
     /** Epoch milliseconds after which a `url` source stops resolving. */
     readonly expiresAt?: number;
     readonly providerMetadata?: ProviderMetadata;
+    /** Transient download credentials for `url` sources; see `Asset.Input.headers`. */
+    readonly headers?: Record<string, string>;
     constructor(input: Asset.Input);
     /** Inline payload without effects, for protocols that embed base64 or data URLs directly. */
     inline(): Inline | undefined;
@@ -84,9 +86,6 @@ export declare class Asset {
         } | {
             readonly type: "url";
             readonly url: string;
-            readonly headers?: {
-                readonly [x: string]: string;
-            } | undefined;
             readonly mediaType?: string | undefined;
             readonly expiresAt?: number | undefined;
         } | {
@@ -122,6 +121,12 @@ export declare namespace Asset {
         readonly source: Source;
         readonly info?: Info;
         readonly providerMetadata?: ProviderMetadata;
+        /**
+         * Headers required to download a `url` source, such as the provider API key Veo demands for its file URIs.
+         * They are runtime-only: never part of `source`, `toJSON()`, or `AssetSchema`, so a persisted asset cannot leak
+         * credentials and cannot be downloaded again after a round-trip. Call `materialize()` before persisting.
+         */
+        readonly headers?: Record<string, string>;
     }
 }
 /** JSON form of an asset: the serializable `Source` plus caller-supplied metadata. `bytes` sources encode as base64. */
@@ -140,8 +145,6 @@ export declare const AssetEncoded: Schema.Struct<{
         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">;
@@ -175,8 +178,6 @@ export declare const AssetSchema: Schema.decodeTo<Schema.declare<Asset, Asset>,
         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">;

package/dist/media.js

@@ -5,7 +5,7 @@ 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";
+import { detectMediaType, fileMediaType } from "./utils/media-type.js";
 export { detectMediaType } from "./utils/media-type.js";
 const OCTET_STREAM = "application/octet-stream";
 // ---------------------------------------------------------------------------
@@ -27,8 +27,6 @@ const UrlSource = Schema.Struct({
     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({
@@ -40,9 +38,7 @@ const RefSource = Schema.Struct({
 export const Source = Schema.Union([BytesSource, Base64Source, UrlSource, RefSource])
     .pipe(Schema.toTaggedUnion("type"))
     .annotate({ identifier: "Media.Source" });
-// ---------------------------------------------------------------------------
-// Kind, Info, Notice
-// ---------------------------------------------------------------------------
+export const AspectRatio = Schema.declare((value) => typeof value === "string" && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(value), { title: "Media.AspectRatio" });
 export const Kind = Schema.Literals(["image", "video", "audio", "document", "other"]);
 export const kindOf = (mediaType) => {
     const lower = mediaType.toLowerCase();
@@ -85,6 +81,8 @@ export class Asset {
     /** Epoch milliseconds after which a `url` source stops resolving. */
     expiresAt;
     providerMetadata;
+    /** Transient download credentials for `url` sources; see `Asset.Input.headers`. */
+    headers;
     // 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.
@@ -100,6 +98,7 @@ export class Asset {
         this.info = input.info;
         this.expiresAt = input.source.type === "url" ? input.source.expiresAt : undefined;
         this.providerMetadata = input.providerMetadata;
+        this.headers = input.source.type === "url" ? input.headers : undefined;
     }
     /** Inline payload without effects, for protocols that embed base64 or data URLs directly. */
     inline() {
@@ -122,7 +121,7 @@ export class Asset {
                 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);
+                : download(source, this.headers);
             return decoded.pipe(Effect.tap((data) => Effect.sync(() => (this.#bytes = data))));
         });
     }
@@ -177,9 +176,9 @@ 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 download = Effect.fn("Media.download")(function* (source, headers) {
     const executor = yield* Service;
-    const response = yield* executor.execute(HttpClientRequest.get(source.url).pipe(HttpClientRequest.setHeaders(source.headers ?? {})));
+    const response = yield* executor.execute(HttpClientRequest.get(source.url).pipe(HttpClientRequest.setHeaders(headers ?? {})));
     const buffer = yield* response.arrayBuffer.pipe(Effect.mapError((cause) => new AIError({
         reason: new InvalidProviderOutputError({
             message: `Failed to read media from ${source.url}`,
@@ -193,8 +192,8 @@ 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);
+    const { mediaType, expiresAt, ...rest } = options ?? {};
+    return from({ type: "url", url: value, mediaType, expiresAt }, rest);
 };
 export const ref = (provider, id, mediaType, options) => from({ type: "ref", provider: ProviderID.make(provider), id, mediaType }, options);
 const DATA_URL = /^data:([^;,]+)(?:;[^,]*)*;base64,(.*)$/s;
@@ -216,7 +215,7 @@ export const file = (path, options) => Effect.gen(function* () {
     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);
+    return bytes(data, fileMediaType(data, path), options);
 });
 /** Materialize an asset and write its bytes through `FileSystem`. */
 export const write = (asset, path) => Effect.gen(function* () {