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

package/dist/unstable/ai/AiError.js

@@ -13,6 +13,7 @@
  */
 import * as Duration from "../../Duration.js";
 import * as Effect from "../../Effect.js";
+import * as InternalRecord from "../../internal/record.js";
 import * as Option from "../../Option.js";
 import * as Predicate from "../../Predicate.js";
 import { redact } from "../../Redactable.js";
@@ -26,7 +27,7 @@ const redactHeaders = headers => {
   const result = {};
   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;
 };
@@ -44,7 +45,7 @@ const redactHeaders = headers => {
  *
  * **Example** (Creating a network error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.NetworkError({
@@ -59,15 +60,13 @@ const redactHeaders = headers => {
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/NetworkError")({
+export class NetworkError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/NetworkError")({
   _tag: /*#__PURE__*/Schema.tag("NetworkError"),
   reason: /*#__PURE__*/Schema.Literals(["TransportError", "EncodeError", "InvalidUrlError"]),
   request: HttpRequestDetails,
@@ -92,13 +91,17 @@ export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
    *
    * **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
@@ -159,7 +162,7 @@ export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
  *
  * **Example** (Inspecting metadata shape)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * const metadata = {
  *   openai: {
  *     errorCode: "rate_limit_exceeded",
@@ -167,6 +170,8 @@ export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
  *   },
  *   anthropic: null
  * }
+ *
+ * Array.of(metadata.openai.errorCode, metadata.anthropic) // => ["rate_limit_exceeded", null]
  * ```
  *
  * @category schemas
@@ -185,9 +190,9 @@ export const ProviderMetadata = /*#__PURE__*/Schema.Record(Schema.String, /*#__P
  * @since 4.0.0
  */
 export const UsageInfo = /*#__PURE__*/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"
 });
@@ -230,7 +235,7 @@ export const HttpContext = /*#__PURE__*/Schema.Struct({
  *
  * **Example** (Creating a rate limit error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -238,14 +243,13 @@ export const HttpContext = /*#__PURE__*/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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/RateLimitError")({
+export class RateLimitError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/RateLimitError")({
   _tag: /*#__PURE__*/Schema.tag("RateLimitError"),
   retryAfter: /*#__PURE__*/Schema.optional(Schema.Duration),
   metadata: /*#__PURE__*/providerMetadataWithDefaults(),
@@ -280,20 +284,18 @@ export class RateLimitError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Ai
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/QuotaExhaustedError")({
+export class QuotaExhaustedError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/QuotaExhaustedError")({
   _tag: /*#__PURE__*/Schema.tag("QuotaExhaustedError"),
   resetAt: /*#__PURE__*/Schema.optional(Schema.DateTimeUtc),
   metadata: /*#__PURE__*/providerMetadataWithDefaults(),
@@ -328,22 +330,20 @@ export class QuotaExhaustedError extends /*#__PURE__*/Schema.ErrorClass("effect/
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/AuthenticationError")({
+export class AuthenticationError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/AuthenticationError")({
   _tag: /*#__PURE__*/Schema.tag("AuthenticationError"),
   kind: /*#__PURE__*/Schema.Literals(["InvalidKey", "ExpiredKey", "MissingKey", "InsufficientPermissions", "Unknown"]),
   metadata: /*#__PURE__*/providerMetadataWithDefaults(),
@@ -383,22 +383,20 @@ export class AuthenticationError extends /*#__PURE__*/Schema.ErrorClass("effect/
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ContentPolicyError")({
+export class ContentPolicyError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/ContentPolicyError")({
   _tag: /*#__PURE__*/Schema.tag("ContentPolicyError"),
   description: Schema.String,
   metadata: /*#__PURE__*/providerMetadataWithDefaults(),
@@ -431,7 +429,7 @@ export class ContentPolicyError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  *
  * **Example** (Creating an invalid request error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const invalidRequestError = new AiError.InvalidRequestError({
@@ -440,15 +438,13 @@ export class ContentPolicyError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidRequestError")({
+export class InvalidRequestError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/InvalidRequestError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidRequestError"),
   parameter: /*#__PURE__*/Schema.optional(Schema.String),
   constraint: /*#__PURE__*/Schema.optional(Schema.String),
@@ -487,22 +483,20 @@ export class InvalidRequestError extends /*#__PURE__*/Schema.ErrorClass("effect/
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InternalProviderError")({
+export class InternalProviderError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/InternalProviderError")({
   _tag: /*#__PURE__*/Schema.tag("InternalProviderError"),
   description: Schema.String,
   metadata: /*#__PURE__*/providerMetadataWithDefaults(),
@@ -535,22 +529,20 @@ export class InternalProviderError extends /*#__PURE__*/Schema.ErrorClass("effec
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidOutputError")({
+export class InvalidOutputError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/InvalidOutputError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidOutputError"),
   description: Schema.String,
   metadata: /*#__PURE__*/providerMetadataWithDefaults(),
@@ -575,13 +567,15 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
    *
    * **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
@@ -605,7 +599,7 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  *
  * **Example** (Creating a structured output error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.StructuredOutputError({
@@ -613,15 +607,13 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/StructuredOutputError")({
+export class StructuredOutputError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/StructuredOutputError")({
   _tag: /*#__PURE__*/Schema.tag("StructuredOutputError"),
   description: Schema.String,
   responseText: Schema.String,
@@ -647,14 +639,15 @@ export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effec
    *
    * **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
@@ -680,22 +673,20 @@ export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effec
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/UnsupportedSchemaError")({
+export class UnsupportedSchemaError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/UnsupportedSchemaError")({
   _tag: /*#__PURE__*/Schema.tag("UnsupportedSchemaError"),
   description: Schema.String,
   metadata: /*#__PURE__*/providerMetadataWithDefaults()
@@ -727,22 +718,20 @@ export class UnsupportedSchemaError extends /*#__PURE__*/Schema.ErrorClass("effe
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/UnknownError")({
+export class UnknownError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/UnknownError")({
   _tag: /*#__PURE__*/Schema.tag("UnknownError"),
   description: /*#__PURE__*/Schema.optional(Schema.String),
   metadata: /*#__PURE__*/providerMetadataWithDefaults(),
@@ -779,7 +768,7 @@ export class UnknownError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
  *
  * **Example** (Creating a tool not found error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolNotFoundError({
@@ -787,15 +776,13 @@ export class UnknownError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolNotFoundError")({
+export class ToolNotFoundError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/ToolNotFoundError")({
   _tag: /*#__PURE__*/Schema.tag("ToolNotFoundError"),
   toolName: Schema.String,
   availableTools: /*#__PURE__*/Schema.Array(Schema.String)
@@ -829,7 +816,7 @@ export class ToolNotFoundError extends /*#__PURE__*/Schema.ErrorClass("effect/ai
  *
  * **Example** (Creating a tool parameter validation error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolParameterValidationError({
@@ -838,15 +825,13 @@ export class ToolNotFoundError extends /*#__PURE__*/Schema.ErrorClass("effect/ai
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolParameterValidationError")({
+export class ToolParameterValidationError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/ToolParameterValidationError")({
   _tag: /*#__PURE__*/Schema.tag("ToolParameterValidationError"),
   toolName: Schema.String,
   toolParams: Schema.Json,
@@ -881,7 +866,7 @@ export class ToolParameterValidationError extends /*#__PURE__*/Schema.ErrorClass
  *
  * **Example** (Creating an invalid tool result error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidToolResultError({
@@ -889,15 +874,13 @@ export class ToolParameterValidationError extends /*#__PURE__*/Schema.ErrorClass
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidToolResultError")({
+export class InvalidToolResultError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/InvalidToolResultError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidToolResultError"),
   toolName: Schema.String,
   description: Schema.String
@@ -930,7 +913,7 @@ export class InvalidToolResultError extends /*#__PURE__*/Schema.ErrorClass("effe
  *
  * **Example** (Creating a tool result encoding error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolResultEncodingError({
@@ -939,15 +922,13 @@ export class InvalidToolResultError extends /*#__PURE__*/Schema.ErrorClass("effe
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolResultEncodingError")({
+export class ToolResultEncodingError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/ToolResultEncodingError")({
   _tag: /*#__PURE__*/Schema.tag("ToolResultEncodingError"),
   toolName: Schema.String,
   toolResult: Schema.Unknown,
@@ -981,7 +962,7 @@ export class ToolResultEncodingError extends /*#__PURE__*/Schema.ErrorClass("eff
  *
  * **Example** (Creating a tool configuration error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolConfigurationError({
@@ -989,15 +970,13 @@ export class ToolResultEncodingError extends /*#__PURE__*/Schema.ErrorClass("eff
  *   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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolConfigurationError")({
+export class ToolConfigurationError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/ToolConfigurationError")({
   _tag: /*#__PURE__*/Schema.tag("ToolConfigurationError"),
   toolName: Schema.String,
   description: Schema.String
@@ -1030,22 +1009,20 @@ export class ToolConfigurationError extends /*#__PURE__*/Schema.ErrorClass("effe
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolkitRequiredError")({
+export class ToolkitRequiredError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/ToolkitRequiredError")({
   _tag: /*#__PURE__*/Schema.tag("ToolkitRequiredError"),
   pendingApprovals: /*#__PURE__*/Schema.Array(Schema.String),
   description: /*#__PURE__*/Schema.optional(Schema.String)
@@ -1080,22 +1057,20 @@ export class ToolkitRequiredError extends /*#__PURE__*/Schema.ErrorClass("effect
  *
  * **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 /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidUserInputError")({
+export class InvalidUserInputError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/InvalidUserInputError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidUserInputError"),
   description: Schema.String
 }) {
@@ -1153,11 +1128,15 @@ const TypeId = "~effect/unstable/ai/AiError/AiError";
  *
  * **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(
@@ -1168,12 +1147,14 @@ const TypeId = "~effect/unstable/ai/AiError/AiError";
  *     return Effect.fail(error)
  *   })
  * )
+ *
+ * await Effect.runPromise(handled) // => "Retry after 30000 millis"
  * ```
  *
  * @category schemas
  * @since 4.0.0
  */
-export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/AiError")({
+export class AiError extends /*#__PURE__*/Schema.Error("effect/ai/AiError/AiError")({
   _tag: /*#__PURE__*/Schema.tag("AiError"),
   module: Schema.String,
   method: Schema.String,
@@ -1206,7 +1187,7 @@ export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/A
  *
  * **Example** (Checking for an AI error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const someError = new Error("generic error")
@@ -1216,8 +1197,7 @@ export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/A
  *   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
@@ -1229,14 +1209,13 @@ export const isAiError = u => Predicate.hasProperty(u, TypeId);
  *
  * **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
@@ -1248,7 +1227,7 @@ export const isAiErrorReason = u => Predicate.hasProperty(u, ReasonTypeId);
  *
  * **Example** (Creating an AI error)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1260,8 +1239,7 @@ export const isAiErrorReason = u => Predicate.hasProperty(u, ReasonTypeId);
  *   })
  * })
  *
- * 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
@@ -1278,7 +1256,7 @@ export const make = params => new AiError(params);
  *
  * **Example** (Mapping an HTTP status to a reason)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { AiError } from "effect/unstable/ai"
  *
  * const reason = AiError.reasonFromHttpStatus({
@@ -1286,7 +1264,7 @@ export const make = params => new AiError(params);
  *   body: { error: "Rate limit exceeded" }
  * })
  *
- * console.log(reason._tag) // "RateLimitError"
+ * reason._tag // => "RateLimitError"
  * ```
  *
  * @category constructors