@opencode/ai 2.0.14 → 2.0.16

package/dist/route/media-protocol.d.ts

@@ -0,0 +1,158 @@
+import { Duration, Effect, Schema, type Stream } from "effect";
+import { HttpClientResponse } from "effect/unstable/http";
+import type { Snapshot, Status } from "../generation.js";
+import { Media } from "../media.js";
+import type { AuthInput } from "./auth.js";
+import { AIError, HttpContext } from "../schema/index.js";
+/** Array values become repeated parameters (`keyterm=a&keyterm=b`). */
+export type Query = Readonly<Record<string, string | ReadonlyArray<string>>>;
+/** `query` is appended to the endpoint URL before the route and caller `http.query` overlays. */
+export type Body = {
+    readonly type: "json";
+    readonly value: Record<string, unknown>;
+    readonly query?: Query;
+} | {
+    readonly type: "multipart";
+    readonly value: FormData;
+} | {
+    readonly type: "binary";
+    readonly value: Uint8Array;
+    readonly contentType: string;
+    readonly query?: Query;
+};
+export declare const json: (value: Record<string, unknown>, query?: Query) => Body;
+export declare const multipart: (value: FormData) => Body;
+export declare const binary: (value: Uint8Array, contentType: string, query?: Query) => Body;
+export type Send = (path: string, body: Body) => Effect.Effect<HttpClientResponse.HttpClientResponse, AIError>;
+/** Runs after unsupported-field rejection and before `body.from`, for providers that need an upload first. */
+export type Prepare<Request> = (request: Request, send: Send) => Effect.Effect<Request, AIError>;
+export interface DecodeContext<Request> {
+    readonly request: Request;
+    readonly body: Body;
+}
+/** One request, one response. JSON or multipart in; JSON or raw bytes out. */
+export interface Inline<Request, Response> {
+    readonly kind: "inline";
+    readonly id: string;
+    readonly name: string;
+    /** Common request fields this protocol cannot lower; the route rejects them before `body.from` runs. */
+    readonly unsupported?: ReadonlyArray<keyof Request & string>;
+    readonly body: {
+        readonly from: (request: Request) => Effect.Effect<Body, AIError>;
+    };
+    readonly response: {
+        readonly decode: (response: HttpClientResponse.HttpClientResponse, context: DecodeContext<Request>) => Effect.Effect<Response, AIError>;
+    };
+}
+export declare const inline: <Request, Response>(input: Omit<Inline<Request, Response>, "kind">) => Inline<Request, Response>;
+/** What `start` learned from the submission response: the route-owned handle plus the first observation. */
+export interface Started<Token> {
+    readonly token: Token;
+    readonly snapshot: Snapshot;
+}
+/**
+ * A follow-up call's inputs: the decoded token and the auth headers the route sent, so a protocol can attach them
+ * to output URLs that require the same credentials to download (Veo). `materialize` downloads an output through the
+ * route's executor, for URLs that expire too soon to hand back (BFL).
+ */
+export interface PollContext<Token> {
+    readonly token: Token;
+    readonly auth: Record<string, string>;
+    readonly materialize: (asset: Media.Asset) => Effect.Effect<Media.Asset, AIError>;
+}
+/**
+ * Submit, then poll. `start` posts the body to the route endpoint; `status`, `result`, and `cancel` are follow-up
+ * calls addressed by the token. Paths are relative to the route base URL unless the provider hands back absolute
+ * URLs (fal `status_url`), in which case they are used verbatim. `result` is always its own GET: providers that
+ * return the output inside the status body (Veo, xAI, Runway) point `result.path` at the status path and decode the
+ * same document, so `Generation.await` and `Video.resume(...).await()` behave identically everywhere.
+ */
+export interface Queued<Request, Response, Token> {
+    readonly kind: "queued";
+    readonly id: string;
+    readonly name: string;
+    /** Common request fields this protocol cannot lower; the route rejects them before `start.body.from` runs. */
+    readonly unsupported?: ReadonlyArray<keyof Request & string>;
+    /** Serializable handle. `Generation.token` carries the encoded form so it can be persisted and resumed elsewhere. */
+    readonly token: Schema.Codec<Token, unknown>;
+    readonly start: {
+        readonly prepare?: Prepare<Request>;
+        readonly body: {
+            readonly from: (request: Request) => Effect.Effect<Body, AIError>;
+        };
+        readonly decode: (response: HttpClientResponse.HttpClientResponse, context: DecodeContext<Request>) => Effect.Effect<Started<Token>, AIError>;
+    };
+    readonly status: {
+        readonly path: (token: Token) => string;
+        readonly decode: (response: HttpClientResponse.HttpClientResponse, context: PollContext<Token>) => Effect.Effect<Snapshot, AIError>;
+    };
+    readonly result: {
+        readonly path: (token: Token) => string;
+        readonly decode: (response: HttpClientResponse.HttpClientResponse, context: PollContext<Token>) => Effect.Effect<Response, AIError>;
+    };
+    readonly cancel?: {
+        readonly method: AuthInput["method"];
+        readonly path: (token: Token) => string;
+    };
+}
+export declare const queued: <Request, Response, Token>(input: Omit<Queued<Request, Response, Token>, "kind">) => Queued<Request, Response, Token>;
+export type Mode = "generate" | "stream";
+export type Addressed<Request> = Request & {
+    readonly mode: Mode;
+};
+export interface ResponseContext<Request> extends DecodeContext<Addressed<Request>> {
+    readonly http: HttpContext;
+}
+/**
+ * One request whose body is parsed incrementally, like LLM protocols: `frames` → `step`* → `finish`. `generate` and
+ * `stream` share this state machine; `request.mode` lets a protocol pick a different body, path, or framing.
+ */
+export interface Streamed<Request, Event, Frame, State> {
+    readonly kind: "stream";
+    readonly id: string;
+    readonly name: string;
+    /** Common request fields this protocol cannot lower; the route rejects them before `body.from` runs. */
+    readonly unsupported?: ReadonlyArray<keyof Request & string>;
+    readonly body: {
+        readonly from: (request: Addressed<Request>) => Effect.Effect<Body, AIError>;
+    };
+    readonly frames: (bytes: Stream.Stream<Uint8Array, AIError>, context: DecodeContext<Addressed<Request>>) => Stream.Stream<Frame, AIError>;
+    readonly initial: () => State;
+    readonly step: (state: State, frame: Frame) => Effect.Effect<readonly [State, ReadonlyArray<Event>], AIError>;
+    /** Emit exactly one terminal event, or fail when the provider stopped before completing. */
+    readonly finish: (state: State, context: ResponseContext<Request>) => Effect.Effect<ReadonlyArray<Event>, AIError>;
+}
+export declare const stream: <Request, Event, Frame, State>(input: Omit<Streamed<Request, Event, Frame, State>, "kind">) => Streamed<Request, Event, Frame, State>;
+/**
+ * Read a text body while retaining the original payload and HTTP context on every downstream error. `invalid` is a
+ * malformed provider document; `ended` is a generation that reached a terminal status without output (`failed` is
+ * provider-side, `cancelled`/`expired` mean the result will never exist); `contentPolicy` is a moderated result.
+ */
+export declare const text: (route: string, name: string, response: HttpClientResponse.HttpClientResponse) => Effect.Effect<{
+    body: string;
+    http: HttpContext;
+    invalid: (message: string, cause?: unknown) => AIError;
+    ended: (status: Exclude<Status, "queued" | "running" | "completed">, message: string) => AIError;
+    contentPolicy: (message: string) => AIError;
+}, AIError, never>;
+export type Output = Effect.Success<ReturnType<typeof text>>;
+/** Read and Schema-decode a JSON body. Decode failures keep the raw body as `reason.body`. */
+export declare const decodeJson: <A>(route: string, name: string, schema: Schema.Codec<A, unknown>) => (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<{
+    value: A;
+    body: string;
+    http: HttpContext;
+    invalid: (message: string, cause?: unknown) => AIError;
+    ended: (status: Exclude<Status, "queued" | "running" | "completed">, message: string) => AIError;
+    contentPolicy: (message: string) => AIError;
+}, AIError, never>;
+/** Decode a submission response into the token and first snapshot. */
+export declare const decodeStarted: <A, Token>(route: string, name: string, schema: Schema.Codec<A, unknown>, started: (value: A) => Started<Token>) => (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<Started<Token>, AIError, never>;
+/** Map a provider status string through the protocol's table; unknown values are an invalid provider document. */
+export declare const status: <Table extends Record<string, Status>>(table: Table, raw: string, output: Output) => Effect.Effect<Status, AIError>;
+export declare const frameError: (route: string, message: string, body?: string, cause?: unknown) => AIError;
+export declare const incomplete: (route: string) => AIError;
+/** Schema-decode one JSON stream frame. Decode failures keep the frame as `reason.body`. */
+export declare const decodeFrame: <A>(route: string, name: string, schema: Schema.Codec<A, unknown>) => (frame: string) => Effect.Effect<A, AIError, never>;
+/** A `url` asset whose provider-declared retention window starts now. */
+export declare const expiringUrl: (url: string, retention: Duration.Duration, options?: Parameters<typeof Media.url>[1]) => Effect.Effect<Media.Asset, never, never>;
+export * as MediaProtocol from "./media-protocol.js";

package/dist/route/media-protocol.js

@@ -0,0 +1,96 @@
+import { Clock, Duration, Effect, Schema } from "effect";
+import { HttpClientResponse } from "effect/unstable/http";
+import { Media } from "../media.js";
+import { AIError, ContentPolicyError, HttpContext, InvalidProviderOutputError, InvalidRequestError, ProviderInternalError, } from "../schema/index.js";
+export const json = (value, query) => ({
+    type: "json",
+    value,
+    query,
+});
+export const multipart = (value) => ({ type: "multipart", value });
+export const binary = (value, contentType, query) => ({
+    type: "binary",
+    value,
+    contentType,
+    query,
+});
+export const inline = (input) => ({
+    kind: "inline",
+    ...input,
+});
+export const queued = (input) => ({
+    kind: "queued",
+    ...input,
+});
+export const stream = (input) => ({
+    kind: "stream",
+    ...input,
+});
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+const context = (response) => new HttpContext({ url: response.request.url, status: response.status, headers: response.headers });
+/**
+ * Read a text body while retaining the original payload and HTTP context on every downstream error. `invalid` is a
+ * malformed provider document; `ended` is a generation that reached a terminal status without output (`failed` is
+ * provider-side, `cancelled`/`expired` mean the result will never exist); `contentPolicy` is a moderated result.
+ */
+export const text = Effect.fn("MediaProtocol.text")(function* (route, name, response) {
+    const http = context(response);
+    const body = yield* response.text.pipe(Effect.mapError((cause) => new AIError({
+        reason: new InvalidProviderOutputError({
+            route,
+            message: `Failed to read the ${name} response`,
+            http,
+            cause,
+        }),
+    })));
+    return {
+        body,
+        http,
+        invalid: (message, cause) => new AIError({ reason: new InvalidProviderOutputError({ route, message, body, http, cause }) }),
+        ended: (status, message) => new AIError({
+            reason: status === "failed"
+                ? new ProviderInternalError({ message, body, http })
+                : new InvalidRequestError({ message, body, http }),
+        }),
+        contentPolicy: (message) => new AIError({ reason: new ContentPolicyError({ message, body, http }) }),
+    };
+});
+/** Read and Schema-decode a JSON body. Decode failures keep the raw body as `reason.body`. */
+export const decodeJson = (route, name, schema) => {
+    const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema));
+    return Effect.fn("MediaProtocol.decodeJson")(function* (response) {
+        const output = yield* text(route, name, response);
+        const value = yield* decode(output.body).pipe(Effect.mapError((cause) => output.invalid(`${name} returned an invalid response`, cause)));
+        return { ...output, value };
+    });
+};
+/** Decode a submission response into the token and first snapshot. */
+export const decodeStarted = (route, name, schema, started) => {
+    const decode = decodeJson(route, name, schema);
+    return (response) => decode(response).pipe(Effect.map((output) => started(output.value)));
+};
+/** Map a provider status string through the protocol's table; unknown values are an invalid provider document. */
+export const status = (table, raw, output) => {
+    const normalized = table[raw];
+    if (normalized === undefined)
+        return Effect.fail(output.invalid(`Unknown generation status "${raw}"`));
+    return Effect.succeed(normalized);
+};
+export const frameError = (route, message, body, cause) => new AIError({ reason: new InvalidProviderOutputError({ route, message, body, cause }) });
+export const incomplete = (route) => new AIError({
+    reason: new InvalidProviderOutputError({
+        route,
+        message: "The provider response ended unexpectedly.",
+        classification: "incomplete-stream",
+    }),
+});
+/** Schema-decode one JSON stream frame. Decode failures keep the frame as `reason.body`. */
+export const decodeFrame = (route, name, schema) => {
+    const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(schema));
+    return (frame) => decode(frame).pipe(Effect.mapError((cause) => frameError(route, `${name} sent an invalid stream event`, frame, cause)));
+};
+/** A `url` asset whose provider-declared retention window starts now. */
+export const expiringUrl = (url, retention, options) => Clock.currentTimeMillis.pipe(Effect.map((now) => Media.url(url, { ...options, expiresAt: now + Duration.toMillis(retention) })));
+export * as MediaProtocol from "./media-protocol.js";

