npm - @neurocode-ai/llm - Versions diffs - 1.18.8 - Mend

@neurocode-ai/llm 1.18.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (152) hide show

package/AGENTS.md +321 -0
package/DESIGN.md +1114 -0
package/README.md +131 -0
package/example/call-sites.md +591 -0
package/example/tutorial.ts +255 -0
package/package.json +51 -0
package/script/recording-cost-report.ts +250 -0
package/script/setup-recording-env.ts +542 -0
package/src/cache-policy.ts +111 -0
package/src/index.ts +33 -0
package/src/llm.ts +186 -0
package/src/protocols/anthropic-messages.ts +855 -0
package/src/protocols/bedrock-converse.ts +674 -0
package/src/protocols/bedrock-event-stream.ts +87 -0
package/src/protocols/gemini.ts +512 -0
package/src/protocols/index.ts +6 -0
package/src/protocols/openai-chat.ts +506 -0
package/src/protocols/openai-compatible-chat.ts +24 -0
package/src/protocols/openai-responses.ts +1022 -0
package/src/protocols/shared.ts +326 -0
package/src/protocols/utils/bedrock-auth.ts +70 -0
package/src/protocols/utils/bedrock-cache.ts +37 -0
package/src/protocols/utils/bedrock-media.ts +90 -0
package/src/protocols/utils/cache.ts +16 -0
package/src/protocols/utils/gemini-tool-schema.ts +99 -0
package/src/protocols/utils/lifecycle.ts +102 -0
package/src/protocols/utils/openai-options.ts +93 -0
package/src/protocols/utils/tool-schema.ts +86 -0
package/src/protocols/utils/tool-stream.ts +218 -0
package/src/provider-error.ts +43 -0
package/src/provider.ts +36 -0
package/src/providers/amazon-bedrock.ts +43 -0
package/src/providers/anthropic.ts +35 -0
package/src/providers/azure.ts +110 -0
package/src/providers/cloudflare.ts +127 -0
package/src/providers/github-copilot.ts +69 -0
package/src/providers/google.ts +35 -0
package/src/providers/index.ts +11 -0
package/src/providers/openai-compatible-profile.ts +20 -0
package/src/providers/openai-compatible.ts +65 -0
package/src/providers/openai-options.ts +83 -0
package/src/providers/openai.ts +63 -0
package/src/providers/openrouter.ts +98 -0
package/src/providers/xai.ts +56 -0
package/src/route/auth-options.ts +57 -0
package/src/route/auth.ts +156 -0
package/src/route/client.ts +436 -0
package/src/route/endpoint.ts +53 -0
package/src/route/executor.ts +385 -0
package/src/route/framing.ts +27 -0
package/src/route/index.ts +25 -0
package/src/route/protocol.ts +84 -0
package/src/route/transport/http.ts +155 -0
package/src/route/transport/index.ts +33 -0
package/src/route/transport/websocket.ts +280 -0
package/src/schema/errors.ts +207 -0
package/src/schema/events.ts +618 -0
package/src/schema/ids.ts +43 -0
package/src/schema/index.ts +5 -0
package/src/schema/messages.ts +312 -0
package/src/schema/options.ts +276 -0
package/src/tool-runtime.ts +78 -0
package/src/tool.ts +253 -0
package/src/utils/record.ts +3 -0
package/sst-env.d.ts +10 -0
package/test/adapter.test.ts +171 -0
package/test/auth-options.types.ts +168 -0
package/test/auth.test.ts +103 -0
package/test/cache-policy.test.ts +262 -0
package/test/continuation-scenarios.ts +104 -0
package/test/endpoint.test.ts +58 -0
package/test/executor.test.ts +458 -0
package/test/exports.test.ts +76 -0
package/test/fixtures/media/restroom.png +0 -0
package/test/fixtures/recordings/anthropic-messages/accepts-malformed-assistant-tool-order-with-default-patch.json +29 -0
package/test/fixtures/recordings/anthropic-messages/anthropic-opus-4-7-image-tool-result.json +43 -0
package/test/fixtures/recordings/anthropic-messages/claude-opus-4-7-drives-a-tool-loop.json +56 -0
package/test/fixtures/recordings/anthropic-messages/rejects-malformed-assistant-tool-order-without-patch.json +29 -0
package/test/fixtures/recordings/anthropic-messages/streams-text.json +29 -0
package/test/fixtures/recordings/anthropic-messages/streams-tool-call.json +29 -0
package/test/fixtures/recordings/anthropic-messages-cache/writes-then-reads-cache-control-on-identical-second-call.json +48 -0
package/test/fixtures/recordings/bedrock-converse/drives-a-tool-loop.json +55 -0
package/test/fixtures/recordings/bedrock-converse/streams-a-tool-call.json +29 -0
package/test/fixtures/recordings/bedrock-converse/streams-text.json +29 -0
package/test/fixtures/recordings/cloudflare-ai-gateway/cloudflare-ai-gateway-workers-ai-gpt-oss-20b-tools-tool-call.json +32 -0
package/test/fixtures/recordings/cloudflare-ai-gateway/cloudflare-ai-gateway-workers-ai-llama-3-1-8b-text.json +32 -0
package/test/fixtures/recordings/cloudflare-workers-ai/cloudflare-workers-ai-gpt-oss-20b-tools-tool-call.json +32 -0
package/test/fixtures/recordings/cloudflare-workers-ai/cloudflare-workers-ai-llama-3-1-8b-text.json +32 -0
package/test/fixtures/recordings/gemini/gemini-2-5-flash-image.json +32 -0
package/test/fixtures/recordings/gemini/streams-text.json +28 -0
package/test/fixtures/recordings/gemini/streams-tool-call.json +28 -0
package/test/fixtures/recordings/gemini-cache/reports-cachedcontenttokencount-on-identical-second-call.json +46 -0
package/test/fixtures/recordings/openai-chat/continues-after-tool-result.json +28 -0
package/test/fixtures/recordings/openai-chat/drives-a-tool-loop-end-to-end.json +46 -0
package/test/fixtures/recordings/openai-chat/streams-text.json +28 -0
package/test/fixtures/recordings/openai-chat/streams-tool-call.json +28 -0
package/test/fixtures/recordings/openai-compatible-chat/deepseek-streams-text.json +28 -0
package/test/fixtures/recordings/openai-compatible-chat/groq-llama-3-3-70b-drives-a-tool-loop.json +53 -0
package/test/fixtures/recordings/openai-compatible-chat/groq-streams-text.json +28 -0
package/test/fixtures/recordings/openai-compatible-chat/groq-streams-tool-call.json +28 -0
package/test/fixtures/recordings/openai-compatible-chat/openrouter-claude-opus-4-7-drives-a-tool-loop.json +54 -0
package/test/fixtures/recordings/openai-compatible-chat/openrouter-gpt-4o-mini-drives-a-tool-loop.json +53 -0
package/test/fixtures/recordings/openai-compatible-chat/openrouter-gpt-5-5-drives-a-tool-loop.json +54 -0
package/test/fixtures/recordings/openai-compatible-chat/openrouter-streams-text.json +28 -0
package/test/fixtures/recordings/openai-compatible-chat/openrouter-streams-tool-call.json +28 -0
package/test/fixtures/recordings/openai-compatible-chat/togetherai-streams-text.json +28 -0
package/test/fixtures/recordings/openai-compatible-chat/togetherai-streams-tool-call.json +28 -0
package/test/fixtures/recordings/openai-responses/gpt-5-5-drives-a-tool-loop.json +54 -0
package/test/fixtures/recordings/openai-responses/gpt-5-5-streams-text.json +28 -0
package/test/fixtures/recordings/openai-responses/gpt-5-5-streams-tool-call.json +28 -0
package/test/fixtures/recordings/openai-responses/openai-responses-gpt-5-5-image-tool-result.json +42 -0
package/test/fixtures/recordings/openai-responses/openai-responses-gpt-5-5-reasoning-continuation.json +58 -0
package/test/fixtures/recordings/openai-responses/openai-responses-gpt-5-5-reasoning.json +32 -0
package/test/fixtures/recordings/openai-responses-cache/reports-cached-tokens-on-identical-second-call.json +46 -0
package/test/generate-object.test.ts +184 -0
package/test/lib/effect.ts +50 -0
package/test/lib/http.ts +98 -0
package/test/lib/openai-chunks.ts +27 -0
package/test/lib/sse.ts +17 -0
package/test/lib/tool-runtime.ts +146 -0
package/test/llm.test.ts +199 -0
package/test/prepare.test.ts +178 -0
package/test/provider/anthropic-messages-cache.recorded.test.ts +53 -0
package/test/provider/anthropic-messages.recorded.test.ts +45 -0
package/test/provider/anthropic-messages.test.ts +895 -0
package/test/provider/bedrock-converse-cache.recorded.test.ts +54 -0
package/test/provider/bedrock-converse.test.ts +744 -0
package/test/provider/cloudflare.test.ts +230 -0
package/test/provider/gemini-cache.recorded.test.ts +48 -0
package/test/provider/gemini.test.ts +584 -0
package/test/provider/golden.recorded.test.ts +223 -0
package/test/provider/openai-chat.test.ts +674 -0
package/test/provider/openai-compatible-chat.test.ts +238 -0
package/test/provider/openai-responses-cache.recorded.test.ts +46 -0
package/test/provider/openai-responses.test.ts +1472 -0
package/test/provider/openrouter.test.ts +56 -0
package/test/provider-error.test.ts +30 -0
package/test/provider.types.ts +41 -0
package/test/recorded-golden.ts +97 -0
package/test/recorded-runner.ts +100 -0
package/test/recorded-scenarios.ts +531 -0
package/test/recorded-test.ts +94 -0
package/test/recorded-utils.ts +56 -0
package/test/recorded-websocket.ts +26 -0
package/test/response.test.ts +98 -0
package/test/route.test.ts +43 -0
package/test/schema.test.ts +86 -0
package/test/tool-runtime.test.ts +818 -0
package/test/tool-schema-projection.test.ts +117 -0
package/test/tool-stream.test.ts +99 -0
package/test/tool.types.ts +40 -0
package/tsconfig.json +15 -0

