@opencode/ai 0.0.0-reserved → 2.0.0

package/dist/route/transport/websocket.js

@@ -0,0 +1,370 @@
+import { Cause, Effect, Queue, Stream } from "effect";
+import { Headers } from "effect/unstable/http";
+import { Socket } from "effect/unstable/socket";
+import { AIError, AIErrorReason, TransportError, } from "../../schema/index.js";
+import * as HttpTransport from "./http.js";
+const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+const transportError = (message, input) => new AIError({
+    reason: new TransportError({
+        message,
+        body: input.body,
+        cause: input.cause,
+        transport: "websocket",
+        operation: input.operation,
+        url: input.url,
+        code: input.code,
+        phase: input.phase,
+        delivery: input.delivery,
+    }),
+});
+const annotateTransportError = (error, input) => error.reason._tag === "Transport"
+    ? new AIError({
+        reason: new TransportError({
+            ...error.reason,
+            message: error.reason.message,
+            cause: error.reason.cause,
+            phase: input.phase,
+            delivery: input.delivery,
+        }),
+    })
+    : error;
+const eventMessage = (event) => {
+    if ("message" in event && typeof event.message === "string")
+        return event.message;
+    return event.type;
+};
+const binaryMessage = (data) => {
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return undefined;
+};
+const waitOpen = (ws, input) => {
+    if (ws.readyState === globalThis.WebSocket.OPEN)
+        return Effect.void;
+    if (ws.readyState === globalThis.WebSocket.CLOSING || ws.readyState === globalThis.WebSocket.CLOSED) {
+        return Effect.fail(transportError(`WebSocket closed before opening (state ${ws.readyState})`, {
+            url: input.url,
+            operation: "request",
+            code: "closed",
+            phase: "connect",
+            delivery: "not-sent",
+        }));
+    }
+    return Effect.callback((resume, signal) => {
+        const cleanup = () => {
+            ws.removeEventListener("open", onOpen);
+            ws.removeEventListener("error", onError);
+            ws.removeEventListener("close", onClose);
+            signal.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            if (ws.readyState === globalThis.WebSocket.CLOSED || ws.readyState === globalThis.WebSocket.CLOSING)
+                return;
+            // Node's ws reports an aborted handshake as an error event on the next tick; with no listener left
+            // after cleanup, EventEmitter would throw it as an uncaught exception.
+            ws.addEventListener("error", () => { }, { once: true });
+            ws.close(1000);
+        };
+        const onOpen = () => {
+            cleanup();
+            resume(Effect.void);
+        };
+        const onError = (event) => {
+            cleanup();
+            resume(Effect.fail(transportError(`Failed to open WebSocket: ${eventMessage(event)}`, {
+                cause: "error" in event ? (event.error ?? event) : event,
+                url: input.url,
+                operation: "request",
+                phase: "connect",
+                delivery: "not-sent",
+            })));
+        };
+        const onClose = (event) => {
+            cleanup();
+            resume(Effect.fail(transportError(`WebSocket closed before opening with code ${event.code}`, {
+                body: event.reason,
+                cause: event,
+                url: input.url,
+                operation: "request",
+                code: String(event.code),
+                phase: "connect",
+                delivery: "not-sent",
+            })));
+        };
+        ws.addEventListener("open", onOpen, { once: true });
+        ws.addEventListener("error", onError, { once: true });
+        ws.addEventListener("close", onClose, { once: true });
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+};
+export const toWebSocketUrl = (value) => Effect.try({
+    try: () => {
+        const url = new URL(value);
+        if (url.protocol === "https:") {
+            url.protocol = "wss:";
+            return url.toString();
+        }
+        if (url.protocol === "http:") {
+            url.protocol = "ws:";
+            return url.toString();
+        }
+        throw new Error(`Unsupported WebSocket URL protocol ${url.protocol}`);
+    },
+    catch: (error) => transportError(error instanceof Error ? error.message : "Invalid WebSocket URL", {
+        cause: error,
+        url: value,
+        operation: "request",
+        code: "invalid-url",
+        phase: "prepare",
+        delivery: "not-sent",
+    }),
+});
+export const open = (input) => Effect.gen(function* () {
+    const constructor = yield* Socket.WebSocketConstructor;
+    const ws = yield* Effect.try({
+        try: () => 
+        // Platform implementations may extend Effect's browser-compatible constructor with handshake options.
+        // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+        constructor(input.url, {
+            headers: input.headers,
+        }),
+        catch: (error) => transportError(error instanceof Error ? error.message : "Failed to construct WebSocket", {
+            cause: error,
+            url: input.url,
+            operation: "request",
+            phase: "connect",
+            delivery: "not-sent",
+        }),
+    });
+    return yield* fromWebSocket(ws, input);
+});
+export const fromWebSocket = (ws, input) => Effect.gen(function* () {
+    yield* waitOpen(ws, input);
+    const messages = yield* Queue.bounded(128);
+    const oversized = (message) => typeof message === "string" ? new Blob([message]).size > MAX_FRAME_BYTES : message.byteLength > MAX_FRAME_BYTES;
+    const rejectOversized = (message) => {
+        if (!oversized(message))
+            return false;
+        Queue.failCauseUnsafe(messages, Cause.fail(transportError("WebSocket message exceeds the 16 MiB limit", {
+            body: typeof message === "string" ? message : new TextDecoder().decode(message),
+            url: input.url,
+            operation: "read",
+            code: "message-too-large",
+            phase: "receive",
+        })));
+        if (ws.readyState === globalThis.WebSocket.OPEN)
+            ws.close(1009, "Message too large");
+        return true;
+    };
+    const offer = (message) => {
+        if (rejectOversized(message))
+            return;
+        if (Queue.offerUnsafe(messages, message))
+            return;
+        Queue.failCauseUnsafe(messages, Cause.fail(transportError("WebSocket inbound queue overflow", {
+            body: typeof message === "string" ? message : new TextDecoder().decode(message),
+            url: input.url,
+            operation: "read",
+            code: "queue-overflow",
+            phase: "receive",
+        })));
+    };
+    const onMessage = (event) => {
+        if (typeof event.data === "string")
+            return offer(event.data);
+        const binary = binaryMessage(event.data);
+        if (binary)
+            return offer(binary);
+        Queue.failCauseUnsafe(messages, Cause.fail(transportError("Unsupported WebSocket message payload", {
+            cause: event,
+            url: input.url,
+            operation: "read",
+            code: "message",
+            phase: "receive",
+        })));
+    };
+    const onError = (event) => {
+        Queue.failCauseUnsafe(messages, Cause.fail(transportError(`WebSocket error: ${eventMessage(event)}`, {
+            cause: "error" in event ? (event.error ?? event) : event,
+            url: input.url,
+            operation: "read",
+            code: "message",
+            phase: "receive",
+        })));
+    };
+    const onClose = (event) => {
+        Queue.failCauseUnsafe(messages, Cause.fail(transportError(`WebSocket closed with code ${event.code}`, {
+            body: event.reason,
+            cause: event,
+            url: input.url,
+            operation: "read",
+            code: String(event.code),
+            phase: "close",
+        })));
+    };
+    const cleanup = Effect.sync(() => {
+        ws.removeEventListener("message", onMessage);
+        ws.removeEventListener("error", onError);
+        ws.removeEventListener("close", onClose);
+    }).pipe(Effect.andThen(Queue.shutdown(messages)));
+    ws.addEventListener("message", onMessage);
+    ws.addEventListener("error", onError);
+    ws.addEventListener("close", onClose);
+    return {
+        sendText: (message) => Effect.suspend(() => {
+            if (ws.readyState !== globalThis.WebSocket.OPEN)
+                return Effect.fail(transportError(`WebSocket is not open (state ${ws.readyState})`, {
+                    url: input.url,
+                    operation: "write",
+                    phase: "send",
+                    delivery: "not-sent",
+                }));
+            return Effect.try({
+                try: () => ws.send(message),
+                catch: (error) => transportError(error instanceof Error ? error.message : "Failed to send WebSocket message", {
+                    cause: error,
+                    url: input.url,
+                    operation: "write",
+                    phase: "send",
+                    delivery: "not-sent",
+                }),
+            });
+        }),
+        messages: Stream.fromQueue(messages),
+        close: cleanup.pipe(Effect.andThen(Effect.sync(() => {
+            if (ws.readyState === globalThis.WebSocket.CLOSED || ws.readyState === globalThis.WebSocket.CLOSING)
+                return;
+            ws.close(1000);
+        }))),
+    };
+});
+export const messageText = (message, decoder) => typeof message === "string" ? message : decoder.decode(message);
+const observationFrame = (observation) => {
+    if (observation.type === "frame" || observation.type === "completed" || observation.type === "incomplete")
+        return Effect.succeed(observation.frame);
+    return Effect.fail(observation.error);
+};
+const observationTerminal = (observation) => observation.type !== "frame";
+export const makeDirect = (connector) => ({
+    execute: (exchange) => Effect.gen(function* () {
+        const connection = yield* Effect.acquireRelease(connector
+            .open(exchange.connect)
+            .pipe(Effect.mapError((error) => annotateTransportError(error, { phase: "connect", delivery: "not-sent" }))), (connection) => connection.close);
+        const create = yield* exchange.driver.create(undefined);
+        yield* connection.sendText(create.message).pipe(Effect.mapError((error) => new AIError({
+            reason: AIErrorReason.make({
+                ...error.reason,
+                message: error.reason.message,
+                cause: error.reason.cause,
+                http: error.reason.http ?? connection.http,
+            }),
+        })));
+        const decoder = new TextDecoder();
+        let observed = false;
+        return {
+            http: connection.http,
+            frames: connection.messages.pipe(Stream.map((message) => {
+                observed = true;
+                return messageText(message, decoder);
+            }), Stream.mapError((error) => annotateTransportError(error, {
+                phase: error.reason._tag === "Transport" && error.reason.phase === "close" ? "close" : "receive",
+                delivery: observed ? "accepted" : "ambiguous",
+            })), Stream.mapEffect((frame) => exchange.driver.observe(create, frame).pipe(Effect.mapError((error) => new AIError({
+                reason: AIErrorReason.make({
+                    ...error.reason,
+                    message: error.reason.message,
+                    cause: error.reason.cause,
+                    body: frame,
+                }),
+            })), Effect.map((observation) => "error" in observation
+                ? {
+                    ...observation,
+                    error: new AIError({
+                        reason: AIErrorReason.make({
+                            ...observation.error.reason,
+                            message: observation.error.reason.message,
+                            cause: observation.error.reason.cause,
+                            body: frame,
+                        }),
+                    }),
+                }
+                : observation))), Stream.takeUntil(observationTerminal), Stream.mapEffect(observationFrame), Stream.mapError((error) => new AIError({
+                reason: AIErrorReason.make({
+                    ...error.reason,
+                    message: error.reason.message,
+                    cause: error.reason.cause,
+                    http: error.reason.http ?? connection.http,
+                }),
+            }))),
+            complete: Effect.void,
+        };
+    }),
+});
+export const direct = Effect.gen(function* () {
+    const constructor = yield* Socket.WebSocketConstructor;
+    return makeDirect({
+        open: (input) => open(input).pipe(Effect.provideService(Socket.WebSocketConstructor, constructor)),
+    });
+});
+export const json = (input) => ({
+    id: "websocket-json",
+    with: (patch) => json({ ...input, ...patch }),
+    prepare: (prepareInput) => Effect.gen(function* () {
+        const parts = yield* HttpTransport.jsonRequestParts({
+            ...prepareInput,
+        });
+        return {
+            url: yield* toWebSocketUrl(parts.url),
+            headers: parts.headers,
+            message: input.encodeMessage(yield* input.toMessage(parts.jsonBody)),
+        };
+    }),
+    execute: (prepared, request, _runtime, options) => {
+        const webSocket = options?.webSocket;
+        if (!webSocket) {
+            return Effect.fail(transportError("WebSocket JSON transport requires StreamOptions.webSocket", {
+                url: prepared.url,
+                operation: "request",
+                code: "unavailable",
+                phase: "prepare",
+                delivery: "not-sent",
+            }));
+        }
+        const driver = {
+            create: () => Effect.succeed({ message: prepared.message, mode: "full" }),
+            observe: (_create, frame) => Effect.succeed({ type: "frame", frame }),
+        };
+        const exchange = {
+            id: request.id ?? "request",
+            connect: { url: prepared.url, headers: prepared.headers },
+            fallback: () => Stream.fail(transportError("WebSocket JSON transport does not provide HTTP fallback", {
+                url: prepared.url,
+                operation: "request",
+                code: "websocket",
+                phase: "fallback",
+                delivery: "not-sent",
+            })),
+            driver,
+        };
+        return webSocket.execute(exchange);
+    },
+});
+export const jsonTransport = {
+    id: "websocket-json",
+    with: json,
+};
+export const WebSocketTransport = {
+    json,
+    jsonTransport,
+    direct,
+    makeDirect,
+    open,
+    fromWebSocket,
+    messageText,
+    toWebSocketUrl,
+};

