@opencode/ai 2.0.15 → 2.0.17

package/dist/route/auth.d.ts

@@ -4,7 +4,7 @@ import { AIError, type HttpOptions } from "../schema/index.js";
 export declare class MissingCredentialError extends Error {
     readonly source: string;
     readonly _tag = "MissingCredentialError";
-    constructor(source: string);
+    constructor(source: string, message?: string);
 }
 export type CredentialError = MissingCredentialError | Config.ConfigError;
 export type AuthError = CredentialError | AIError;
@@ -13,7 +13,7 @@ export interface AuthInput {
     readonly request: {
         readonly http?: HttpOptions;
     };
-    readonly method: "POST" | "GET";
+    readonly method: "POST" | "GET" | "PUT" | "DELETE";
     readonly url: string;
     readonly body: string;
     readonly headers: Headers.Headers;
@@ -47,5 +47,8 @@ export declare function header(name: string): (source: Secret | Credential) => D
 export declare function header(name: string, source: Secret | Credential): Definition;
 export declare function bearerHeader(name: string): (source: Secret | Credential) => Definition;
 export declare function bearerHeader(name: string, source: Secret | Credential): Definition;
+/** `Authorization: <scheme> <secret>` for providers whose scheme is not `Bearer`, such as fal's `Key`. */
+export declare function scheme(name: string): (source: Secret | Credential) => Definition;
+export declare function scheme(name: string, source: Secret | Credential): Definition;
 export declare const toEffect: (input: Definition) => (authInput: AuthInput) => Effect.Effect<Headers.Headers, AIError>;
 export * as Auth from "./auth.js";

package/dist/route/auth.js

@@ -1,11 +1,11 @@
-import { Config, Effect, Redacted } from "effect";
+import { Config, Effect, Option, Redacted } from "effect";
 import { Headers } from "effect/unstable/http";
-import { AuthenticationError, InvalidRequestError, AIError } from "../schema/index.js";
+import { AuthenticationError, AIError } from "../schema/index.js";
 export class MissingCredentialError extends Error {
     source;
     _tag = "MissingCredentialError";
-    constructor(source) {
-        super(`Missing auth credential: ${source}`);
+    constructor(source, message = `Missing auth credential: ${source}`) {
+        super(message);
         this.source = source;
     }
 }
@@ -47,7 +47,12 @@ export const value = (secret, source = "value") => credentialFromSecret(secret,
 export const optional = (secret, source = "optional value") => secret === undefined
     ? credential(Effect.fail(new MissingCredentialError(source)))
     : credentialFromSecret(secret, source);
-export const config = (name) => credentialFromSecret(Config.redacted(name), name);
+export const config = (name) => credential(Effect.gen(function* () {
+    const secret = yield* Config.option(Config.redacted(name));
+    if (Option.isSome(secret) && Redacted.value(secret.value) !== "")
+        return secret.value;
+    return yield* Effect.fail(new MissingCredentialError(name, `${name} is not set`));
+}));
 export const effect = (load) => credential(load);
 export const none = auth((input) => Effect.succeed(input.headers));
 export const headers = (input) => auth((inputAuth) => Effect.succeed(Headers.setAll(inputAuth.headers, input)));
@@ -73,15 +78,17 @@ export function bearerHeader(name, source) {
         return render;
     return render(source);
 }
+export function scheme(name, source) {
+    const render = (input) => fromCredential(credentialInput(input), (secret) => ({ authorization: `${name} ${secret}` }));
+    if (source === undefined)
+        return render;
+    return render(source);
+}
 const toAIError = (error) => {
-    if (error instanceof MissingCredentialError || error instanceof Config.ConfigError) {
-        return new AIError({
-            reason: error instanceof MissingCredentialError
-                ? new AuthenticationError({ message: error.message, cause: error })
-                : new InvalidRequestError({ message: `Failed to resolve auth config: ${error.message}`, cause: error }),
-        });
-    }
-    return error;
+    if (error instanceof AIError)
+        return error;
+    const message = error instanceof MissingCredentialError ? error.message : `Failed to resolve auth config: ${error.message}`;
+    return new AIError({ reason: new AuthenticationError({ message, cause: error }) });
 };
 export const toEffect = (input) => (authInput) => input.apply(authInput).pipe(Effect.mapError(toAIError));
 export * as Auth from "./auth.js";

package/dist/route/client.d.ts

@@ -6,7 +6,7 @@ import { Framing } from "./framing.js";
 import { HttpTransport } from "./transport/index.js";
 import type { HttpMiddleware, Transport, TransportRuntime, WebSocketChannelExecutor } from "./transport/index.js";
 import type { Protocol } from "./protocol.js";
-import type { ProtocolID, ProviderOptions } from "../schema/index.js";
+import type { LanguageModelSanitizerCompatibility, ProtocolID, ProviderOptions } from "../schema/index.js";
 import { AIError, CompactionResponse, CompactionCheckpointResponse, GenerationOptions, HttpOptions, LLMRequest, LLMResponse, LanguageModel, LLMEvent, ProviderID } from "../schema/index.js";
 export interface RouteBody<Body> {
     /** Schema for the validated provider-native body sent as the JSON request. */
@@ -31,6 +31,7 @@ export interface Route<Body, Prepared = unknown, Compact extends CompactionOpera
     readonly defaults: RouteDefaults;
     readonly body: RouteBody<Body>;
     readonly supportsEffortUpdates?: (request: LLMRequest) => boolean;
+    readonly sanitizer?: LanguageModelSanitizerCompatibility;
     readonly with: {
         <Next extends CompactionOperations | undefined>(patch: RoutePatch<Body, Prepared> & {
             readonly compact: Next;
@@ -71,7 +72,6 @@ export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
 }
 type RouteMappedLanguageModelInput = RouteLanguageModelInput | RouteRoutedLanguageModelInput;
 export declare const generationOptions: (input: GenerationOptions.Input | undefined) => GenerationOptions | undefined;
-export declare const httpOptions: (input: HttpOptionsInput | undefined) => HttpOptions | undefined;
 export interface Interface {
     readonly compact: CompactMethod;
     readonly stream: StreamMethod;
@@ -121,9 +121,11 @@ export declare function canCompact(request: LLMRequest, options?: {
 export declare function canCompact(request: LLMRequest, options: {
     readonly mechanism: "trigger";
 }): request is CheckpointRequest;
-declare const Service_base: Context.ServiceClass<Service, "@opencode/LLMClient", Interface>;
-export declare class Service extends Service_base {
+declare const LLMClientService_base: Context.ServiceClass<LLMClientService, "@opencode/LLMClient", Interface>;
+export declare class LLMClientService extends LLMClientService_base {
 }
+export declare const Service: typeof LLMClientService;
+export type Service = LLMClientService;
 export interface MakeInput<Body, Frame, Event, State> {
     readonly compact?: CompactionOperations;
     /** Route id used in diagnostics and prepared request metadata. */
@@ -423,7 +425,7 @@ export declare const streamRequest: (request: LLMRequest, options?: StreamOption
             readonly [x: string]: unknown;
         };
     } | undefined;
-}, AIError, Service>;
+}, AIError, LLMClientService>;
 export declare const layer: Layer.Layer<Service, never, RequestExecutor.Service>;
 export declare const Route: {
     readonly make: typeof make;
@@ -431,8 +433,8 @@ export declare const Route: {
 export declare const LLMClient: {
     readonly canCompact: typeof canCompact;
     readonly compact: typeof compact;
-    readonly Service: typeof Service;
-    readonly layer: Layer.Layer<Service, never, RequestExecutor.Service>;
+    readonly Service: typeof LLMClientService;
+    readonly layer: Layer.Layer<LLMClientService, never, import("./executor-service.js").RequestExecutorService>;
     readonly stream: typeof stream;
     readonly generate: typeof generate;
 };

package/dist/route/client.js

@@ -9,6 +9,7 @@ import { applyEffortUpdates } from "../effort-updates.js";
 import { normalizeToolHistory } from "../tool-history.js";
 import { sanitizeSurrogates } from "../utils/sanitize.js";
 import * as ProviderShared from "../protocols/shared.js";
+import { ToolSchemaProjection } from "../protocols/utils/tool-schema.js";
 import { AIError, CompactionResponse, CompactionCheckpointResponse, AIErrorReason, GenerationOptions, HttpOptions, LLMRequest, LLMResponse, LanguageModel, LLMEvent, InvalidProviderOutputError, ProviderConfigurationError, ProviderID, mergeGenerationOptions, mergeHttpOptions, mergeProviderOptions, } from "../schema/index.js";
 const makeRouteLanguageModel = (route, mapped) => {
     const provider = route.provider ?? ("provider" in mapped ? mapped.provider : undefined);
@@ -33,7 +34,7 @@ const mergeRouteDefaults = (base, patch) => {
         headers,
         generation: mergeGenerationOptions(generationOptions(base?.generation), generationOptions(patch.generation)),
         providerOptions: mergeProviderOptions(base?.providerOptions, patch.providerOptions),
-        http: mergeHttpOptions(base?.http, httpOptions(patch.http), headers === undefined ? undefined : new HttpOptions({ headers })),
+        http: mergeHttpOptions(base?.http, HttpOptions.make(patch.http), headers === undefined ? undefined : new HttpOptions({ headers })),
     };
 };
 const endpointBaseURL = (endpoint) => typeof endpoint.baseURL === "string" ? endpoint.baseURL : undefined;
@@ -44,11 +45,6 @@ const mergeHeaders = (...items) => {
     return Object.fromEntries(entries);
 };
 export const generationOptions = (input) => input === undefined ? undefined : GenerationOptions.make(input);
-export const httpOptions = (input) => {
-    if (input === undefined)
-        return input;
-    return HttpOptions.make(input);
-};
 export function canCompact(request, options) {
     if (options?.mechanism === "trigger")
         return request.model.route.compact?.trigger !== undefined;
@@ -66,8 +62,9 @@ const unsupportedCompaction = (request, mechanism) => {
         message: `${request.model.provider}/${request.model.route.id} does not support ${mechanism === "trigger" ? "trigger" : "explicit"} compaction`,
     });
 };
-export class Service extends Context.Service()("@opencode/LLMClient") {
+export class LLMClientService extends Context.Service()("@opencode/LLMClient") {
 }
+export const Service = LLMClientService;
 const resolveRequestOptions = (request) => {
     const messages = normalizeToolHistory(request.messages);
     const normalized = messages === request.messages ? request : LLMRequest.update(request, { messages });
@@ -122,6 +119,7 @@ function makeFromTransport(input) {
             defaults: routeInput.defaults ?? {},
             body: protocol.body,
             supportsEffortUpdates: protocol.supportsEffortUpdates,
+            sanitizer: protocol.sanitizer,
             with: (patch) => {
                 const { compact, id, provider, providerMetadataKey, auth, transport, endpoint, ...defaults } = patch;
                 return build({
@@ -214,7 +212,7 @@ const prepareRequest = (request) => {
     const sanitized = LLMRequest.update(original, sanitizeSurrogates({ ...LLMRequest.input(original), model: undefined }));
     // Deduplicate per sibling level; a tool and a namespace may share a name.
     const dedupe = (tools) => [...new Map(tools.map((tool) => [`${tool.type}:${tool.name}`, tool])).values()].map((tool) => tool.type === "tool" ? tool : { ...tool, tools: dedupe(tool.tools) });
-    const resolved = applyCachePolicy(applyEffortUpdates(LLMRequest.update(sanitized, { tools: dedupe(sanitized.tools) })));
+    const resolved = applyCachePolicy(applyEffortUpdates(LLMRequest.update(sanitized, { tools: ToolSchemaProjection.tools(dedupe(sanitized.tools), sanitized.model) })));
     const headers = resolved.model.route.headers?.({ request: resolved });
     return headers === undefined
         ? resolved

package/dist/route/endpoint.d.ts

@@ -24,5 +24,6 @@ export type EndpointPatch<Body, Request = LLMRequest> = Partial<Definition<Body,
 /** Construct an `Endpoint` from a path string or path function. */
 export declare const path: <Body, Request = LLMRequest>(value: EndpointPart<Body, Request>, options?: Omit<Definition<Body, Request>, "path">) => Definition<Body, Request>;
 export declare const merge: <Body, Request = LLMRequest>(base: Definition<Body, Request>, patch: EndpointPatch<Body, Request>) => Definition<Body, Request>;
+export declare const trimBaseUrl: (value: string) => string;
 export declare const render: <Body, Request = LLMRequest>(endpoint: Definition<Body, Request>, input: EndpointInput<Body, Request>) => URL;
 export * as Endpoint from "./endpoint.js";

package/dist/route/endpoint.js

@@ -1,4 +1,3 @@
-import * as ProviderShared from "../protocols/shared.js";
 /** Construct an `Endpoint` from a path string or path function. */
 export const path = (value, options = {}) => ({
     ...options,
@@ -11,9 +10,10 @@ export const merge = (base, patch) => ({
     path: patch.path ?? base.path,
     query: patch.query === undefined ? base.query : { ...base.query, ...patch.query },
 });
+export const trimBaseUrl = (value) => value.replace(/\/+$/, "");
 const renderPart = (part, input) => typeof part === "function" ? part(input) : part;
 export const render = (endpoint, input) => {
-    const url = new URL(`${ProviderShared.trimBaseUrl(endpoint.baseURL ?? "")}${renderPart(endpoint.path, input)}`);
+    const url = new URL(`${trimBaseUrl(endpoint.baseURL ?? "")}${renderPart(endpoint.path, input)}`);
     for (const [key, value] of Object.entries(endpoint.query ?? {}))
         url.searchParams.set(key, value);
     return url;

package/dist/route/executor-service.d.ts

@@ -6,7 +6,9 @@ export interface Interface {
 }
 export type HttpHandler = (request: HttpClientRequest.HttpClientRequest) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error>;
 export type HttpMiddleware = (request: HttpClientRequest.HttpClientRequest, handler: HttpHandler) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error>;
-declare const Service_base: Context.ServiceClass<Service, "@opencode/AI/RequestExecutor", Interface>;
-export declare class Service extends Service_base {
+declare const RequestExecutorService_base: Context.ServiceClass<RequestExecutorService, "@opencode/AI/RequestExecutor", Interface>;
+export declare class RequestExecutorService extends RequestExecutorService_base {
 }
+export declare const Service: typeof RequestExecutorService;
+export type Service = RequestExecutorService;
 export {};

package/dist/route/executor-service.js

@@ -1,3 +1,4 @@
 import { Context } from "effect";
-export class Service extends Context.Service()("@opencode/AI/RequestExecutor") {
+export class RequestExecutorService extends Context.Service()("@opencode/AI/RequestExecutor") {
 }
+export const Service = RequestExecutorService;

package/dist/route/executor.d.ts

@@ -18,5 +18,7 @@ export declare const httpFailure: (input: {
 export declare const responseStream: (response: HttpClientResponse.HttpClientResponse) => Stream.Stream<Uint8Array, AIError>;
 export declare const stream: (executor: Interface, request: HttpClientRequest.HttpClientRequest, middleware?: HttpMiddleware) => Stream.Stream<Uint8Array, AIError>;
 export declare const layer: Layer.Layer<Service, never, HttpClient.HttpClient>;
-export declare const fetchLayer: Layer.Layer<Service, never, never>;
+export declare const fetchLayer: Layer.Layer<import("./executor-service.js").RequestExecutorService, never, never>;
+/** Run `fn` on every request: it sees the raw response before status classification, inside middleware already on `executor`, and outside per-call middleware. */
+export declare const middleware: (fn: HttpMiddleware, executor?: Layer.Layer<Service>) => Layer.Layer<Service>;
 export * as RequestExecutor from "./executor.js";

package/dist/route/executor.js

@@ -180,4 +180,11 @@ export const layer = Layer.effect(Service, Effect.gen(function* () {
     });
 }));
 export const fetchLayer = layer.pipe(Layer.provide(FetchHttpClient.layer));
+/** Run `fn` on every request: it sees the raw response before status classification, inside middleware already on `executor`, and outside per-call middleware. */
+export const middleware = (fn, executor = fetchLayer) => Layer.effect(Service, Effect.gen(function* () {
+    const inner = yield* Service;
+    return Service.of({
+        execute: (request, next) => inner.execute(request, next === undefined ? fn : (input, handler) => fn(input, (forwarded) => next(forwarded, handler))),
+    });
+})).pipe(Layer.provide(executor));
 export * as RequestExecutor from "./executor.js";

package/dist/route/framing.d.ts

@@ -1,5 +1,5 @@
-import type { Stream } from "effect";
-import type { AIError } from "../schema/index.js";
+import { Stream } from "effect";
+import { AIError } from "../schema/index.js";
 /**
  * Decode a streaming HTTP response body into provider-protocol frames.
  *
@@ -10,6 +10,8 @@ import type { AIError } from "../schema/index.js";
  *   `[DONE]`; protocols that use it as a terminal select `sseWithDone`.
  * - AWS event stream — length-prefixed binary frames with CRC checksums.
  *   Each emitted frame is one parsed binary event record.
+ * - Media streams — newline-delimited JSON (`lines`) or the whole body as one
+ *   frame (`document`); chunked binary bodies need no framing.
  *
  * The frame type is opaque to this layer; the protocol's event schema decodes
  * each frame before its state machine handles it.
@@ -20,10 +22,21 @@ export interface Definition<Frame> {
     /** Original wire representation when framing transforms the provider payload. */
     readonly body?: (frame: Frame) => string | undefined;
 }
+/**
+ * `framing` step for Server-Sent Events. Decodes UTF-8, runs the SSE channel
+ * decoder, optionally filters named events, and drops empty events and known
+ * keepalives that proxies send as data. `[DONE]` is dropped by default or
+ * retained for protocols that use it as their stream boundary. Retry control events are ignored without
+ * interrupting the stream. Decoder failures become provider output errors so
+ * the public error channel stays `AIError`.
+ */
+export declare const sseFraming: (bytes: Stream.Stream<Uint8Array, AIError>, events?: ReadonlySet<string>, includeDone?: boolean) => Stream.Stream<string, AIError>;
 /** Server-Sent Events framing. Used by every JSON-streaming HTTP provider. */
 export declare const sse: Definition<string>;
 /** Server-Sent Events framing that retains the conventional `[DONE]` sentinel. */
 export declare const sseWithDone: Definition<string>;
 /** SSE framing restricted to protocol-recognized event names. */
 export declare const sseEvents: (events: ReadonlySet<string>) => Definition<string>;
+export declare const lines: Definition<string>;
+export declare const document: Definition<string>;
 export * as Framing from "./framing.js";

package/dist/route/framing.js

@@ -1,14 +1,63 @@
-import * as ProviderShared from "../protocols/shared.js";
+import { Effect, Stream } from "effect";
+import { makeParser } from "effect/unstable/encoding/Sse";
+import { AIError, InvalidProviderOutputError } from "../schema/index.js";
+/**
+ * `framing` step for Server-Sent Events. Decodes UTF-8, runs the SSE channel
+ * decoder, optionally filters named events, and drops empty events and known
+ * keepalives that proxies send as data. `[DONE]` is dropped by default or
+ * retained for protocols that use it as their stream boundary. Retry control events are ignored without
+ * interrupting the stream. Decoder failures become provider output errors so
+ * the public error channel stays `AIError`.
+ */
+export const sseFraming = (bytes, events, includeDone = false) => bytes.pipe(Stream.decodeText(), Stream.mapAccumEffect(() => {
+    const output = [];
+    return {
+        output,
+        parser: makeParser((event) => {
+            if (event._tag === "Event")
+                output.push(event);
+        }),
+    };
+}, (state, chunk) => Effect.gen(function* () {
+    const error = state.parser.feed(chunk);
+    if (error)
+        return yield* new AIError({
+            reason: new InvalidProviderOutputError({
+                route: "sse",
+                message: error.message,
+                body: chunk,
+                cause: error,
+            }),
+        });
+    return [state, state.output.splice(0)];
+})), Stream.filter((event) => (events === undefined || events.has(event.event)) &&
+    event.data.length > 0 &&
+    // Some OpenAI-compatible proxies serialize an empty flush as a bare
+    // `data: null`, between events or after `[DONE]`. No protocol has a
+    // null event, so it carries nothing and must not abort the stream.
+    event.data !== "null" &&
+    // Vertex AI partner models (e.g. `xai/grok-4.6`) send their SSE
+    // keepalive comment as `data: : keepalive` while reasoning.
+    event.data !== ": keepalive" &&
+    (event.data !== "[DONE]" || includeDone || (events !== undefined && event.event !== "message"))), Stream.map((event) => event.data));
 /** Server-Sent Events framing. Used by every JSON-streaming HTTP provider. */
-export const sse = { id: "sse", frame: ProviderShared.sseFraming };
+export const sse = { id: "sse", frame: sseFraming };
 /** Server-Sent Events framing that retains the conventional `[DONE]` sentinel. */
 export const sseWithDone = {
     id: "sse",
-    frame: (bytes) => ProviderShared.sseFraming(bytes, undefined, true),
+    frame: (bytes) => sseFraming(bytes, undefined, true),
 };
 /** SSE framing restricted to protocol-recognized event names. */
 export const sseEvents = (events) => ({
     id: "sse",
-    frame: (bytes) => ProviderShared.sseFraming(bytes, events),
+    frame: (bytes) => sseFraming(bytes, events),
 });
+export const lines = {
+    id: "lines",
+    frame: (bytes) => bytes.pipe(Stream.decodeText(), Stream.splitLines, Stream.filter((line) => line.trim().length > 0)),
+};
+export const document = {
+    id: "document",
+    frame: (bytes) => Stream.fromEffect(Stream.mkString(bytes.pipe(Stream.decodeText()))),
+};
 export * as Framing from "./framing.js";

package/dist/route/index.d.ts

@@ -1,5 +1,5 @@
 export { Route, LLMClient } from "./client.js";
-export type { Route as RouteShape, RouteLanguageModelInput, RouteRoutedLanguageModelInput, RouteDefaults, RouteDefaultsInput, AnyRoute, Interface as LLMClientShape, Service as LLMClientService, StreamOptions, CompactMethod, CompactionOperations, CompactionRequest, CheckpointRequest, EndpointCompactOptions, TriggerCompactOptions, } from "./client.js";
+export type { Route as RouteShape, RouteLanguageModelInput, RouteRoutedLanguageModelInput, RouteDefaults, RouteDefaultsInput, AnyRoute, Interface as LLMClientShape, LLMClientService, StreamOptions, CompactMethod, CompactionOperations, CompactionRequest, CheckpointRequest, EndpointCompactOptions, TriggerCompactOptions, } from "./client.js";
 export * from "./executor.js";
 export { Auth } from "./auth.js";
 export { AuthOptions } from "./auth-options.js";

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

@@ -1,15 +1,31 @@
-import { Effect, Schema } from "effect";
+import { Duration, Effect, Schema, type Stream } from "effect";
 import { HttpClientResponse } from "effect/unstable/http";
-import { AIError, HttpContext } from "../schema/index.js";
+import type { Snapshot, Status } from "../generation.js";
+import { Media } from "../media.js";
+import type { AuthInput } from "./auth.js";
+import { AIError, HttpContext, ProviderID } 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>) => Body;
+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;
@@ -18,7 +34,7 @@ export interface DecodeContext<Request> {
 export interface Inline<Request, Response> {
     readonly kind: "inline";
     readonly id: string;
-    readonly name: string;
+    readonly provider: ProviderID;
     /** Common request fields this protocol cannot lower; the route rejects them before `body.from` runs. */
     readonly unsupported?: ReadonlyArray<keyof Request & string>;
     readonly body: {
@@ -28,18 +44,129 @@ export interface Inline<Request, 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>;
-/** Read a text body while retaining the original payload and HTTP context on every downstream error. */
-export declare const text: (route: string, name: string, response: HttpClientResponse.HttpClientResponse) => Effect.Effect<{
-    body: string;
-    http: HttpContext;
-    invalid: (message: string, cause?: unknown) => AIError;
-}, AIError, never>;
-/** 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;
-}, AIError, never>;
+export declare const inline: <Request, Response>(route: Identity, input: Omit<Inline<Request, Response>, "kind" | "id" | "provider">) => 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 provider: ProviderID;
+    /** 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;
+        /**
+         * Fetch a fresh status first and skip the call for terminal generations, for providers whose cancel endpoint
+         * destroys finished work (Runway's `DELETE /v1/tasks/{id}` deletes completed tasks and their outputs).
+         */
+        readonly activeOnly?: boolean;
+    };
+}
+export declare const queued: <Request, Response, Token>(route: Identity, input: Omit<Queued<Request, Response, Token>, "kind" | "id" | "provider">) => 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 provider: ProviderID;
+    /** 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>(route: Identity, input: Omit<Streamed<Request, Event, Frame, State>, "kind" | "id" | "provider">) => Streamed<Request, Event, Frame, State>;
+/** One protocol's route id, display name, and provider, with the decoders and errors that carry them. */
+export declare const identity: (input: {
+    readonly id: string;
+    readonly name: string;
+    readonly provider: string;
+}) => {
+    id: string;
+    name: string;
+    provider: string & import("effect/Brand").Brand<"AI.ProviderID">;
+    text: (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;
+        pending: (id: string) => AIError;
+        contentPolicy: (message: string) => AIError;
+    }, AIError, never>;
+    decodeJson: <A>(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;
+        pending: (id: string) => AIError;
+        contentPolicy: (message: string) => AIError;
+    }, AIError, never>;
+    /** Decode a submission response into the token and first snapshot. */
+    decodeStarted: <A, Token>(schema: Schema.Codec<A, unknown>, started: (value: A) => Started<Token>) => (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<Started<Token>, AIError, never>;
+    /** Schema-decode one JSON stream frame. Decode failures keep the frame as `reason.body`. */
+    decodeFrame: <A>(schema: Schema.Codec<A, unknown>) => (frame: string) => Effect.Effect<A, AIError, never>;
+    /** A stream-time failure; the frame stays on `reason.body`. */
+    frameError: (message: string, body?: string, cause?: unknown) => AIError;
+    incomplete: () => AIError;
+    unsupported: (operation: string, message: string) => AIError;
+};
+export type Identity = ReturnType<typeof identity>;
+export type Output = Effect.Success<ReturnType<Identity["text"]>>;
+/** 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>;
+/** 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";