package/dist/route/media.d.ts

@@ -0,0 +1,97 @@
+import { Effect, Stream } from "effect";
+import { Auth } from "./auth.js";
+import { Endpoint } from "./endpoint.js";
+import { type Interface } from "./executor-service.js";
+import { MediaProtocol } from "./media-protocol.js";
+import { Generation, type AwaitOptions, type Observation } from "../generation.js";
+import { AIError, HttpOptions, ProviderID } from "../schema/index.js";
+export type Execute = Interface["execute"];
+/** The minimum a media request must carry for the route to build a transport request. */
+export interface MediaRequest {
+    readonly model: {
+        readonly id: string;
+        readonly provider: ProviderID;
+        readonly http?: HttpOptions;
+    };
+    readonly http?: HttpOptions;
+}
+/** Deployment inputs every media model factory accepts; provider facades fill these from `configure(...)`. */
+export interface ModelInput {
+    readonly id: string;
+    readonly auth: Auth.Definition;
+    readonly baseURL?: string;
+    readonly headers?: Record<string, string>;
+    readonly http?: HttpOptions;
+}
+/** One request, one response. */
+export interface Route<Request extends MediaRequest, Response> {
+    readonly kind: "inline";
+    readonly id: string;
+    readonly provider: ProviderID;
+    readonly protocol: string;
+    readonly generate: (request: Request, execute: Execute) => Effect.Effect<Response, AIError>;
+}
+/** Submit, then poll through the returned `Generation`. */
+export interface QueuedRoute<Request extends MediaRequest, Response> {
+    readonly kind: "queued";
+    readonly id: string;
+    readonly provider: ProviderID;
+    readonly protocol: string;
+    readonly start: (request: Request, execute: Execute) => Effect.Effect<Generation<Response>, AIError>;
+    /** Rebuild a handle from a persisted `Generation.token`; fails typed when the token is not this route's. */
+    readonly resume: (model: MediaRequest["model"], token: unknown, execute: Execute) => Effect.Effect<Generation<Response>, AIError>;
+}
+/** One request whose response parses into events; `generate` runs the same stream and collects it. */
+export interface StreamRoute<Request extends MediaRequest, Event, Response> {
+    readonly kind: "stream";
+    readonly id: string;
+    readonly provider: ProviderID;
+    readonly protocol: string;
+    readonly stream: (request: Request, execute: Execute) => Stream.Stream<Event, AIError>;
+    readonly generate: (request: Request, execute: Execute) => Effect.Effect<Response, AIError>;
+}
+export type AnyRoute<Request extends MediaRequest, Event, Response> = Route<Request, Response> | StreamRoute<Request, Event, Response> | QueuedRoute<Request, Response>;
+export interface Composition<Request extends MediaRequest> {
+    readonly id: string;
+    readonly provider: string | ProviderID;
+    readonly endpoint: Endpoint.Definition<MediaProtocol.Body, Request>;
+    readonly auth: Auth.Definition;
+    /** Deployment headers applied before transport authentication. */
+    readonly headers?: Record<string, string>;
+}
+export interface InlineInput<Request extends MediaRequest, Response> extends Composition<Request> {
+    readonly protocol: MediaProtocol.Inline<Request, Response>;
+}
+export interface QueuedInput<Request extends MediaRequest, Response, Token> extends Composition<Request> {
+    readonly protocol: MediaProtocol.Queued<Request, Response, Token>;
+}
+export interface StreamInput<Request extends MediaRequest, Event, Response, Frame, State> extends Composition<MediaProtocol.Addressed<Request>> {
+    readonly protocol: MediaProtocol.Streamed<Request, Event, Frame, State>;
+    readonly collect: (events: ReadonlyArray<Event>) => Effect.Effect<Response, AIError>;
+}
+/**
+ * Compose an inline media protocol with an endpoint and auth into a runnable route. The route owns the transport
+ * plumbing every media protocol would otherwise duplicate: option merging, surrogate sanitizing, unsupported-field
+ * rejection, URL and query rendering, auth headers, JSON, multipart, or binary encoding, and handing responses back
+ * to the protocol.
+ */
+export declare const inline: <Request extends MediaRequest, Response>(input: InlineInput<Request, Response>) => Route<Request, Response>;
+/**
+ * Compose a queued media protocol the same way, adding `start`/`resume` handles whose polls reuse the route's auth,
+ * deployment headers, and (for `start`) the request's `http` overlay. The token is decoded once at the boundary and
+ * closed over by the resulting `Generation.Route`.
+ */
+export declare const queued: <Request extends MediaRequest, Response, Token>(input: QueuedInput<Request, Response, Token>) => QueuedRoute<Request, Response>;
+/** Compose a streaming media protocol; `generate` runs the same stream in `generate` mode and folds it with `collect`. */
+export declare const stream: <Request extends MediaRequest, Event, Response, Frame, State>(input: StreamInput<Request, Event, Response, Frame, State>) => StreamRoute<Request, Event, Response>;
+export declare const dispatch: <Event, Response>(input: {
+    readonly modality: string;
+    readonly execute: Execute;
+    readonly responseEvents: (response: Response) => ReadonlyArray<Event>;
+}) => {
+    start: <Request extends MediaRequest>(route: AnyRoute<Request, Event, Response>, request: Request) => Effect.Effect<Generation<Response>, AIError, never>;
+    resume: <Request extends MediaRequest>(route: AnyRoute<Request, Event, Response>, model: MediaRequest["model"], token: unknown) => Effect.Effect<Generation<Response>, AIError, never>;
+    generate: <Request extends MediaRequest>(route: AnyRoute<Request, Event, Response>, request: Request, options?: AwaitOptions) => Effect.Effect<Response, AIError, never>;
+    stream: <Request extends MediaRequest>(route: AnyRoute<Request, Event, Response>, request: Request, options?: AwaitOptions) => Stream.Stream<Event | Observation, AIError>;
+};
+export * as MediaRoute from "./media.js";