package/src/route/transport/index.ts ADDED Viewed

@@ -0,0 +1,33 @@
+import type { Effect, Stream } from "effect"
+import type { Endpoint } from "../endpoint"
+import type { Auth } from "../auth"
+import type { Interface as RequestExecutorInterface } from "../executor"
+import type { Interface as WebSocketExecutorInterface } from "./websocket"
+import type { LLMError, LLMRequest } from "../../schema"
+export interface TransportRuntime {
+  readonly http: RequestExecutorInterface
+  readonly webSocket?: WebSocketExecutorInterface
+}
+export interface Transport<Body, Prepared, Frame> {
+  readonly id: string
+  readonly prepare: (input: TransportPrepareInput<Body>) => Effect.Effect<Prepared, LLMError>
+  readonly frames: (
+    prepared: Prepared,
+    request: LLMRequest,
+    runtime: TransportRuntime,
+  ) => Stream.Stream<Frame, LLMError>
+}
+export interface TransportPrepareInput<Body> {
+  readonly body: Body
+  readonly request: LLMRequest
+  readonly endpoint: Endpoint<Body>
+  readonly auth: Auth
+  readonly encodeBody: (body: Body) => string
+  readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
+}
+export * as HttpTransport from "./http"
+export { WebSocketExecutor, WebSocketTransport } from "./websocket"

