@opencode-ai/ai 0.0.0-beta-17492

package/dist/route/transport/websocket.js

@@ -0,0 +1,326 @@
+import { Cause, Effect, Queue, Stream } from "effect";
+import { Headers } from "effect/unstable/http";
+import { Socket } from "effect/unstable/socket";
+import { AIError, TransportReason } from "../../schema/index.js";
+import * as HttpTransport from "./http.js";
+const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+const transportError = (method, message, input) => new AIError({
+    module: "WebSocketConnector",
+    method,
+    reason: new TransportReason({
+        message,
+        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({
+        module: error.module,
+        method: error.method,
+        reason: new TransportReason({
+            message: error.reason.message,
+            transport: error.reason.transport,
+            operation: error.reason.operation,
+            code: error.reason.code,
+            url: error.reason.url,
+            http: error.reason.http,
+            phase: input.phase,
+            delivery: input.delivery,
+            recovery: error.reason.recovery,
+        }),
+    })
+    : 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("open", `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)
+                ws.close(1000);
+        };
+        const onOpen = () => {
+            cleanup();
+            resume(Effect.void);
+        };
+        const onError = (event) => {
+            cleanup();
+            resume(Effect.fail(transportError("open", `Failed to open WebSocket: ${eventMessage(event)}`, {
+                url: input.url,
+                operation: "request",
+                phase: "connect",
+                delivery: "not-sent",
+            })));
+        };
+        const onClose = (event) => {
+            cleanup();
+            resume(Effect.fail(transportError("open", `WebSocket closed before opening with code ${event.code}`, {
+                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("prepare", error instanceof Error ? error.message : "Invalid WebSocket URL", {
+        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("open", error instanceof Error ? error.message : "Failed to construct WebSocket", {
+            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("message", "WebSocket message exceeds the 16 MiB limit", {
+            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("message", "WebSocket inbound queue overflow", {
+            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("message", "Unsupported WebSocket message payload", {
+            url: input.url,
+            operation: "read",
+            code: "message",
+            phase: "receive",
+        })));
+    };
+    const onError = (event) => {
+        Queue.failCauseUnsafe(messages, Cause.fail(transportError("message", `WebSocket error: ${eventMessage(event)}`, {
+            url: input.url,
+            operation: "read",
+            code: "message",
+            phase: "receive",
+        })));
+    };
+    const onClose = (event) => {
+        Queue.failCauseUnsafe(messages, Cause.fail(transportError("message", `WebSocket closed with code ${event.code}`, {
+            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("sendText", `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("sendText", error instanceof Error ? error.message : "Failed to send WebSocket message", {
+                    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);
+        const decoder = new TextDecoder();
+        let observed = false;
+        return {
+            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)), Stream.takeUntil(observationTerminal), Stream.mapEffect(observationFrame)),
+            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("json", "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("fallback", "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,159 @@
+import { Schema } from "effect";
+import { Tool } from "@opencode-ai/schema/tool";
+export declare const ProviderFailureClassification: Schema.Literals<readonly ["context-overflow", "payload-too-large"]>;
+export type ProviderFailureClassification = typeof ProviderFailureClassification.Type;
+declare const HttpRequestDetails_base: Schema.Class<HttpRequestDetails, Schema.Struct<{
+    readonly method: Schema.String;
+    readonly url: Schema.String;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+export declare class HttpRequestDetails extends HttpRequestDetails_base {
+}
+declare const HttpResponseDetails_base: Schema.Class<HttpResponseDetails, Schema.Struct<{
+    readonly status: Schema.Number;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+export declare class HttpResponseDetails extends HttpResponseDetails_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 HttpContext_base: Schema.Class<HttpContext, Schema.Struct<{
+    readonly request: typeof HttpRequestDetails;
+    readonly response: Schema.optional<typeof HttpResponseDetails>;
+    readonly body: Schema.optional<Schema.String>;
+    readonly bodyTruncated: Schema.optional<Schema.Boolean>;
+    readonly requestId: Schema.optional<Schema.String>;
+    readonly rateLimit: Schema.optional<typeof HttpRateLimitDetails>;
+}>, {}>;
+export declare class HttpContext extends HttpContext_base {
+}
+declare const InvalidRequestReason_base: Schema.Class<InvalidRequestReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"InvalidRequest">;
+    readonly message: Schema.String;
+    readonly parameter: Schema.optional<Schema.String>;
+    readonly classification: Schema.optional<Schema.Literals<readonly ["context-overflow", "payload-too-large"]>>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+    readonly http: Schema.optional<typeof HttpContext>;
+}>, {}>;
+export declare class InvalidRequestReason extends InvalidRequestReason_base {
+}
+declare const NoRouteReason_base: Schema.Class<NoRouteReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"NoRoute">;
+    readonly route: Schema.String;
+    readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
+    readonly model: Schema.brand<Schema.String, "AI.ModelID">;
+}>, {}>;
+export declare class NoRouteReason extends NoRouteReason_base {
+    get message(): string;
+}
+declare const AuthenticationReason_base: Schema.Class<AuthenticationReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"Authentication">;
+    readonly message: Schema.String;
+    readonly kind: Schema.Literals<readonly ["missing", "invalid", "expired", "insufficient-permissions", "unknown"]>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+    readonly http: Schema.optional<typeof HttpContext>;
+}>, {}>;
+export declare class AuthenticationReason extends AuthenticationReason_base {
+}
+declare const RateLimitReason_base: Schema.Class<RateLimitReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"RateLimit">;
+    readonly message: Schema.String;
+    readonly retryAfterMs: Schema.optional<Schema.Number>;
+    readonly rateLimit: Schema.optional<typeof HttpRateLimitDetails>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+    readonly http: Schema.optional<typeof HttpContext>;
+}>, {}>;
+export declare class RateLimitReason extends RateLimitReason_base {
+}
+declare const QuotaExceededReason_base: Schema.Class<QuotaExceededReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"QuotaExceeded">;
+    readonly message: Schema.String;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+    readonly http: Schema.optional<typeof HttpContext>;
+}>, {}>;
+export declare class QuotaExceededReason extends QuotaExceededReason_base {
+}
+declare const ContentPolicyReason_base: Schema.Class<ContentPolicyReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"ContentPolicy">;
+    readonly message: Schema.String;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+    readonly http: Schema.optional<typeof HttpContext>;
+}>, {}>;
+export declare class ContentPolicyReason extends ContentPolicyReason_base {
+}
+declare const ProviderInternalReason_base: Schema.Class<ProviderInternalReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"ProviderInternal">;
+    readonly message: Schema.String;
+    readonly status: Schema.optional<Schema.Number>;
+    readonly retryAfterMs: Schema.optional<Schema.Number>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+    readonly http: Schema.optional<typeof HttpContext>;
+}>, {}>;
+export declare class ProviderInternalReason extends ProviderInternalReason_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 TransportReason_base: Schema.Class<TransportReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"Transport">;
+    readonly message: Schema.String;
+    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 http: Schema.optional<typeof HttpContext>;
+    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"]>>;
+}>, {}>;
+export declare class TransportReason extends TransportReason_base {
+}
+declare const InvalidProviderOutputReason_base: Schema.Class<InvalidProviderOutputReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"InvalidProviderOutput">;
+    readonly message: Schema.String;
+    readonly classification: Schema.optional<Schema.Literals<readonly ["incomplete-stream"]>>;
+    readonly route: Schema.optional<Schema.String>;
+    readonly raw: Schema.optional<Schema.String>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+}>, {}>;
+export declare class InvalidProviderOutputReason extends InvalidProviderOutputReason_base {
+}
+declare const UnknownProviderReason_base: Schema.Class<UnknownProviderReason, Schema.Struct<{
+    readonly _tag: Schema.tag<"UnknownProvider">;
+    readonly message: Schema.String;
+    readonly status: Schema.optional<Schema.Number>;
+    readonly providerMetadata: Schema.optional<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Unknown>>>;
+    readonly http: Schema.optional<typeof HttpContext>;
+}>, {}>;
+export declare class UnknownProviderReason extends UnknownProviderReason_base {
+}
+export declare const AIErrorReason: Schema.toTaggedUnion<"_tag", readonly [typeof InvalidRequestReason, typeof NoRouteReason, typeof AuthenticationReason, typeof RateLimitReason, typeof QuotaExceededReason, typeof ContentPolicyReason, typeof ProviderInternalReason, typeof TransportReason, typeof InvalidProviderOutputReason, typeof UnknownProviderReason]>;
+export type AIErrorReason = Schema.Schema.Type<typeof AIErrorReason>;
+declare const AIError_base: Schema.Class<AIError, Schema.TaggedStruct<"AI.Error", {
+    readonly module: Schema.String;
+    readonly method: Schema.String;
+    readonly reason: Schema.toTaggedUnion<"_tag", readonly [typeof InvalidRequestReason, typeof NoRouteReason, typeof AuthenticationReason, typeof RateLimitReason, typeof QuotaExceededReason, typeof ContentPolicyReason, typeof ProviderInternalReason, typeof TransportReason, typeof InvalidProviderOutputReason, typeof UnknownProviderReason]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class AIError extends AIError_base {
+    readonly cause: InvalidRequestReason | NoRouteReason | AuthenticationReason | RateLimitReason | QuotaExceededReason | ContentPolicyReason | ProviderInternalReason | TransportReason | InvalidProviderOutputReason | UnknownProviderReason;
+    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,155 @@
+import { Schema } from "effect";
+import { Tool } from "@opencode-ai/schema/tool";
+import { ModelID, ProviderID, ProviderMetadata, RouteID } from "./ids.js";
+export const ProviderFailureClassification = Schema.Literals(["context-overflow", "payload-too-large"]);
+export class HttpRequestDetails extends Schema.Class("AI.HttpRequestDetails")({
+    method: Schema.String,
+    url: Schema.String,
+    headers: Schema.Record(Schema.String, Schema.String),
+}) {
+}
+export class HttpResponseDetails extends Schema.Class("AI.HttpResponseDetails")({
+    status: Schema.Number,
+    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)),
+}) {
+}
+export class HttpContext extends Schema.Class("AI.HttpContext")({
+    request: HttpRequestDetails,
+    response: Schema.optional(HttpResponseDetails),
+    body: Schema.optional(Schema.String),
+    bodyTruncated: Schema.optional(Schema.Boolean),
+    requestId: Schema.optional(Schema.String),
+    rateLimit: Schema.optional(HttpRateLimitDetails),
+}) {
+}
+export class InvalidRequestReason extends Schema.Class("AI.Error.InvalidRequest")({
+    _tag: Schema.tag("InvalidRequest"),
+    message: Schema.String,
+    parameter: Schema.optional(Schema.String),
+    classification: Schema.optional(ProviderFailureClassification),
+    providerMetadata: Schema.optional(ProviderMetadata),
+    http: Schema.optional(HttpContext),
+}) {
+}
+export class NoRouteReason extends Schema.Class("AI.Error.NoRoute")({
+    _tag: Schema.tag("NoRoute"),
+    route: RouteID,
+    provider: ProviderID,
+    model: ModelID,
+}) {
+    get message() {
+        return `No AI route for ${this.provider}/${this.model} using ${this.route}`;
+    }
+}
+export class AuthenticationReason extends Schema.Class("AI.Error.Authentication")({
+    _tag: Schema.tag("Authentication"),
+    message: Schema.String,
+    kind: Schema.Literals(["missing", "invalid", "expired", "insufficient-permissions", "unknown"]),
+    providerMetadata: Schema.optional(ProviderMetadata),
+    http: Schema.optional(HttpContext),
+}) {
+}
+export class RateLimitReason extends Schema.Class("AI.Error.RateLimit")({
+    _tag: Schema.tag("RateLimit"),
+    message: Schema.String,
+    retryAfterMs: Schema.optional(Schema.Number),
+    rateLimit: Schema.optional(HttpRateLimitDetails),
+    providerMetadata: Schema.optional(ProviderMetadata),
+    http: Schema.optional(HttpContext),
+}) {
+}
+export class QuotaExceededReason extends Schema.Class("AI.Error.QuotaExceeded")({
+    _tag: Schema.tag("QuotaExceeded"),
+    message: Schema.String,
+    providerMetadata: Schema.optional(ProviderMetadata),
+    http: Schema.optional(HttpContext),
+}) {
+}
+export class ContentPolicyReason extends Schema.Class("AI.Error.ContentPolicy")({
+    _tag: Schema.tag("ContentPolicy"),
+    message: Schema.String,
+    providerMetadata: Schema.optional(ProviderMetadata),
+    http: Schema.optional(HttpContext),
+}) {
+}
+export class ProviderInternalReason extends Schema.Class("AI.Error.ProviderInternal")({
+    _tag: Schema.tag("ProviderInternal"),
+    message: Schema.String,
+    status: Schema.optional(Schema.Number),
+    retryAfterMs: Schema.optional(Schema.Number),
+    providerMetadata: Schema.optional(ProviderMetadata),
+    http: Schema.optional(HttpContext),
+}) {
+}
+export const TransportType = Schema.Literals(["http", "websocket"]);
+export const TransportOperation = Schema.Literals(["request", "read", "write"]);
+export class TransportReason extends Schema.Class("AI.Error.Transport")({
+    _tag: Schema.tag("Transport"),
+    message: Schema.String,
+    transport: TransportType,
+    operation: TransportOperation,
+    code: Schema.optional(Schema.String),
+    url: Schema.optional(Schema.String),
+    http: Schema.optional(HttpContext),
+    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 InvalidProviderOutputReason extends Schema.Class("AI.Error.InvalidProviderOutput")({
+    _tag: Schema.tag("InvalidProviderOutput"),
+    message: Schema.String,
+    classification: Schema.optional(Schema.Literals(["incomplete-stream"])),
+    route: Schema.optional(Schema.String),
+    raw: Schema.optional(Schema.String),
+    providerMetadata: Schema.optional(ProviderMetadata),
+}) {
+}
+export class UnknownProviderReason extends Schema.Class("AI.Error.UnknownProvider")({
+    _tag: Schema.tag("UnknownProvider"),
+    message: Schema.String,
+    status: Schema.optional(Schema.Number),
+    providerMetadata: Schema.optional(ProviderMetadata),
+    http: Schema.optional(HttpContext),
+}) {
+}
+export const AIErrorReason = Schema.Union([
+    InvalidRequestReason,
+    NoRouteReason,
+    AuthenticationReason,
+    RateLimitReason,
+    QuotaExceededReason,
+    ContentPolicyReason,
+    ProviderInternalReason,
+    TransportReason,
+    InvalidProviderOutputReason,
+    UnknownProviderReason,
+]).pipe(Schema.toTaggedUnion("_tag"));
+export class AIError extends Schema.TaggedErrorClass()("AI.Error", {
+    module: Schema.String,
+    method: Schema.String,
+    reason: AIErrorReason,
+}) {
+    cause = this.reason;
+    get message() {
+        return `${this.module}.${this.method}: ${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 {
+}