package/dist/route/media.js

@@ -0,0 +1,236 @@
+import { Effect, Schema, Stream } from "effect";
+import { Headers, HttpClientRequest } from "effect/unstable/http";
+import { Auth } from "./auth.js";
+import { Endpoint } from "./endpoint.js";
+import { Service as RequestExecutorService } from "./executor-service.js";
+import { RequestExecutor } from "./executor.js";
+import { MediaProtocol } from "./media-protocol.js";
+import { Generation, resultEvents, } from "../generation.js";
+import { ProviderShared } from "../protocols/shared.js";
+import { AIError, AIErrorReason, HttpOptions, InvalidRequestError, ProviderID, mergeHttpOptions, } from "../schema/index.js";
+import { sanitizeSurrogates } from "../utils/sanitize.js";
+/**
+ * Compose an inline media protocol with an endpoint and auth into a runnable route. The route owns the transport
+ * plumbing every media protocol would otherwise duplicate: option merging, surrogate sanitizing, unsupported-field
+ * rejection, URL and query rendering, auth headers, JSON, multipart, or binary encoding, and handing responses back
+ * to the protocol.
+ */
+export const inline = (input) => {
+    const transport = makeTransport(input);
+    return {
+        kind: "inline",
+        id: input.id,
+        provider: transport.provider,
+        protocol: input.protocol.id,
+        generate: Effect.fn(`MediaRoute.generate`)(function* (request, execute) {
+            const submitted = yield* transport.submit(request, { unsupported: input.protocol.unsupported, from: input.protocol.body.from }, execute);
+            return yield* input.protocol.response.decode(submitted.response, submitted.context);
+        }),
+    };
+};
+/**
+ * Compose a queued media protocol the same way, adding `start`/`resume` handles whose polls reuse the route's auth,
+ * deployment headers, and (for `start`) the request's `http` overlay. The token is decoded once at the boundary and
+ * closed over by the resulting `Generation.Route`.
+ */
+export const queued = (input) => {
+    const transport = makeTransport(input);
+    const protocol = input.protocol;
+    const decodeToken = Schema.decodeUnknownEffect(protocol.token);
+    // A protocol producing a token its own codec rejects is a programmer defect, not a provider error.
+    const encodeToken = Schema.encodeSync(protocol.token);
+    const generationRoute = (token, http, execute) => {
+        const materialize = (asset) => asset.materialize().pipe(Effect.provideService(RequestExecutorService, { execute }));
+        const poll = (operation) => transport
+            .call("GET", operation.path(token), http, execute)
+            .pipe(Effect.flatMap((sent) => operation.decode(sent.response, { token, auth: sent.auth, materialize })));
+        const cancel = protocol.cancel;
+        const route = {
+            status: poll(protocol.status),
+            result: poll(protocol.result),
+            cancel: cancel === undefined
+                ? undefined
+                : transport.call(cancel.method, cancel.path(token), http, execute).pipe(Effect.asVoid),
+        };
+        return route;
+    };
+    const start = Effect.fn("MediaRoute.start")(function* (request, execute) {
+        const submitted = yield* transport.submit(request, { unsupported: protocol.unsupported, prepare: protocol.start.prepare, from: protocol.start.body.from }, execute);
+        const started = yield* protocol.start.decode(submitted.response, submitted.context);
+        const route = generationRoute(started.token, submitted.context.request.http, execute);
+        return new Generation(route, encodeToken(started.token), started.snapshot);
+    });
+    const resume = Effect.fn("MediaRoute.resume")(function* (model, raw, execute) {
+        const token = yield* decodeToken(raw).pipe(Effect.mapError((cause) => new AIError({
+            reason: new InvalidRequestError({
+                message: `${input.id} cannot resume a generation from this token`,
+                cause,
+            }),
+        })));
+        const route = generationRoute(token, transport.http(model), execute);
+        return new Generation(route, encodeToken(token), yield* route.status);
+    });
+    return { kind: "queued", id: input.id, provider: transport.provider, protocol: protocol.id, start, resume };
+};
+/** Compose a streaming media protocol; `generate` runs the same stream in `generate` mode and folds it with `collect`. */
+export const stream = (input) => {
+    const transport = makeTransport(input);
+    const protocol = input.protocol;
+    const events = (request, execute, mode) => Stream.unwrap(Effect.gen(function* () {
+        const submitted = yield* transport.submit({ ...request, mode }, { unsupported: protocol.unsupported, from: protocol.body.from }, execute);
+        const http = RequestExecutor.responseHttp(submitted.response);
+        return Stream.suspend(() => {
+            // Parser state is local to one response, exactly like `Route.make`'s LLM stream loop.
+            let state = protocol.initial();
+            return protocol.frames(RequestExecutor.responseStream(submitted.response), submitted.context).pipe(Stream.mapEffect((frame) => protocol.step(state, frame).pipe(Effect.map(([next, output]) => {
+                state = next;
+                return output;
+            }))), Stream.flattenIterable, Stream.concat(Stream.suspend(() => Stream.fromIterableEffect(protocol.finish(state, { ...submitted.context, http })))), Stream.mapError((error) => error.reason.http !== undefined
+                ? error
+                : new AIError({
+                    reason: AIErrorReason.make({
+                        ...error.reason,
+                        message: error.reason.message,
+                        cause: error.reason.cause,
+                        http,
+                    }),
+                })));
+        });
+    }));
+    return {
+        kind: "stream",
+        id: input.id,
+        provider: transport.provider,
+        protocol: protocol.id,
+        stream: (request, execute) => events(request, execute, "stream"),
+        generate: (request, execute) => events(request, execute, "generate").pipe(Stream.runCollect, Effect.flatMap(input.collect)),
+    };
+};
+export const dispatch = (input) => {
+    const notQueued = (route, operation) => ProviderShared.unsupportedOperation({
+        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 = (route, request) => {
+        if (route.kind !== "queued")
+            return Effect.fail(notQueued(route, "start"));
+        return route.start(request, input.execute);
+    };
+    return {
+        start,
+        resume: (route, model, token) => {
+            if (route.kind !== "queued")
+                return Effect.fail(notQueued(route, "resume"));
+            return route.resume(model, token, input.execute);
+        },
+        generate: (route, request, options) => {
+            if (route.kind !== "queued")
+                return route.generate(request, input.execute);
+            return start(route, request).pipe(Effect.flatMap((generation) => generation.await(options)));
+        },
+        stream: (route, request, options) => {
+            if (route.kind === "stream")
+                return route.stream(request, input.execute);
+            if (route.kind === "queued")
+                return Stream.unwrap(start(route, request).pipe(Effect.map((generation) => resultEvents(generation, input.responseEvents, options))));
+            return Stream.fromIterableEffect(Effect.map(route.generate(request, input.execute), input.responseEvents));
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// Transport plumbing shared by every kind
+// ---------------------------------------------------------------------------
+const makeTransport = (input) => {
+    const provider = ProviderID.make(input.provider);
+    const routeHttp = input.headers === undefined ? undefined : new HttpOptions({ headers: input.headers });
+    const authorize = Auth.toEffect(input.auth);
+    const baseURL = (path) => new URL(`${ProviderShared.trimBaseUrl(input.endpoint.baseURL ?? "")}${path}`);
+    /** `auth` is only what `Auth` added, never deployment headers. */
+    const send = Effect.fn("MediaRoute.send")(function* (call, execute) {
+        const encoded = encode(call.body, call.headers);
+        const url = call.url.toString();
+        const headers = yield* authorize({
+            request: call.request,
+            method: call.method,
+            url,
+            body: encoded.text,
+            headers: encoded.headers,
+        });
+        const response = yield* execute(encoded.apply(HttpClientRequest.make(call.method)(url).pipe(HttpClientRequest.setHeaders(headers))));
+        return { response, auth: Object.fromEntries(Object.entries(headers).filter(([key]) => !(key in call.headers))) };
+    });
+    return {
+        provider,
+        /** Route and model overlays; `start` additionally merges the request's own `http`. */
+        http: (model) => mergeHttpOptions(routeHttp, model.http),
+        /** POST the protocol body to the route endpoint. */
+        submit: Effect.fn("MediaRoute.submit")(function* (request, protocol, execute) {
+            yield* rejectUnsupported(input.id, provider, request, protocol.unsupported);
+            const http = mergeHttpOptions(routeHttp, request.model.http, request.http);
+            const headers = Headers.fromInput(http?.headers);
+            const prepared = protocol.prepare === undefined
+                ? request
+                : yield* protocol.prepare(request, (path, body) => send({ method: "POST", url: baseURL(path), headers, request, body }, execute).pipe(Effect.map((sent) => sent.response)));
+            // Sanitize after merging so model-level overlays are covered; the model value is restored, not sanitized.
+            const resolved = { ...sanitizeSurrogates({ ...prepared, http }), model: request.model };
+            const body = yield* protocol.from(resolved);
+            const url = withQuery(withQuery(Endpoint.render(input.endpoint, { request: resolved, body }), body.type === "multipart" ? undefined : body.query), http?.query);
+            const sent = yield* send({ method: "POST", url, headers, request: resolved, body }, execute);
+            return { response: sent.response, context: { request: resolved, body } };
+        }),
+        /** Bodiless follow-up call (status, result, cancel) with the same auth and headers as `submit`. */
+        call: (method, path, http, execute) => {
+            // Provider-issued absolute URLs (fal `status_url`) are used as-is; everything else resolves against the base.
+            const url = withQuery(/^https?:\/\//.test(path) ? new URL(path) : baseURL(path), http?.query);
+            for (const [key, value] of Object.entries(input.endpoint.query ?? {}))
+                url.searchParams.set(key, value);
+            return send({ method, url, headers: Headers.fromInput(http?.headers), request: { http } }, execute);
+        },
+    };
+};
+const withQuery = (url, query) => {
+    for (const [key, value] of Object.entries(query ?? {})) {
+        url.searchParams.delete(key);
+        for (const item of typeof value === "string" ? [value] : value)
+            url.searchParams.append(key, item);
+    }
+    return url;
+};
+const encode = (body, headers) => {
+    if (body === undefined)
+        return { text: "", headers, apply: (request) => request };
+    if (body.type === "json") {
+        const text = ProviderShared.encodeJson(body.value);
+        return { text, headers, apply: HttpClientRequest.bodyText(text, "application/json") };
+    }
+    if (body.type === "binary")
+        return {
+            text: `[${body.contentType}]`,
+            headers,
+            apply: HttpClientRequest.bodyUint8Array(body.value, body.contentType),
+        };
+    return {
+        text: "[multipart/form-data]",
+        // The HTTP client sets the multipart boundary; a caller-supplied content-type would corrupt it.
+        headers: Headers.remove(headers, "content-type"),
+        apply: HttpClientRequest.bodyFormData(body.value),
+    };
+};
+/** Common fields are never silently dropped: a present field the protocol declared unsupported fails typed. */
+const rejectUnsupported = (route, provider, request, unsupported) => {
+    const present = (unsupported ?? []).filter((field) => {
+        const value = request[field];
+        return Array.isArray(value) ? value.length > 0 : value !== undefined;
+    });
+    if (present.length === 0)
+        return Effect.void;
+    return Effect.fail(ProviderShared.unsupportedOperation({
+        operation: `media.${present[0]}`,
+        provider,
+        route,
+        message: `${provider}/${route} does not support ${present.join(", ")}`,
+    }));
+};
+export * as MediaRoute from "./media.js";

package/dist/schema/errors.d.ts

@@ -147,13 +147,23 @@ declare const UnknownProviderError_base: Schema.Class<UnknownProviderError, Sche
 }>, import("effect/Cause").YieldableError>;
 export declare class UnknownProviderError extends UnknownProviderError_base {
 }
-export declare const AIErrorReason: Schema.toTaggedUnion<"_tag", readonly [typeof InvalidRequestError, typeof UnsupportedOperationError, typeof NoRouteError, typeof AuthenticationError, typeof RateLimitError, typeof QuotaExceededError, typeof ContentPolicyError, typeof ProviderInternalError, typeof TransportError, typeof InvalidProviderOutputError, typeof UnknownProviderError]>;
+declare const TimeoutError_base: Schema.Class<TimeoutError, Schema.TaggedStruct<"Timeout", {
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+    readonly message: Schema.String;
+    readonly body: Schema.optional<Schema.String>;
+    readonly http: Schema.optional<typeof HttpContext>;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/** A caller-supplied deadline elapsed, such as `Generation.await` polling past its `Poll.timeout`. */
+export declare class TimeoutError extends TimeoutError_base {
+}
+export declare const AIErrorReason: Schema.toTaggedUnion<"_tag", readonly [typeof InvalidRequestError, typeof UnsupportedOperationError, typeof NoRouteError, typeof AuthenticationError, typeof RateLimitError, typeof QuotaExceededError, typeof ContentPolicyError, typeof ProviderInternalError, typeof TransportError, typeof InvalidProviderOutputError, typeof UnknownProviderError, typeof TimeoutError]>;
 export type AIErrorReason = Schema.Schema.Type<typeof AIErrorReason>;
 declare const AIError_base: Schema.Class<AIError, Schema.TaggedStruct<"AI.Error", {
-    readonly reason: Schema.toTaggedUnion<"_tag", readonly [typeof InvalidRequestError, typeof UnsupportedOperationError, typeof NoRouteError, typeof AuthenticationError, typeof RateLimitError, typeof QuotaExceededError, typeof ContentPolicyError, typeof ProviderInternalError, typeof TransportError, typeof InvalidProviderOutputError, typeof UnknownProviderError]>;
+    readonly reason: Schema.toTaggedUnion<"_tag", readonly [typeof InvalidRequestError, typeof UnsupportedOperationError, typeof NoRouteError, typeof AuthenticationError, typeof RateLimitError, typeof QuotaExceededError, typeof ContentPolicyError, typeof ProviderInternalError, typeof TransportError, typeof InvalidProviderOutputError, typeof UnknownProviderError, typeof TimeoutError]>;
 }>, import("effect/Cause").YieldableError>;
 export declare class AIError extends AIError_base {
-    readonly cause: InvalidRequestError | UnsupportedOperationError | NoRouteError | AuthenticationError | RateLimitError | QuotaExceededError | ContentPolicyError | ProviderInternalError | TransportError | InvalidProviderOutputError | UnknownProviderError;
+    readonly cause: InvalidRequestError | UnsupportedOperationError | NoRouteError | AuthenticationError | RateLimitError | QuotaExceededError | ContentPolicyError | ProviderInternalError | TransportError | InvalidProviderOutputError | UnknownProviderError | TimeoutError;
     get message(): string;
 }
 /**

package/dist/schema/errors.js

@@ -97,6 +97,12 @@ export class InvalidProviderOutputError extends Schema.TaggedError("AI.Error.Inv
 }
 export class UnknownProviderError extends Schema.TaggedError("AI.Error.UnknownProvider")("UnknownProvider", ReasonFields) {
 }
+/** A caller-supplied deadline elapsed, such as `Generation.await` polling past its `Poll.timeout`. */
+export class TimeoutError extends Schema.TaggedError("AI.Error.Timeout")("Timeout", {
+    ...ReasonFields,
+    timeoutMs: Schema.optional(Schema.Number),
+}) {
+}
 export const AIErrorReason = Schema.Union([
     InvalidRequestError,
     UnsupportedOperationError,
@@ -109,6 +115,7 @@ export const AIErrorReason = Schema.Union([
     TransportError,
     InvalidProviderOutputError,
     UnknownProviderError,
+    TimeoutError,
 ]).pipe(Schema.toTaggedUnion("_tag"));
 export class AIError extends Schema.TaggedError()("AI.Error", {
     reason: AIErrorReason,