effect 4.0.0-beta.101 → 4.0.0-beta.103

package/dist/unstable/ai/AiError.d.ts

@@ -22,7 +22,7 @@ declare const NetworkError_base: Schema.Class<NetworkError, Schema.Struct<{
         readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
         readonly url: Schema.String;
         readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-        readonly hash: Schema.UndefinedOr<Schema.String>;
+        readonly hash: Schema.optional<Schema.String>;
         readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
     }>;
     readonly description: Schema.optional<Schema.String>;
@@ -38,7 +38,7 @@ declare const NetworkError_base: Schema.Class<NetworkError, Schema.Struct<{
  *
  * **Example** (Creating a network error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.NetworkError({
@@ -53,12 +53,10 @@ declare const NetworkError_base: Schema.Class<NetworkError, Schema.Struct<{
  *   description: "Connection timeout after 30 seconds"
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Transport: Connection timeout after 30 seconds (POST https://api.openai.com/v1/completions)"
+ * const result = [error.reason, error.isRetryable] // => ["TransportError", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class NetworkError extends NetworkError_base {
@@ -79,13 +77,17 @@ export declare class NetworkError extends NetworkError_base {
      *
      * **Example** (Creating a network error from a request error)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { AiError } from "effect/unstable/ai"
-     * import type { HttpClientError } from "effect/unstable/http"
+     * import { HttpClientError, HttpClientRequest } from "effect/unstable/http"
      *
-     * declare const platformError: HttpClientError.RequestError
+     * const platformError = new HttpClientError.TransportError({
+     *   request: HttpClientRequest.get("https://example.com/models"),
+     *   description: "Connection refused"
+     * })
      *
      * const aiError = AiError.NetworkError.fromRequestError(platformError)
+     * aiError.reason // => "TransportError"
      * ```
      *
      * @since 4.0.0
@@ -103,7 +105,7 @@ export declare class NetworkError extends NetworkError_base {
  *
  * **Example** (Inspecting metadata shape)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * const metadata = {
  *   openai: {
  *     errorCode: "rate_limit_exceeded",
@@ -111,6 +113,8 @@ export declare class NetworkError extends NetworkError_base {
  *   },
  *   anthropic: null
  * }
+ *
+ * Array.of(metadata.openai.errorCode, metadata.anthropic) // => ["rate_limit_exceeded", null]
  * ```
  *
  * @category schemas
@@ -221,9 +225,9 @@ export interface UnknownErrorMetadata extends ProviderMetadata {
  * @since 4.0.0
  */
 export declare const UsageInfo: Schema.Struct<{
-    readonly promptTokens: Schema.optional<Schema.Number>;
-    readonly completionTokens: Schema.optional<Schema.Number>;
-    readonly totalTokens: Schema.optional<Schema.Number>;
+    readonly promptTokens: Schema.optional<Schema.Int>;
+    readonly completionTokens: Schema.optional<Schema.Int>;
+    readonly totalTokens: Schema.optional<Schema.Int>;
 }>;
 /**
  * Schema for the combined HTTP context used in error reporting.
@@ -249,11 +253,11 @@ export declare const HttpContext: Schema.Struct<{
         readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
         readonly url: Schema.String;
         readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-        readonly hash: Schema.UndefinedOr<Schema.String>;
+        readonly hash: Schema.optional<Schema.String>;
         readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
     }>;
     readonly response: Schema.optional<Schema.Struct<{
-        readonly status: Schema.Number;
+        readonly status: Schema.Int;
         readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
     }>>;
     readonly body: Schema.optional<Schema.String>;
@@ -267,11 +271,11 @@ declare const RateLimitError_base: Schema.Class<RateLimitError, Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
             readonly url: Schema.String;
             readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-            readonly hash: Schema.UndefinedOr<Schema.String>;
+            readonly hash: Schema.optional<Schema.String>;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>;
         readonly response: Schema.optional<Schema.Struct<{
-            readonly status: Schema.Number;
+            readonly status: Schema.Int;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>>;
         readonly body: Schema.optional<Schema.String>;
@@ -287,7 +291,7 @@ declare const RateLimitError_base: Schema.Class<RateLimitError, Schema.Struct<{
  *
  * **Example** (Creating a rate limit error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -295,11 +299,10 @@ declare const RateLimitError_base: Schema.Class<RateLimitError, Schema.Struct<{
  *   retryAfter: Duration.seconds(60)
  * })
  *
- * console.log(rateLimitError.isRetryable) // true
- * console.log(rateLimitError.message) // "Rate limit exceeded. Retry after 1 minute"
+ * const result = [rateLimitError._tag, rateLimitError.isRetryable] // => ["RateLimitError", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class RateLimitError extends RateLimitError_base {
@@ -326,11 +329,11 @@ declare const QuotaExhaustedError_base: Schema.Class<QuotaExhaustedError, Schema
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
             readonly url: Schema.String;
             readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-            readonly hash: Schema.UndefinedOr<Schema.String>;
+            readonly hash: Schema.optional<Schema.String>;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>;
         readonly response: Schema.optional<Schema.Struct<{
-            readonly status: Schema.Number;
+            readonly status: Schema.Int;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>>;
         readonly body: Schema.optional<Schema.String>;
@@ -345,17 +348,15 @@ declare const QuotaExhaustedError_base: Schema.Class<QuotaExhaustedError, Schema
  *
  * **Example** (Creating a quota exhausted error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const quotaError = new AiError.QuotaExhaustedError({})
  *
- * console.log(quotaError.isRetryable) // false
- * console.log(quotaError.message)
- * // "Quota exhausted. Check your account billing and usage limits."
+ * const result = [quotaError._tag, quotaError.isRetryable] // => ["QuotaExhaustedError", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class QuotaExhaustedError extends QuotaExhaustedError_base {
@@ -382,11 +383,11 @@ declare const AuthenticationError_base: Schema.Class<AuthenticationError, Schema
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
             readonly url: Schema.String;
             readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-            readonly hash: Schema.UndefinedOr<Schema.String>;
+            readonly hash: Schema.optional<Schema.String>;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>;
         readonly response: Schema.optional<Schema.Struct<{
-            readonly status: Schema.Number;
+            readonly status: Schema.Int;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>>;
         readonly body: Schema.optional<Schema.String>;
@@ -401,19 +402,17 @@ declare const AuthenticationError_base: Schema.Class<AuthenticationError, Schema
  *
  * **Example** (Creating an authentication error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const authError = new AiError.AuthenticationError({
  *   kind: "InvalidKey"
  * })
  *
- * console.log(authError.isRetryable) // false
- * console.log(authError.message)
- * // "InvalidKey: Verify your API key is correct"
+ * const result = [authError.kind, authError.isRetryable] // => ["InvalidKey", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class AuthenticationError extends AuthenticationError_base {
@@ -440,11 +439,11 @@ declare const ContentPolicyError_base: Schema.Class<ContentPolicyError, Schema.S
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
             readonly url: Schema.String;
             readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-            readonly hash: Schema.UndefinedOr<Schema.String>;
+            readonly hash: Schema.optional<Schema.String>;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>;
         readonly response: Schema.optional<Schema.Struct<{
-            readonly status: Schema.Number;
+            readonly status: Schema.Int;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>>;
         readonly body: Schema.optional<Schema.String>;
@@ -459,19 +458,17 @@ declare const ContentPolicyError_base: Schema.Class<ContentPolicyError, Schema.S
  *
  * **Example** (Creating a content policy error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const policyError = new AiError.ContentPolicyError({
  *   description: "Input contains prohibited content"
  * })
  *
- * console.log(policyError.isRetryable) // false
- * console.log(policyError.message)
- * // "Content policy violation: Input contains prohibited content"
+ * const result = [policyError.description, policyError.isRetryable] // => ["Input contains prohibited content", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class ContentPolicyError extends ContentPolicyError_base {
@@ -500,11 +497,11 @@ declare const InvalidRequestError_base: Schema.Class<InvalidRequestError, Schema
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
             readonly url: Schema.String;
             readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-            readonly hash: Schema.UndefinedOr<Schema.String>;
+            readonly hash: Schema.optional<Schema.String>;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>;
         readonly response: Schema.optional<Schema.Struct<{
-            readonly status: Schema.Number;
+            readonly status: Schema.Int;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>>;
         readonly body: Schema.optional<Schema.String>;
@@ -519,7 +516,7 @@ declare const InvalidRequestError_base: Schema.Class<InvalidRequestError, Schema
  *
  * **Example** (Creating an invalid request error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const invalidRequestError = new AiError.InvalidRequestError({
@@ -528,12 +525,10 @@ declare const InvalidRequestError_base: Schema.Class<InvalidRequestError, Schema
  *   description: "Temperature value 5 is out of range"
  * })
  *
- * console.log(invalidRequestError.isRetryable) // false
- * console.log(invalidRequestError.message)
- * // "Invalid request: parameter 'temperature' must be between 0 and 2. Temperature value 5 is out of range"
+ * const result = [invalidRequestError.parameter, invalidRequestError.isRetryable] // => ["temperature", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class InvalidRequestError extends InvalidRequestError_base {
@@ -560,11 +555,11 @@ declare const InternalProviderError_base: Schema.Class<InternalProviderError, Sc
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
             readonly url: Schema.String;
             readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-            readonly hash: Schema.UndefinedOr<Schema.String>;
+            readonly hash: Schema.optional<Schema.String>;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>;
         readonly response: Schema.optional<Schema.Struct<{
-            readonly status: Schema.Number;
+            readonly status: Schema.Int;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>>;
         readonly body: Schema.optional<Schema.String>;
@@ -579,19 +574,17 @@ declare const InternalProviderError_base: Schema.Class<InternalProviderError, Sc
  *
  * **Example** (Creating an internal provider error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const providerError = new AiError.InternalProviderError({
  *   description: "Server encountered an unexpected error"
  * })
  *
- * console.log(providerError.isRetryable) // true
- * console.log(providerError.message)
- * // "Internal provider error: Server encountered an unexpected error"
+ * const result = [providerError.description, providerError.isRetryable] // => ["Server encountered an unexpected error", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class InternalProviderError extends InternalProviderError_base {
@@ -614,9 +607,9 @@ declare const InvalidOutputError_base: Schema.Class<InvalidOutputError, Schema.S
     readonly description: Schema.String;
     readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<InvalidOutputErrorMetadata>>, never>;
     readonly usage: Schema.optional<Schema.Struct<{
-        readonly promptTokens: Schema.optional<Schema.Number>;
-        readonly completionTokens: Schema.optional<Schema.Number>;
-        readonly totalTokens: Schema.optional<Schema.Number>;
+        readonly promptTokens: Schema.optional<Schema.Int>;
+        readonly completionTokens: Schema.optional<Schema.Int>;
+        readonly totalTokens: Schema.optional<Schema.Int>;
     }>>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
@@ -628,19 +621,17 @@ declare const InvalidOutputError_base: Schema.Class<InvalidOutputError, Schema.S
  *
  * **Example** (Creating an invalid output error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const parseError = new AiError.InvalidOutputError({
  *   description: "Expected a string but received a number"
  * })
  *
- * console.log(parseError.isRetryable) // true
- * console.log(parseError.message)
- * // "Invalid output: Expected a string but received a number"
+ * const result = [parseError.description, parseError.isRetryable] // => ["Expected a string but received a number", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class InvalidOutputError extends InvalidOutputError_base {
@@ -661,13 +652,15 @@ export declare class InvalidOutputError extends InvalidOutputError_base {
      *
      * **Example** (Creating an invalid output error from a schema error)
      *
-     * ```ts
-     * import { Schema } from "effect"
+     * ```ts import.meta.vitest
+     * import { Effect, Schema } from "effect"
      * import { AiError } from "effect/unstable/ai"
      *
-     * declare const schemaError: Schema.SchemaError
-     *
+     * const schemaError = await Effect.runPromise(
+     *   Schema.decodeUnknownEffect(Schema.Number)("not a number").pipe(Effect.flip)
+     * )
      * const parseError = AiError.InvalidOutputError.fromSchemaError(schemaError)
+     * parseError.description // => "Expected number"
      * ```
      *
      * @since 4.0.0
@@ -681,9 +674,9 @@ declare const StructuredOutputError_base: Schema.Class<StructuredOutputError, Sc
     readonly responseText: Schema.String;
     readonly metadata: Schema.withDecodingDefault<Schema.withConstructorDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson, Schema.MutableJson, never, never>>> & Schema.Schema<StructuredOutputErrorMetadata>>, never>;
     readonly usage: Schema.optional<Schema.Struct<{
-        readonly promptTokens: Schema.optional<Schema.Number>;
-        readonly completionTokens: Schema.optional<Schema.Number>;
-        readonly totalTokens: Schema.optional<Schema.Number>;
+        readonly promptTokens: Schema.optional<Schema.Int>;
+        readonly completionTokens: Schema.optional<Schema.Int>;
+        readonly totalTokens: Schema.optional<Schema.Int>;
     }>>;
 }>, import("../../Cause.ts").YieldableError>;
 /**
@@ -696,7 +689,7 @@ declare const StructuredOutputError_base: Schema.Class<StructuredOutputError, Sc
  *
  * **Example** (Creating a structured output error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.StructuredOutputError({
@@ -704,12 +697,10 @@ declare const StructuredOutputError_base: Schema.Class<StructuredOutputError, Sc
  *   responseText: "{\"foo\":}"
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Structured output validation failed: Expected a valid JSON object"
+ * const result = [error.description, error.responseText, error.isRetryable] // => ["Expected a valid JSON object", '{"foo":}', true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class StructuredOutputError extends StructuredOutputError_base {
@@ -730,14 +721,15 @@ export declare class StructuredOutputError extends StructuredOutputError_base {
      *
      * **Example** (Creating a structured output error from a schema error)
      *
-     * ```ts
-     * import { Schema } from "effect"
+     * ```ts import.meta.vitest
+     * import { Effect, Schema } from "effect"
      * import { AiError } from "effect/unstable/ai"
      *
-     * declare const schemaError: Schema.SchemaError
-     * declare const rawText: string
-     *
-     * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError, rawText)
+     * const schemaError = await Effect.runPromise(
+     *   Schema.decodeUnknownEffect(Schema.Struct({ name: Schema.String }))({}).pipe(Effect.flip)
+     * )
+     * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError, "{}")
+     * parseError.responseText // => "{}"
      * ```
      *
      * @since 4.0.0
@@ -761,19 +753,17 @@ declare const UnsupportedSchemaError_base: Schema.Class<UnsupportedSchemaError,
  *
  * **Example** (Creating an unsupported schema error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.UnsupportedSchemaError({
  *   description: "Unions are not supported in Anthropic structured output"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Unsupported schema: Unions are not supported in Anthropic structured output"
+ * const result = [error.description, error.isRetryable] // => ["Unions are not supported in Anthropic structured output", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class UnsupportedSchemaError extends UnsupportedSchemaError_base {
@@ -800,11 +790,11 @@ declare const UnknownError_base: Schema.Class<UnknownError, Schema.Struct<{
             readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
             readonly url: Schema.String;
             readonly urlParams: Schema.$Array<Schema.Tuple<readonly [Schema.String, Schema.String]>>;
-            readonly hash: Schema.UndefinedOr<Schema.String>;
+            readonly hash: Schema.optional<Schema.String>;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>;
         readonly response: Schema.optional<Schema.Struct<{
-            readonly status: Schema.Number;
+            readonly status: Schema.Int;
             readonly headers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Redacted<Schema.String>]>>;
         }>>;
         readonly body: Schema.optional<Schema.String>;
@@ -819,19 +809,17 @@ declare const UnknownError_base: Schema.Class<UnknownError, Schema.Struct<{
  *
  * **Example** (Creating an unknown error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const unknownError = new AiError.UnknownError({
  *   description: "An unexpected error occurred"
  * })
  *
- * console.log(unknownError.isRetryable) // false
- * console.log(unknownError.message)
- * // "An unexpected error occurred"
+ * const result = [unknownError.description, unknownError.isRetryable] // => ["An unexpected error occurred", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class UnknownError extends UnknownError_base {
@@ -864,7 +852,7 @@ declare const ToolNotFoundError_base: Schema.Class<ToolNotFoundError, Schema.Str
  *
  * **Example** (Creating a tool not found error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolNotFoundError({
@@ -872,12 +860,10 @@ declare const ToolNotFoundError_base: Schema.Class<ToolNotFoundError, Schema.Str
  *   availableTools: ["GetWeather", "GetTime"]
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Tool 'unknownTool' not found. Available tools: GetWeather, GetTime"
+ * const result = [error.toolName, error.availableTools, error.isRetryable] // => ["unknownTool", ["GetWeather", "GetTime"], true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class ToolNotFoundError extends ToolNotFoundError_base {
@@ -911,7 +897,7 @@ declare const ToolParameterValidationError_base: Schema.Class<ToolParameterValid
  *
  * **Example** (Creating a tool parameter validation error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolParameterValidationError({
@@ -920,12 +906,10 @@ declare const ToolParameterValidationError_base: Schema.Class<ToolParameterValid
  *   description: "Expected string, got number"
  * })
  *
- * console.log(error.isRetryable) // true
- * console.log(error.message)
- * // "Invalid parameters for tool 'GetWeather': Expected string, got number"
+ * const result = [error.toolName, error.description, error.isRetryable] // => ["GetWeather", "Expected string, got number", true]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class ToolParameterValidationError extends ToolParameterValidationError_base {
@@ -959,7 +943,7 @@ declare const InvalidToolResultError_base: Schema.Class<InvalidToolResultError,
  *
  * **Example** (Creating an invalid tool result error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidToolResultError({
@@ -967,12 +951,10 @@ declare const InvalidToolResultError_base: Schema.Class<InvalidToolResultError,
  *   description: "Tool handler returned invalid result: missing 'temperature' field"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Tool 'GetWeather' returned invalid result: missing 'temperature' field"
+ * const result = [error.toolName, error.isRetryable] // => ["GetWeather", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class InvalidToolResultError extends InvalidToolResultError_base {
@@ -1006,7 +988,7 @@ declare const ToolResultEncodingError_base: Schema.Class<ToolResultEncodingError
  *
  * **Example** (Creating a tool result encoding error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolResultEncodingError({
@@ -1015,12 +997,10 @@ declare const ToolResultEncodingError_base: Schema.Class<ToolResultEncodingError
  *   description: "Cannot encode bigint values as JSON"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Failed to encode result for tool 'GetWeather': Cannot encode bigint values as JSON"
+ * const result = [error.toolName, error.description, error.isRetryable] // => ["GetWeather", "Cannot encode bigint values as JSON", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class ToolResultEncodingError extends ToolResultEncodingError_base {
@@ -1053,7 +1033,7 @@ declare const ToolConfigurationError_base: Schema.Class<ToolConfigurationError,
  *
  * **Example** (Creating a tool configuration error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolConfigurationError({
@@ -1061,12 +1041,10 @@ declare const ToolConfigurationError_base: Schema.Class<ToolConfigurationError,
  *   description: "Invalid container ID format"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Invalid configuration for tool 'OpenAiCodeInterpreter': Invalid container ID format"
+ * const result = [error.toolName, error.description, error.isRetryable] // => ["OpenAiCodeInterpreter", "Invalid container ID format", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class ToolConfigurationError extends ToolConfigurationError_base {
@@ -1099,19 +1077,17 @@ declare const ToolkitRequiredError_base: Schema.Class<ToolkitRequiredError, Sche
  *
  * **Example** (Creating a toolkit required error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolkitRequiredError({
  *   pendingApprovals: ["GetWeather", "SendEmail"]
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Toolkit required to resolve pending tool approvals: GetWeather, SendEmail"
+ * const result = [error.pendingApprovals, error.isRetryable] // => [["GetWeather", "SendEmail"], false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class ToolkitRequiredError extends ToolkitRequiredError_base {
@@ -1144,19 +1120,17 @@ declare const InvalidUserInputError_base: Schema.Class<InvalidUserInputError, Sc
  *
  * **Example** (Creating an invalid user input error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidUserInputError({
  *   description: "Unsupported media type 'video/mp4'. Supported types include images, application/pdf, text/plain"
  * })
  *
- * console.log(error.isRetryable) // false
- * console.log(error.message)
- * // "Invalid user input: Unsupported media type 'video/mp4'. Supported types include images, application/pdf, text/plain"
+ * const result = [error._tag, error.isRetryable] // => ["InvalidUserInputError", false]
  * ```
  *
- * @category reason
+ * @category errors
  * @since 4.0.0
  */
 export declare class InvalidUserInputError extends InvalidUserInputError_base {
@@ -1183,7 +1157,7 @@ export declare class InvalidUserInputError extends InvalidUserInputError_base {
  * `isRetryable` getter. Provider-facing reasons may also include retry timing,
  * provider metadata, usage information, or HTTP context.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export type AiErrorReason = RateLimitError | QuotaExhaustedError | AuthenticationError | ContentPolicyError | InvalidRequestError | InternalProviderError | NetworkError | InvalidOutputError | StructuredOutputError | UnsupportedSchemaError | UnknownError | ToolNotFoundError | ToolParameterValidationError | InvalidToolResultError | ToolResultEncodingError | ToolConfigurationError | ToolkitRequiredError | InvalidUserInputError;
@@ -1245,11 +1219,15 @@ declare const AiError_base: Schema.Class<AiError, Schema.Struct<{
  *
  * **Example** (Handling an AI error by tag)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Duration, Effect } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
- * declare const aiOperation: Effect.Effect<string, AiError.AiError>
+ * const aiOperation = Effect.fail(new AiError.AiError({
+ *   module: "OpenAI",
+ *   method: "generateText",
+ *   reason: new AiError.RateLimitError({ retryAfter: Duration.seconds(30) })
+ * }))
  *
  * // Handle specific reason types
  * const handled = aiOperation.pipe(
@@ -1260,6 +1238,8 @@ declare const AiError_base: Schema.Class<AiError, Schema.Struct<{
  *     return Effect.fail(error)
  *   })
  * )
+ *
+ * await Effect.runPromise(handled) // => "Retry after 30000 millis"
  * ```
  *
  * @category schemas
@@ -1294,7 +1274,7 @@ export type AiErrorEncoded = typeof AiError["Encoded"];
  *
  * **Example** (Checking for an AI error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const someError = new Error("generic error")
@@ -1304,8 +1284,7 @@ export type AiErrorEncoded = typeof AiError["Encoded"];
  *   reason: new AiError.RateLimitError({})
  * })
  *
- * console.log(AiError.isAiError(someError)) // false
- * console.log(AiError.isAiError(aiError)) // true
+ * const result = [AiError.isAiError(someError), AiError.isAiError(aiError)] // => [false, true]
  * ```
  *
  * @category guards
@@ -1317,14 +1296,13 @@ export declare const isAiError: (u: unknown) => u is AiError;
  *
  * **Example** (Checking for an AI error reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const rateLimitError = new AiError.RateLimitError({})
  * const genericError = new Error("generic error")
  *
- * console.log(AiError.isAiErrorReason(rateLimitError)) // true
- * console.log(AiError.isAiErrorReason(genericError)) // false
+ * const result = [AiError.isAiErrorReason(rateLimitError), AiError.isAiErrorReason(genericError)] // => [true, false]
  * ```
  *
  * @category guards
@@ -1336,7 +1314,7 @@ export declare const isAiErrorReason: (u: unknown) => u is AiErrorReason;
  *
  * **Example** (Creating an AI error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1348,8 +1326,7 @@ export declare const isAiErrorReason: (u: unknown) => u is AiErrorReason;
  *   })
  * })
  *
- * console.log(error.message)
- * // "OpenAI.completion: Rate limit exceeded. Retry after 1 minute"
+ * const result = [error.module, error.method, error.reason._tag] // => ["OpenAI", "completion", "RateLimitError"]
  * ```
  *
  * @category constructors
@@ -1370,7 +1347,7 @@ export declare const make: (params: {
  *
  * **Example** (Mapping an HTTP status to a reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const reason = AiError.reasonFromHttpStatus({
@@ -1378,7 +1355,7 @@ export declare const make: (params: {
  *   body: { error: "Rate limit exceeded" }
  * })
  *
- * console.log(reason._tag) // "RateLimitError"
+ * reason._tag // => "RateLimitError"
  * ```
  *
  * @category constructors