effect 4.0.0-beta.98 → 4.0.0-rc.108

package/src/unstable/ai/AiError.ts

@@ -13,6 +13,7 @@
  */
 import * as Duration from "../../Duration.ts"
 import * as Effect from "../../Effect.ts"
+import * as InternalRecord from "../../internal/record.ts"
 import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import { redact } from "../../Redactable.ts"
@@ -34,7 +35,7 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
   const result: Record<string, string> = {}
   for (const key in redacted) {
     const value = redacted[key]
-    result[key] = Redacted.isRedacted(value) ? value.toString() : value
+    InternalRecord.assignProperty(result, key, Redacted.isRedacted(value) ? value.toString() : value)
   }
   return result
 }
@@ -54,7 +55,7 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  *
  * **Example** (Creating a network error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.NetworkError({
@@ -69,15 +70,13 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  *   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 class NetworkError extends Schema.ErrorClass<NetworkError>(
+export class NetworkError extends Schema.Error<NetworkError>(
   "effect/ai/AiError/NetworkError"
 )({
   _tag: Schema.tag("NetworkError"),
@@ -106,13 +105,17 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
    *
    * **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
@@ -183,7 +186,7 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
  *
  * **Example** (Inspecting metadata shape)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * const metadata = {
  *   openai: {
  *     errorCode: "rate_limit_exceeded",
@@ -191,6 +194,8 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
  *   },
  *   anthropic: null
  * }
+ *
+ * Array.of(metadata.openai.errorCode, metadata.anthropic) // => ["rate_limit_exceeded", null]
  * ```
  *
  * @category schemas
@@ -306,9 +311,9 @@ export interface UnknownErrorMetadata extends ProviderMetadata {}
  * @since 4.0.0
  */
 export const UsageInfo = Schema.Struct({
-  promptTokens: Schema.optional(Schema.Number),
-  completionTokens: Schema.optional(Schema.Number),
-  totalTokens: Schema.optional(Schema.Number)
+  promptTokens: Schema.optional(Schema.Int),
+  completionTokens: Schema.optional(Schema.Int),
+  totalTokens: Schema.optional(Schema.Int)
 }).annotate({ identifier: "UsageInfo" })
 
 /**
@@ -350,7 +355,7 @@ export const HttpContext = Schema.Struct({
  *
  * **Example** (Creating a rate limit error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -358,14 +363,13 @@ export const HttpContext = 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 class RateLimitError extends Schema.ErrorClass<RateLimitError>(
+export class RateLimitError extends Schema.Error<RateLimitError>(
   "effect/ai/AiError/RateLimitError"
 )({
   _tag: Schema.tag("RateLimitError"),
@@ -405,20 +409,18 @@ export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
  *
  * **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 class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
+export class QuotaExhaustedError extends Schema.Error<QuotaExhaustedError>(
   "effect/ai/AiError/QuotaExhaustedError"
 )({
   _tag: Schema.tag("QuotaExhaustedError"),
@@ -458,22 +460,20 @@ export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
  *
  * **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 class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
+export class AuthenticationError extends Schema.Error<AuthenticationError>(
   "effect/ai/AiError/AuthenticationError"
 )({
   _tag: Schema.tag("AuthenticationError"),
@@ -518,22 +518,20 @@ export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
  *
  * **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 class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
+export class ContentPolicyError extends Schema.Error<ContentPolicyError>(
   "effect/ai/AiError/ContentPolicyError"
 )({
   _tag: Schema.tag("ContentPolicyError"),
@@ -571,7 +569,7 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
  *
  * **Example** (Creating an invalid request error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const invalidRequestError = new AiError.InvalidRequestError({
@@ -580,15 +578,13 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
  *   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 class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
+export class InvalidRequestError extends Schema.Error<InvalidRequestError>(
   "effect/ai/AiError/InvalidRequestError"
 )({
   _tag: Schema.tag("InvalidRequestError"),
@@ -632,22 +628,20 @@ export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
  *
  * **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 class InternalProviderError extends Schema.ErrorClass<InternalProviderError>(
+export class InternalProviderError extends Schema.Error<InternalProviderError>(
   "effect/ai/AiError/InternalProviderError"
 )({
   _tag: Schema.tag("InternalProviderError"),
@@ -685,22 +679,20 @@ export class InternalProviderError extends Schema.ErrorClass<InternalProviderErr
  *
  * **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 class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
+export class InvalidOutputError extends Schema.Error<InvalidOutputError>(
   "effect/ai/AiError/InvalidOutputError"
 )({
   _tag: Schema.tag("InvalidOutputError"),
@@ -729,13 +721,15 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
    *
    * **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
@@ -761,7 +755,7 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  *
  * **Example** (Creating a structured output error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.StructuredOutputError({
@@ -769,15 +763,13 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  *   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 class StructuredOutputError extends Schema.ErrorClass<StructuredOutputError>(
+export class StructuredOutputError extends Schema.Error<StructuredOutputError>(
   "effect/ai/AiError/StructuredOutputError"
 )({
   _tag: Schema.tag("StructuredOutputError"),
@@ -807,14 +799,15 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
    *
    * **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
@@ -842,22 +835,20 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
  *
  * **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 class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaError>(
+export class UnsupportedSchemaError extends Schema.Error<UnsupportedSchemaError>(
   "effect/ai/AiError/UnsupportedSchemaError"
 )({
   _tag: Schema.tag("UnsupportedSchemaError"),
@@ -894,22 +885,20 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
  *
  * **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 class UnknownError extends Schema.ErrorClass<UnknownError>(
+export class UnknownError extends Schema.Error<UnknownError>(
   "effect/ai/AiError/UnknownError"
 )({
   _tag: Schema.tag("UnknownError"),
@@ -952,7 +941,7 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
  *
  * **Example** (Creating a tool not found error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolNotFoundError({
@@ -960,15 +949,13 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
  *   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 class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
+export class ToolNotFoundError extends Schema.Error<ToolNotFoundError>(
   "effect/ai/AiError/ToolNotFoundError"
 )({
   _tag: Schema.tag("ToolNotFoundError"),
@@ -1007,7 +994,7 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
  *
  * **Example** (Creating a tool parameter validation error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolParameterValidationError({
@@ -1016,15 +1003,13 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
  *   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 class ToolParameterValidationError extends Schema.ErrorClass<ToolParameterValidationError>(
+export class ToolParameterValidationError extends Schema.Error<ToolParameterValidationError>(
   "effect/ai/AiError/ToolParameterValidationError"
 )({
   _tag: Schema.tag("ToolParameterValidationError"),
@@ -1064,7 +1049,7 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  *
  * **Example** (Creating an invalid tool result error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidToolResultError({
@@ -1072,15 +1057,13 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  *   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 class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultError>(
+export class InvalidToolResultError extends Schema.Error<InvalidToolResultError>(
   "effect/ai/AiError/InvalidToolResultError"
 )({
   _tag: Schema.tag("InvalidToolResultError"),
@@ -1118,7 +1101,7 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
  *
  * **Example** (Creating a tool result encoding error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolResultEncodingError({
@@ -1127,15 +1110,13 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
  *   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 class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodingError>(
+export class ToolResultEncodingError extends Schema.Error<ToolResultEncodingError>(
   "effect/ai/AiError/ToolResultEncodingError"
 )({
   _tag: Schema.tag("ToolResultEncodingError"),
@@ -1174,7 +1155,7 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
  *
  * **Example** (Creating a tool configuration error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolConfigurationError({
@@ -1182,15 +1163,13 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
  *   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 class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationError>(
+export class ToolConfigurationError extends Schema.Error<ToolConfigurationError>(
   "effect/ai/AiError/ToolConfigurationError"
 )({
   _tag: Schema.tag("ToolConfigurationError"),
@@ -1228,22 +1207,20 @@ export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationE
  *
  * **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 class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError>(
+export class ToolkitRequiredError extends Schema.Error<ToolkitRequiredError>(
   "effect/ai/AiError/ToolkitRequiredError"
 )({
   _tag: Schema.tag("ToolkitRequiredError"),
@@ -1283,22 +1260,20 @@ export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError
  *
  * **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 class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputError>(
+export class InvalidUserInputError extends Schema.Error<InvalidUserInputError>(
   "effect/ai/AiError/InvalidUserInputError"
 )({
   _tag: Schema.tag("InvalidUserInputError"),
@@ -1338,7 +1313,7 @@ export class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputErr
  * `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 =
@@ -1438,11 +1413,15 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
  *
  * **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(
@@ -1453,12 +1432,14 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
  *     return Effect.fail(error)
  *   })
  * )
+ *
+ * await Effect.runPromise(handled) // => "Retry after 30000 millis"
  * ```
  *
  * @category schemas
  * @since 4.0.0
  */
-export class AiError extends Schema.ErrorClass<AiError>(
+export class AiError extends Schema.Error<AiError>(
   "effect/ai/AiError/AiError"
 )({
   _tag: Schema.tag("AiError"),
@@ -1505,7 +1486,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")
@@ -1515,8 +1496,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
@@ -1529,14 +1509,13 @@ export const isAiError = (u: unknown): u is AiError => Predicate.hasProperty(u,
  *
  * **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
@@ -1549,7 +1528,7 @@ export const isAiErrorReason = (u: unknown): u is AiErrorReason => Predicate.has
  *
  * **Example** (Creating an AI error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1561,8 +1540,7 @@ export const isAiErrorReason = (u: unknown): u is AiErrorReason => Predicate.has
  *   })
  * })
  *
- * 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
@@ -1584,7 +1562,7 @@ export 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({
@@ -1592,7 +1570,7 @@ export const make = (params: {
  *   body: { error: "Rate limit exceeded" }
  * })
  *
- * console.log(reason._tag) // "RateLimitError"
+ * reason._tag // => "RateLimitError"
  * ```
  *
  * @category constructors