package/dist/route.d.ts

@@ -0,0 +1 @@
+export * from "./route/index.js";

package/dist/route.js

@@ -0,0 +1 @@
+export * from "./route/index.js";

package/dist/schema/errors.d.ts

@@ -0,0 +1,170 @@
+import { Schema } from "effect";
+import { Tool } from "@opencode/schema/tool";
+export declare const ProviderFailureClassification: Schema.Literals<readonly ["context-overflow", "payload-too-large"]>;
+export type ProviderFailureClassification = typeof ProviderFailureClassification.Type;
+declare const HttpContext_base: Schema.Class<HttpContext, Schema.Struct<{
+    readonly url: Schema.String;
+    readonly status: Schema.Int;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+export declare class HttpContext extends HttpContext_base {
+}
+declare const HttpRateLimitDetails_base: Schema.Class<HttpRateLimitDetails, Schema.Struct<{
+    readonly retryAfterMs: Schema.optional<Schema.Number>;
+    readonly limit: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly remaining: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly reset: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+}>, {}>;
+export declare class HttpRateLimitDetails extends HttpRateLimitDetails_base {
+}
+declare const InvalidRequestError_base: Schema.Class<InvalidRequestError, Schema.TaggedStruct<"InvalidRequest", {
+    readonly parameter: Schema.optional<Schema.String>;
+    readonly classification: Schema.optional<Schema.Literals<readonly ["context-overflow", "payload-too-large"]>>;
+    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>;
+export declare class InvalidRequestError extends InvalidRequestError_base {
+}
+declare const UnsupportedOperationError_base: Schema.Class<UnsupportedOperationError, Schema.TaggedStruct<"UnsupportedOperation", {
+    readonly operation: Schema.String;
+    readonly provider: Schema.optional<Schema.brand<Schema.String, "AI.ProviderID">>;
+    readonly route: Schema.optional<Schema.String>;
+    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-requested operation the selected route does not implement, such as
+ * explicit compaction on a route without a compact endpoint. Detected locally
+ * before any network I/O, so unlike transport or provider-output failures it
+ * never carries HTTP context from a provider round-trip.
+ */
+export declare class UnsupportedOperationError extends UnsupportedOperationError_base {
+}
+declare const ProviderConfigurationError_base: Schema.Class<ProviderConfigurationError, Schema.TaggedStruct<"ProviderConfiguration", {
+    readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Provider settings that are missing, conflicting, or unsupported, such as
+ * Azure without `resourceName` or `baseURL`. Thrown synchronously while a
+ * provider facade or package entrypoint configures a model, before any
+ * request exists, so it is not an `AIError` reason.
+ */
+export declare class ProviderConfigurationError extends ProviderConfigurationError_base {
+}
+declare const NoRouteError_base: Schema.Class<NoRouteError, Schema.TaggedStruct<"NoRoute", {
+    readonly route: Schema.String;
+    readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
+    readonly model: Schema.brand<Schema.String, "AI.ModelID">;
+    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>;
+export declare class NoRouteError extends NoRouteError_base {
+}
+declare const AuthenticationError_base: Schema.Class<AuthenticationError, Schema.TaggedStruct<"Authentication", {
+    message: Schema.String;
+    body: Schema.optional<Schema.String>;
+    http: Schema.optional<typeof HttpContext>;
+    cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class AuthenticationError extends AuthenticationError_base {
+}
+declare const RateLimitError_base: Schema.Class<RateLimitError, Schema.TaggedStruct<"RateLimit", {
+    readonly retryAfterMs: Schema.optional<Schema.Number>;
+    readonly rateLimit: Schema.optional<typeof HttpRateLimitDetails>;
+    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>;
+export declare class RateLimitError extends RateLimitError_base {
+}
+declare const QuotaExceededError_base: Schema.Class<QuotaExceededError, Schema.TaggedStruct<"QuotaExceeded", {
+    message: Schema.String;
+    body: Schema.optional<Schema.String>;
+    http: Schema.optional<typeof HttpContext>;
+    cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class QuotaExceededError extends QuotaExceededError_base {
+}
+declare const ContentPolicyError_base: Schema.Class<ContentPolicyError, Schema.TaggedStruct<"ContentPolicy", {
+    message: Schema.String;
+    body: Schema.optional<Schema.String>;
+    http: Schema.optional<typeof HttpContext>;
+    cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ContentPolicyError extends ContentPolicyError_base {
+}
+declare const ProviderInternalError_base: Schema.Class<ProviderInternalError, Schema.TaggedStruct<"ProviderInternal", {
+    readonly retryAfterMs: 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>;
+export declare class ProviderInternalError extends ProviderInternalError_base {
+}
+export declare const TransportType: Schema.Literals<readonly ["http", "websocket"]>;
+export type TransportType = typeof TransportType.Type;
+export declare const TransportOperation: Schema.Literals<readonly ["request", "read", "write"]>;
+export type TransportOperation = typeof TransportOperation.Type;
+declare const TransportError_base: Schema.Class<TransportError, Schema.TaggedStruct<"Transport", {
+    readonly transport: Schema.Literals<readonly ["http", "websocket"]>;
+    readonly operation: Schema.Literals<readonly ["request", "read", "write"]>;
+    readonly code: Schema.optional<Schema.String>;
+    readonly url: Schema.optional<Schema.String>;
+    readonly phase: Schema.optional<Schema.Literals<readonly ["prepare", "queue", "connect", "send", "receive", "decode", "complete", "fallback", "close"]>>;
+    readonly delivery: Schema.optional<Schema.Literals<readonly ["not-sent", "rejected", "ambiguous", "accepted"]>>;
+    readonly recovery: Schema.optional<Schema.Literals<readonly ["retry-connect", "retry-full", "rotate-and-retry-full", "fallback-http", "fail"]>>;
+    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>;
+export declare class TransportError extends TransportError_base {
+}
+declare const InvalidProviderOutputError_base: Schema.Class<InvalidProviderOutputError, Schema.TaggedStruct<"InvalidProviderOutput", {
+    readonly classification: Schema.optional<Schema.Literals<readonly ["incomplete-stream"]>>;
+    readonly route: Schema.optional<Schema.String>;
+    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>;
+export declare class InvalidProviderOutputError extends InvalidProviderOutputError_base {
+}
+declare const UnknownProviderError_base: Schema.Class<UnknownProviderError, Schema.TaggedStruct<"UnknownProvider", {
+    message: Schema.String;
+    body: Schema.optional<Schema.String>;
+    http: Schema.optional<typeof HttpContext>;
+    cause: Schema.optional<Schema.Defect>;
+}>, 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]>;
+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]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class AIError extends AIError_base {
+    readonly cause: InvalidRequestError | UnsupportedOperationError | NoRouteError | AuthenticationError | RateLimitError | QuotaExceededError | ContentPolicyError | ProviderInternalError | TransportError | InvalidProviderOutputError | UnknownProviderError;
+    get message(): string;
+}
+/**
+ * Failure type for tool execute handlers. Handlers must map their internal
+ * errors to this shape; the runtime catches `ToolFailure`s and surfaces them
+ * as `tool-error` events plus a `tool-result` of `type: "error"` so the model
+ * can self-correct.
+ *
+ * Anything thrown or yielded by a handler that is not a `ToolFailure` is
+ * treated as a defect and fails the stream.
+ */
+export declare class ToolFailure extends Tool.Error {
+}
+export {};

package/dist/schema/errors.js

@@ -0,0 +1,131 @@
+import { Schema } from "effect";
+import { Tool } from "@opencode/schema/tool";
+import { ModelID, ProviderID, RouteID } from "./ids.js";
+export const ProviderFailureClassification = Schema.Literals(["context-overflow", "payload-too-large"]);
+export class HttpContext extends Schema.Class("AI.HttpContext")({
+    url: Schema.String,
+    status: Schema.Int.check(Schema.isBetween({ minimum: 100, maximum: 599 })),
+    headers: Schema.Record(Schema.String, Schema.String),
+}) {
+}
+export class HttpRateLimitDetails extends Schema.Class("AI.HttpRateLimitDetails")({
+    retryAfterMs: Schema.optional(Schema.Number),
+    limit: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    remaining: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    reset: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+}) {
+}
+const ReasonFields = {
+    message: Schema.String,
+    // Preserve the complete original response or triggering event before decoding narrows it.
+    body: Schema.optional(Schema.String),
+    http: Schema.optional(HttpContext),
+    cause: Schema.optional(Schema.Defect({ includeStack: true })),
+};
+export class InvalidRequestError extends Schema.TaggedError("AI.Error.InvalidRequest")("InvalidRequest", {
+    ...ReasonFields,
+    parameter: Schema.optional(Schema.String),
+    classification: Schema.optional(ProviderFailureClassification),
+}) {
+}
+/**
+ * A caller-requested operation the selected route does not implement, such as
+ * explicit compaction on a route without a compact endpoint. Detected locally
+ * before any network I/O, so unlike transport or provider-output failures it
+ * never carries HTTP context from a provider round-trip.
+ */
+export class UnsupportedOperationError extends Schema.TaggedError("AI.Error.UnsupportedOperation")("UnsupportedOperation", {
+    ...ReasonFields,
+    operation: Schema.String,
+    provider: Schema.optional(ProviderID),
+    route: Schema.optional(RouteID),
+}) {
+}
+/**
+ * Provider settings that are missing, conflicting, or unsupported, such as
+ * Azure without `resourceName` or `baseURL`. Thrown synchronously while a
+ * provider facade or package entrypoint configures a model, before any
+ * request exists, so it is not an `AIError` reason.
+ */
+export class ProviderConfigurationError extends Schema.TaggedError("AI.Error.ProviderConfiguration")("ProviderConfiguration", {
+    provider: ProviderID,
+    message: Schema.String,
+}) {
+}
+export class NoRouteError extends Schema.TaggedError("AI.Error.NoRoute")("NoRoute", {
+    ...ReasonFields,
+    route: RouteID,
+    provider: ProviderID,
+    model: ModelID,
+}) {
+}
+export class AuthenticationError extends Schema.TaggedError("AI.Error.Authentication")("Authentication", ReasonFields) {
+}
+export class RateLimitError extends Schema.TaggedError("AI.Error.RateLimit")("RateLimit", {
+    ...ReasonFields,
+    retryAfterMs: Schema.optional(Schema.Number),
+    rateLimit: Schema.optional(HttpRateLimitDetails),
+}) {
+}
+export class QuotaExceededError extends Schema.TaggedError("AI.Error.QuotaExceeded")("QuotaExceeded", ReasonFields) {
+}
+export class ContentPolicyError extends Schema.TaggedError("AI.Error.ContentPolicy")("ContentPolicy", ReasonFields) {
+}
+export class ProviderInternalError extends Schema.TaggedError("AI.Error.ProviderInternal")("ProviderInternal", {
+    ...ReasonFields,
+    retryAfterMs: Schema.optional(Schema.Number),
+}) {
+}
+export const TransportType = Schema.Literals(["http", "websocket"]);
+export const TransportOperation = Schema.Literals(["request", "read", "write"]);
+export class TransportError extends Schema.TaggedError("AI.Error.Transport")("Transport", {
+    ...ReasonFields,
+    transport: TransportType,
+    operation: TransportOperation,
+    code: Schema.optional(Schema.String),
+    url: Schema.optional(Schema.String),
+    phase: Schema.optional(Schema.Literals(["prepare", "queue", "connect", "send", "receive", "decode", "complete", "fallback", "close"])),
+    delivery: Schema.optional(Schema.Literals(["not-sent", "rejected", "ambiguous", "accepted"])),
+    recovery: Schema.optional(Schema.Literals(["retry-connect", "retry-full", "rotate-and-retry-full", "fallback-http", "fail"])),
+}) {
+}
+export class InvalidProviderOutputError extends Schema.TaggedError("AI.Error.InvalidProviderOutput")("InvalidProviderOutput", {
+    ...ReasonFields,
+    classification: Schema.optional(Schema.Literals(["incomplete-stream"])),
+    route: Schema.optional(Schema.String),
+}) {
+}
+export class UnknownProviderError extends Schema.TaggedError("AI.Error.UnknownProvider")("UnknownProvider", ReasonFields) {
+}
+export const AIErrorReason = Schema.Union([
+    InvalidRequestError,
+    UnsupportedOperationError,
+    NoRouteError,
+    AuthenticationError,
+    RateLimitError,
+    QuotaExceededError,
+    ContentPolicyError,
+    ProviderInternalError,
+    TransportError,
+    InvalidProviderOutputError,
+    UnknownProviderError,
+]).pipe(Schema.toTaggedUnion("_tag"));
+export class AIError extends Schema.TaggedError()("AI.Error", {
+    reason: AIErrorReason,
+}) {
+    cause = this.reason;
+    get message() {
+        return this.reason.message;
+    }
+}
+/**
+ * Failure type for tool execute handlers. Handlers must map their internal
+ * errors to this shape; the runtime catches `ToolFailure`s and surfaces them
+ * as `tool-error` events plus a `tool-result` of `type: "error"` so the model
+ * can self-correct.
+ *
+ * Anything thrown or yielded by a handler that is not a `ToolFailure` is
+ * treated as a defect and fails the stream.
+ */
+export class ToolFailure extends Tool.Error {
+}