package/src/route/transport/websocket.ts ADDED Viewed

@@ -0,0 +1,280 @@
+import { Cause, Context, Effect, Layer, Queue, Stream } from "effect"
+import { Headers } from "effect/unstable/http"
+import { LLMError, TransportReason } from "../../schema"
+import * as HttpTransport from "./http"
+import type { Transport } from "./index"
+export interface WebSocketRequest {
+  readonly url: string
+  readonly headers: Headers.Headers
+}
+export interface WebSocketConnection {
+  readonly sendText: (message: string) => Effect.Effect<void, LLMError>
+  readonly messages: Stream.Stream<string | Uint8Array, LLMError>
+  readonly close: Effect.Effect<void, never>
+}
+export interface Interface {
+  readonly open: (input: WebSocketRequest) => Effect.Effect<WebSocketConnection, LLMError>
+}
+type WebSocketConstructorWithHeaders = new (
+  url: string,
+  options?: { readonly headers?: Headers.Headers },
+) => globalThis.WebSocket
+export class Service extends Context.Service<Service, Interface>()("@neurocode/LLM/WebSocketExecutor") {}
+const transportError = (
+  method: string,
+  message: string,
+  input: { readonly url?: string; readonly kind?: string } = {},
+) =>
+  new LLMError({
+    module: "WebSocketExecutor",
+    method,
+    reason: new TransportReason({ message, url: input.url, kind: input.kind }),
+  })
+const eventMessage = (event: Event) => {
+  if ("message" in event && typeof event.message === "string") return event.message
+  return event.type
+}
+const binaryMessage = (data: unknown) => {
+  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: globalThis.WebSocket, input: WebSocketRequest) => {
+  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,
+        kind: "open",
+      }),
+    )
+  }
+  return Effect.callback<void, LLMError>((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: Event) => {
+      cleanup()
+      resume(
+        Effect.fail(
+          transportError("open", `Failed to open WebSocket: ${eventMessage(event)}`, { url: input.url, kind: "open" }),
+        ),
+      )
+    }
+    const onClose = (event: CloseEvent) => {
+      cleanup()
+      resume(
+        Effect.fail(
+          transportError("open", `WebSocket closed before opening with code ${event.code}`, {
+            url: input.url,
+            kind: "open",
+          }),
+        ),
+      )
+    }
+    ws.addEventListener("open", onOpen, { once: true })
+    ws.addEventListener("error", onError, { once: true })
+    ws.addEventListener("close", onClose, { once: true })
+    signal.addEventListener("abort", onAbort, { once: true })
+  })
+}
+const webSocketUrl = (value: string) =>
+  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,
+        kind: "websocket",
+      }),
+  })
+export const open = (input: WebSocketRequest) =>
+  Effect.try({
+    try: () =>
+      new (globalThis.WebSocket as unknown as WebSocketConstructorWithHeaders)(input.url, { headers: input.headers }),
+    catch: (error) =>
+      transportError("open", error instanceof Error ? error.message : "Failed to construct WebSocket", {
+        url: input.url,
+        kind: "open",
+      }),
+  }).pipe(Effect.flatMap((ws) => fromWebSocket(ws, input)))
+export const layer: Layer.Layer<Service> = Layer.succeed(Service, Service.of({ open }))
+export const fromWebSocket = (
+  ws: globalThis.WebSocket,
+  input: WebSocketRequest,
+): Effect.Effect<WebSocketConnection, LLMError> =>
+  Effect.gen(function* () {
+    yield* waitOpen(ws, input)
+    const messages = yield* Queue.bounded<string | Uint8Array, LLMError | Cause.Done<void>>(128)
+    const onMessage = (event: MessageEvent) => {
+      if (typeof event.data === "string") return Queue.offerUnsafe(messages, event.data)
+      const binary = binaryMessage(event.data)
+      if (binary) return Queue.offerUnsafe(messages, binary)
+      Queue.failCauseUnsafe(
+        messages,
+        Cause.fail(
+          transportError("message", "Unsupported WebSocket message payload", { url: input.url, kind: "message" }),
+        ),
+      )
+    }
+    const onError = (event: Event) => {
+      Queue.failCauseUnsafe(
+        messages,
+        Cause.fail(
+          transportError("message", `WebSocket error: ${eventMessage(event)}`, { url: input.url, kind: "message" }),
+        ),
+      )
+    }
+    const onClose = (event: CloseEvent) => {
+      if (event.code === 1000 || event.code === 1005) return Queue.endUnsafe(messages)
+      Queue.failCauseUnsafe(
+        messages,
+        Cause.fail(
+          transportError("message", `WebSocket closed with code ${event.code}`, { url: input.url, kind: "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.try({
+          try: () => ws.send(message),
+          catch: (error) =>
+            transportError("sendText", error instanceof Error ? error.message : "Failed to send WebSocket message", {
+              url: input.url,
+              kind: "write",
+            }),
+        }),
+      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: string | Uint8Array, decoder: TextDecoder) =>
+  typeof message === "string" ? message : decoder.decode(message)
+export interface JsonPrepared {
+  readonly url: string
+  readonly headers: Headers.Headers
+  readonly message: string
+}
+export interface JsonInput<Body, Message> {
+  readonly toMessage: (body: Body | Record<string, unknown>) => Effect.Effect<Message, LLMError>
+  readonly encodeMessage: (message: Message) => string
+}
+export type JsonPatch<Body, Message> = Partial<JsonInput<Body, Message>>
+export interface JsonTransport<Body, Message> extends Transport<Body, JsonPrepared, string> {
+  readonly with: (patch: JsonPatch<Body, Message>) => JsonTransport<Body, Message>
+}
+export const json = <Body, Message>(input: JsonInput<Body, Message>): JsonTransport<Body, Message> => ({
+  id: "websocket-json",
+  with: (patch) => json({ ...input, ...patch }),
+  prepare: (prepareInput) =>
+    Effect.gen(function* () {
+      const parts = yield* HttpTransport.jsonRequestParts({
+        ...prepareInput,
+      })
+      return {
+        url: yield* webSocketUrl(parts.url),
+        headers: parts.headers,
+        message: input.encodeMessage(yield* input.toMessage(parts.jsonBody)),
+      }
+    }),
+  frames: (prepared, _request, runtime) => {
+    const webSocket = runtime.webSocket
+    if (!webSocket) {
+      return Stream.fail(
+        transportError("json", "WebSocket JSON transport requires WebSocketExecutor.Service", {
+          url: prepared.url,
+          kind: "websocket",
+        }),
+      )
+    }
+    const decoder = new TextDecoder()
+    return Stream.unwrap(
+      Effect.gen(function* () {
+        const connection = yield* Effect.acquireRelease(
+          webSocket.open({ url: prepared.url, headers: prepared.headers }),
+          (connection) => connection.close,
+        )
+        yield* connection.sendText(prepared.message)
+        return connection.messages.pipe(Stream.map((message) => messageText(message, decoder)))
+      }),
+    )
+  },
+})
+export const jsonTransport = {
+  id: "websocket-json",
+  with: json,
+} as const
+export const WebSocketExecutor = {
+  Service,
+  layer,
+  open,
+  fromWebSocket,
+  messageText,
+} as const
+export const WebSocketTransport = {
+  json,
+  jsonTransport,
+} as const

package/src/schema/errors.ts ADDED Viewed

@@ -0,0 +1,207 @@
+import { Schema } from "effect"
+import { ModelID, ProviderID, ProviderMetadata, RouteID } from "./ids"
+export const ProviderFailureClassification = Schema.Literal("context-overflow")
+export type ProviderFailureClassification = typeof ProviderFailureClassification.Type
+export class HttpRequestDetails extends Schema.Class<HttpRequestDetails>("LLM.HttpRequestDetails")({
+  method: Schema.String,
+  url: Schema.String,
+  headers: Schema.Record(Schema.String, Schema.String),
+}) {}
+export class HttpResponseDetails extends Schema.Class<HttpResponseDetails>("LLM.HttpResponseDetails")({
+  status: Schema.Number,
+  headers: Schema.Record(Schema.String, Schema.String),
+}) {}
+export class HttpRateLimitDetails extends Schema.Class<HttpRateLimitDetails>("LLM.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<HttpContext>("LLM.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<InvalidRequestReason>("LLM.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),
+}) {
+  get retryable() {
+    return false
+  }
+}
+export class NoRouteReason extends Schema.Class<NoRouteReason>("LLM.Error.NoRoute")({
+  _tag: Schema.tag("NoRoute"),
+  route: RouteID,
+  provider: ProviderID,
+  model: ModelID,
+}) {
+  get retryable() {
+    return false
+  }
+  get message() {
+    return `No LLM route for ${this.provider}/${this.model} using ${this.route}`
+  }
+}
+export class AuthenticationReason extends Schema.Class<AuthenticationReason>("LLM.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),
+}) {
+  get retryable() {
+    return false
+  }
+}
+export class RateLimitReason extends Schema.Class<RateLimitReason>("LLM.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),
+}) {
+  get retryable() {
+    return true
+  }
+}
+export class QuotaExceededReason extends Schema.Class<QuotaExceededReason>("LLM.Error.QuotaExceeded")({
+  _tag: Schema.tag("QuotaExceeded"),
+  message: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
+  http: Schema.optional(HttpContext),
+}) {
+  get retryable() {
+    return false
+  }
+}
+export class ContentPolicyReason extends Schema.Class<ContentPolicyReason>("LLM.Error.ContentPolicy")({
+  _tag: Schema.tag("ContentPolicy"),
+  message: Schema.String,
+  providerMetadata: Schema.optional(ProviderMetadata),
+  http: Schema.optional(HttpContext),
+}) {
+  get retryable() {
+    return false
+  }
+}
+export class ProviderInternalReason extends Schema.Class<ProviderInternalReason>("LLM.Error.ProviderInternal")({
+  _tag: Schema.tag("ProviderInternal"),
+  message: Schema.String,
+  status: Schema.Number,
+  retryAfterMs: Schema.optional(Schema.Number),
+  providerMetadata: Schema.optional(ProviderMetadata),
+  http: Schema.optional(HttpContext),
+}) {
+  get retryable() {
+    return true
+  }
+}
+export class TransportReason extends Schema.Class<TransportReason>("LLM.Error.Transport")({
+  _tag: Schema.tag("Transport"),
+  message: Schema.String,
+  kind: Schema.optional(Schema.String),
+  url: Schema.optional(Schema.String),
+  http: Schema.optional(HttpContext),
+}) {
+  get retryable() {
+    return false
+  }
+}
+export class InvalidProviderOutputReason extends Schema.Class<InvalidProviderOutputReason>(
+  "LLM.Error.InvalidProviderOutput",
+)({
+  _tag: Schema.tag("InvalidProviderOutput"),
+  message: Schema.String,
+  route: Schema.optional(Schema.String),
+  raw: Schema.optional(Schema.String),
+  providerMetadata: Schema.optional(ProviderMetadata),
+}) {
+  get retryable() {
+    return false
+  }
+}
+export class UnknownProviderReason extends Schema.Class<UnknownProviderReason>("LLM.Error.UnknownProvider")({
+  _tag: Schema.tag("UnknownProvider"),
+  message: Schema.String,
+  status: Schema.optional(Schema.Number),
+  providerMetadata: Schema.optional(ProviderMetadata),
+  http: Schema.optional(HttpContext),
+}) {
+  get retryable() {
+    return false
+  }
+}
+export const LLMErrorReason = Schema.Union([
+  InvalidRequestReason,
+  NoRouteReason,
+  AuthenticationReason,
+  RateLimitReason,
+  QuotaExceededReason,
+  ContentPolicyReason,
+  ProviderInternalReason,
+  TransportReason,
+  InvalidProviderOutputReason,
+  UnknownProviderReason,
+]).pipe(Schema.toTaggedUnion("_tag"))
+export type LLMErrorReason = Schema.Schema.Type<typeof LLMErrorReason>
+export class LLMError extends Schema.TaggedErrorClass<LLMError>()("LLM.Error", {
+  module: Schema.String,
+  method: Schema.String,
+  reason: LLMErrorReason,
+}) {
+  override readonly cause = this.reason
+  get retryable() {
+    return this.reason.retryable
+  }
+  get retryAfterMs() {
+    return "retryAfterMs" in this.reason ? this.reason.retryAfterMs : undefined
+  }
+  override 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 Schema.TaggedErrorClass<ToolFailure>()("LLM.ToolFailure", {
+  message: Schema.String,
+  error: Schema.optional(Schema.Defect()),
+  metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+}) {}