effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/unstable/ai/AiError.js

@@ -35,7 +35,8 @@
  * Each reason type has an `isRetryable` getter indicating whether the error is
  * transient. Some errors also provide a `retryAfter` duration hint.
  *
- * @example
+ * **Example** (Handling AI errors by reason)
+ *
  * ```ts
  * import { Effect, Match } from "effect"
  * import type { AiError } from "effect/unstable/ai"
@@ -58,7 +59,8 @@
  * )
  * ```
  *
- * @example
+ * **Example** (Creating an AI error with a reason)
+ *
  * ```ts
  * import { Duration, Effect } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -76,7 +78,7 @@
  * console.log(error.message) // "OpenAI.completion: Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Duration from "../../Duration.js";
 import * as Effect from "../../Effect.js";
@@ -107,7 +109,8 @@ const redactHeaders = headers => {
  * such as network connectivity problems, request encoding issues, or invalid
  * URLs.
  *
- * @example
+ * **Example** (Creating a network error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -128,8 +131,8 @@ const redactHeaders = headers => {
  * // "Transport: Connection timeout after 30 seconds (POST https://api.openai.com/v1/completions)"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/NetworkError")({
   _tag: /*#__PURE__*/Schema.tag("NetworkError"),
@@ -138,13 +141,15 @@ export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
   description: /*#__PURE__*/Schema.optional(Schema.String)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `NetworkError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Transport errors are retryable; encoding and URL errors are not.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return this.reason === "TransportError";
@@ -152,7 +157,8 @@ export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
   /**
    * Creates a NetworkError from a platform HttpClientError.RequestError.
    *
-   * @example
+   * **Example** (Creating a network error from a request error)
+   *
    * ```ts
    * import { AiError } from "effect/unstable/ai"
    * import type { HttpClientError } from "effect/unstable/http"
@@ -162,8 +168,7 @@ export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
    * const aiError = AiError.NetworkError.fromRequestError(platformError)
    * ```
    *
-   * @since 1.0.0
-   * @category constructors
+   * @since 4.0.0
    */
   static fromRequestError(error) {
     return new NetworkError({
@@ -224,15 +229,15 @@ export class NetworkError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
  * }
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ProviderMetadata = /*#__PURE__*/Schema.Record(Schema.String, /*#__PURE__*/Schema.NullOr(Schema.MutableJson));
 /**
  * Token usage information from AI operations.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const UsageInfo = /*#__PURE__*/Schema.Struct({
   promptTokens: Schema.optional(Schema.Number),
@@ -244,8 +249,8 @@ export const UsageInfo = /*#__PURE__*/Schema.Struct({
 /**
  * Combined HTTP context for error reporting.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const HttpContext = /*#__PURE__*/Schema.Struct({
   request: HttpRequestDetails,
@@ -263,7 +268,8 @@ export const HttpContext = /*#__PURE__*/Schema.Struct({
  * Rate limit errors are always retryable. When `retryAfter` is provided,
  * callers should wait that duration before retrying.
  *
- * @example
+ * **Example** (Creating a rate limit error)
+ *
  * ```ts
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -276,8 +282,8 @@ export const HttpContext = /*#__PURE__*/Schema.Struct({
  * console.log(rateLimitError.message) // "Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class RateLimitError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/RateLimitError")({
   _tag: /*#__PURE__*/Schema.tag("RateLimitError"),
@@ -286,13 +292,15 @@ export class RateLimitError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Ai
   http: /*#__PURE__*/Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `RateLimitError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Rate limit errors are always retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return true;
@@ -308,7 +316,8 @@ export class RateLimitError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Ai
  *
  * Quota exhausted errors are not retryable without user action.
  *
- * @example
+ * **Example** (Creating a quota exhausted error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -319,8 +328,8 @@ export class RateLimitError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/Ai
  * // "Quota exhausted. Check your account billing and usage limits."
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class QuotaExhaustedError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/QuotaExhaustedError")({
   _tag: /*#__PURE__*/Schema.tag("QuotaExhaustedError"),
@@ -329,13 +338,15 @@ export class QuotaExhaustedError extends /*#__PURE__*/Schema.ErrorClass("effect/
   http: /*#__PURE__*/Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `QuotaExhaustedError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Quota exhausted errors require user action and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -351,7 +362,8 @@ export class QuotaExhaustedError extends /*#__PURE__*/Schema.ErrorClass("effect/
  *
  * Authentication errors are never retryable without credential changes.
  *
- * @example
+ * **Example** (Creating an authentication error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -364,8 +376,8 @@ export class QuotaExhaustedError extends /*#__PURE__*/Schema.ErrorClass("effect/
  * // "InvalidKey: Verify your API key is correct"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class AuthenticationError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/AuthenticationError")({
   _tag: /*#__PURE__*/Schema.tag("AuthenticationError"),
@@ -374,13 +386,15 @@ export class AuthenticationError extends /*#__PURE__*/Schema.ErrorClass("effect/
   http: /*#__PURE__*/Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `AuthenticationError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Authentication errors require credential changes and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -401,7 +415,8 @@ export class AuthenticationError extends /*#__PURE__*/Schema.ErrorClass("effect/
  *
  * Content policy errors are never retryable without content changes.
  *
- * @example
+ * **Example** (Creating a content policy error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -414,8 +429,8 @@ export class AuthenticationError extends /*#__PURE__*/Schema.ErrorClass("effect/
  * // "Content policy violation: Input contains prohibited content"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ContentPolicyError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ContentPolicyError")({
   _tag: /*#__PURE__*/Schema.tag("ContentPolicyError"),
@@ -424,13 +439,15 @@ export class ContentPolicyError extends /*#__PURE__*/Schema.ErrorClass("effect/a
   http: /*#__PURE__*/Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ContentPolicyError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Content policy errors require content changes and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -444,7 +461,8 @@ export class ContentPolicyError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  *
  * Invalid request errors require fixing the request and are not retryable.
  *
- * @example
+ * **Example** (Creating an invalid request error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -459,8 +477,8 @@ export class ContentPolicyError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  * // "Invalid request: parameter 'temperature' must be between 0 and 2. Temperature value 5 is out of range"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InvalidRequestError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidRequestError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidRequestError"),
@@ -471,13 +489,15 @@ export class InvalidRequestError extends /*#__PURE__*/Schema.ErrorClass("effect/
   http: /*#__PURE__*/Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidRequestError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Invalid request errors require fixing the request and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -495,7 +515,8 @@ export class InvalidRequestError extends /*#__PURE__*/Schema.ErrorClass("effect/
  *
  * Internal provider errors are typically transient and are retryable.
  *
- * @example
+ * **Example** (Creating an internal provider error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -508,8 +529,8 @@ export class InvalidRequestError extends /*#__PURE__*/Schema.ErrorClass("effect/
  * // "Internal provider error: Server encountered an unexpected error"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InternalProviderError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InternalProviderError")({
   _tag: /*#__PURE__*/Schema.tag("InternalProviderError"),
@@ -518,13 +539,15 @@ export class InternalProviderError extends /*#__PURE__*/Schema.ErrorClass("effec
   http: /*#__PURE__*/Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InternalProviderError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Internal provider errors are typically transient and are retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return true;
@@ -538,7 +561,8 @@ export class InternalProviderError extends /*#__PURE__*/Schema.ErrorClass("effec
  *
  * Invalid output errors are retryable since LLM outputs are non-deterministic.
  *
- * @example
+ * **Example** (Creating an invalid output error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -551,8 +575,8 @@ export class InternalProviderError extends /*#__PURE__*/Schema.ErrorClass("effec
  * // "Invalid output: Expected a string but received a number"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidOutputError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidOutputError"),
@@ -561,13 +585,15 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
   usage: /*#__PURE__*/Schema.optional(UsageInfo)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidOutputError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Invalid output errors are retryable since LLM outputs are non-deterministic.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return true;
@@ -575,7 +601,8 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
   /**
    * Creates an InvalidOutputError from a Schema error.
    *
-   * @example
+   * **Example** (Creating an invalid output error from a schema error)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import { AiError } from "effect/unstable/ai"
@@ -585,8 +612,7 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
    * const parseError = AiError.InvalidOutputError.fromSchemaError(schemaError)
    * ```
    *
-   * @since 1.0.0
-   * @category constructors
+   * @since 4.0.0
    */
   static fromSchemaError(error) {
     return new InvalidOutputError({
@@ -603,7 +629,8 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  *
  * Structured output errors are retryable since LLM outputs are non-deterministic.
  *
- * @example
+ * **Example** (Creating a structured output error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -617,8 +644,8 @@ export class InvalidOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/a
  * // "Structured output validation failed: Expected a valid JSON object"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/StructuredOutputError")({
   _tag: /*#__PURE__*/Schema.tag("StructuredOutputError"),
@@ -628,13 +655,15 @@ export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effec
   usage: /*#__PURE__*/Schema.optional(UsageInfo)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `StructuredOutputError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Structured output errors are retryable since LLM outputs are non-deterministic.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return true;
@@ -642,7 +671,8 @@ export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effec
   /**
    * Creates a StructuredOutputError from a Schema error.
    *
-   * @example
+   * **Example** (Creating a structured output error from a schema error)
+   *
    * ```ts
    * import { Schema } from "effect"
    * import { AiError } from "effect/unstable/ai"
@@ -653,8 +683,7 @@ export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effec
    * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError, rawText)
    * ```
    *
-   * @since 1.0.0
-   * @category constructors
+   * @since 4.0.0
    */
   static fromSchemaError(error, responseText) {
     return new StructuredOutputError({
@@ -673,7 +702,8 @@ export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effec
  * Unsupported schema errors are not retryable because they indicate a
  * programmer error where the schema is incompatible with the provider.
  *
- * @example
+ * **Example** (Creating an unsupported schema error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -686,8 +716,8 @@ export class StructuredOutputError extends /*#__PURE__*/Schema.ErrorClass("effec
  * // "Unsupported schema: Unions are not supported in Anthropic structured output"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class UnsupportedSchemaError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/UnsupportedSchemaError")({
   _tag: /*#__PURE__*/Schema.tag("UnsupportedSchemaError"),
@@ -695,13 +725,15 @@ export class UnsupportedSchemaError extends /*#__PURE__*/Schema.ErrorClass("effe
   metadata: /*#__PURE__*/providerMetadataWithDefaults()
 }) {
   /**
-   * @since 1.0.0
+   * Marks `UnsupportedSchemaError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Unsupported schema errors are not retryable because they indicate a programmer error.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -715,7 +747,8 @@ export class UnsupportedSchemaError extends /*#__PURE__*/Schema.ErrorClass("effe
  *
  * Unknown errors are not retryable by default since the cause is unknown.
  *
- * @example
+ * **Example** (Creating an unknown error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -728,8 +761,8 @@ export class UnsupportedSchemaError extends /*#__PURE__*/Schema.ErrorClass("effe
  * // "An unexpected error occurred"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class UnknownError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/UnknownError")({
   _tag: /*#__PURE__*/Schema.tag("UnknownError"),
@@ -738,13 +771,15 @@ export class UnknownError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
   http: /*#__PURE__*/Schema.optional(HttpContext)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `UnknownError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Unknown errors are not retryable by default.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -762,7 +797,8 @@ export class UnknownError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
  * This error is retryable because the model may self-correct when provided
  * with the list of available tools.
  *
- * @example
+ * **Example** (Creating a tool not found error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -776,8 +812,8 @@ export class UnknownError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiEr
  * // "Tool 'unknownTool' not found. Available tools: GetWeather, GetTime"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolNotFoundError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolNotFoundError")({
   _tag: /*#__PURE__*/Schema.tag("ToolNotFoundError"),
@@ -785,13 +821,15 @@ export class ToolNotFoundError extends /*#__PURE__*/Schema.ErrorClass("effect/ai
   availableTools: /*#__PURE__*/Schema.Array(Schema.String)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolNotFoundError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Tool not found errors are retryable because the model may self-correct.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return true;
@@ -807,7 +845,8 @@ export class ToolNotFoundError extends /*#__PURE__*/Schema.ErrorClass("effect/ai
  * This error is retryable because the model may correct its parameters
  * on subsequent attempts.
  *
- * @example
+ * **Example** (Creating a tool parameter validation error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -822,8 +861,8 @@ export class ToolNotFoundError extends /*#__PURE__*/Schema.ErrorClass("effect/ai
  * // "Invalid parameters for tool 'GetWeather': Expected string, got number"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolParameterValidationError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolParameterValidationError")({
   _tag: /*#__PURE__*/Schema.tag("ToolParameterValidationError"),
@@ -832,13 +871,15 @@ export class ToolParameterValidationError extends /*#__PURE__*/Schema.ErrorClass
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolParameterValidationError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Parameter validation errors are retryable because the model may correct parameters.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return true;
@@ -854,7 +895,8 @@ export class ToolParameterValidationError extends /*#__PURE__*/Schema.ErrorClass
  * This error is not retryable because invalid results indicate a bug in the
  * tool handler implementation.
  *
- * @example
+ * **Example** (Creating an invalid tool result error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -868,8 +910,8 @@ export class ToolParameterValidationError extends /*#__PURE__*/Schema.ErrorClass
  * // "Tool 'GetWeather' returned invalid result: missing 'temperature' field"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InvalidToolResultError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidToolResultError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidToolResultError"),
@@ -877,13 +919,15 @@ export class InvalidToolResultError extends /*#__PURE__*/Schema.ErrorClass("effe
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidToolResultError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Invalid tool result errors are not retryable because they indicate a bug in the handler.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -898,23 +942,24 @@ export class InvalidToolResultError extends /*#__PURE__*/Schema.ErrorClass("effe
  * This error is not retryable because encoding failures indicate a bug in the
  * tool schema definitions.
  *
- * @example
+ * **Example** (Creating a tool result encoding error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.ToolResultEncodingError({
  *   toolName: "GetWeather",
- *   toolResult: { circular: "ref" },
- *   description: "Cannot encode circular reference"
+ *   toolResult: { temperature: 72n },
+ *   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 circular reference"
+ * // "Failed to encode result for tool 'GetWeather': Cannot encode bigint values as JSON"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolResultEncodingError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolResultEncodingError")({
   _tag: /*#__PURE__*/Schema.tag("ToolResultEncodingError"),
@@ -923,13 +968,15 @@ export class ToolResultEncodingError extends /*#__PURE__*/Schema.ErrorClass("eff
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolResultEncodingError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Encoding errors are not retryable because they indicate a code bug.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -944,7 +991,8 @@ export class ToolResultEncodingError extends /*#__PURE__*/Schema.ErrorClass("eff
  * This error is not retryable because it indicates a programming error in the
  * tool configuration that must be fixed in code.
  *
- * @example
+ * **Example** (Creating a tool configuration error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -958,8 +1006,8 @@ export class ToolResultEncodingError extends /*#__PURE__*/Schema.ErrorClass("eff
  * // "Invalid configuration for tool 'OpenAiCodeInterpreter': Invalid container ID format"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolConfigurationError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolConfigurationError")({
   _tag: /*#__PURE__*/Schema.tag("ToolConfigurationError"),
@@ -967,13 +1015,15 @@ export class ToolConfigurationError extends /*#__PURE__*/Schema.ErrorClass("effe
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolConfigurationError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Configuration errors are not retryable because they indicate a code bug.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -988,7 +1038,8 @@ export class ToolConfigurationError extends /*#__PURE__*/Schema.ErrorClass("effe
  * This error occurs when tool approval responses are present in the prompt
  * but no toolkit was provided to resolve them.
  *
- * @example
+ * **Example** (Creating a toolkit required error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1001,8 +1052,8 @@ export class ToolConfigurationError extends /*#__PURE__*/Schema.ErrorClass("effe
  * // "Toolkit required to resolve pending tool approvals: GetWeather, SendEmail"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class ToolkitRequiredError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/ToolkitRequiredError")({
   _tag: /*#__PURE__*/Schema.tag("ToolkitRequiredError"),
@@ -1010,13 +1061,15 @@ export class ToolkitRequiredError extends /*#__PURE__*/Schema.ErrorClass("effect
   description: /*#__PURE__*/Schema.optional(Schema.String)
 }) {
   /**
-   * @since 1.0.0
+   * Marks `ToolkitRequiredError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Toolkit required errors are not retryable without providing a toolkit.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -1033,34 +1086,37 @@ export class ToolkitRequiredError extends /*#__PURE__*/Schema.ErrorClass("effect
  * valid but not supported by the provider (e.g., unsupported media types,
  * unsupported file formats, etc.).
  *
- * @example
+ * **Example** (Creating an invalid user input error)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.InvalidUserInputError({
- *   description: "Unsupported media type 'video/mp4'. Supported types: image/*, application/pdf, text/plain"
+ *   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: image/*, application/pdf, text/plain"
+ * // "Invalid user input: Unsupported media type 'video/mp4'. Supported types include images, application/pdf, text/plain"
  * ```
  *
- * @since 1.0.0
  * @category reason
+ * @since 4.0.0
  */
 export class InvalidUserInputError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/InvalidUserInputError")({
   _tag: /*#__PURE__*/Schema.tag("InvalidUserInputError"),
   description: Schema.String
 }) {
   /**
-   * @since 1.0.0
+   * Marks `InvalidUserInputError` as a semantic AI error reason for runtime guards.
+   *
+   * @since 4.0.0
    */
   [ReasonTypeId] = ReasonTypeId;
   /**
    * Invalid user input errors require fixing the input and are not retryable.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return false;
@@ -1072,8 +1128,8 @@ export class InvalidUserInputError extends /*#__PURE__*/Schema.ErrorClass("effec
 /**
  * Schema for validating and parsing AI error reasons.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const AiErrorReason = /*#__PURE__*/Schema.Union([RateLimitError, QuotaExhaustedError, AuthenticationError, ContentPolicyError, InvalidRequestError, InternalProviderError, NetworkError, InvalidOutputError, StructuredOutputError, UnsupportedSchemaError, UnknownError, ToolNotFoundError, ToolParameterValidationError, InvalidToolResultError, ToolResultEncodingError, ToolConfigurationError, ToolkitRequiredError, InvalidUserInputError]);
 // =============================================================================
@@ -1090,7 +1146,8 @@ const TypeId = "~effect/unstable/ai/AiError/AiError";
  *
  * Use with `Effect.catchReason` for ergonomic error handling:
  *
- * @example
+ * **Example** (Handling an AI error by tag)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -1108,8 +1165,8 @@ const TypeId = "~effect/unstable/ai/AiError/AiError";
  * )
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/AiError")({
   _tag: /*#__PURE__*/Schema.tag("AiError"),
@@ -1122,7 +1179,7 @@ export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/A
   /**
    * Delegates to the underlying reason's `isRetryable` getter.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get isRetryable() {
     return this.reason.isRetryable;
@@ -1130,7 +1187,7 @@ export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/A
   /**
    * Delegates to the underlying reason's `retryAfter` if present.
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   get retryAfter() {
     return "retryAfter" in this.reason ? this.reason.retryAfter : undefined;
@@ -1142,10 +1199,8 @@ export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/A
 /**
  * Type guard to check if a value is an `AiError`.
  *
- * @param u - The value to check
- * @returns `true` if the value is an `AiError`, `false` otherwise
+ * **Example** (Checking for an AI error)
  *
- * @example
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1160,17 +1215,15 @@ export class AiError extends /*#__PURE__*/Schema.ErrorClass("effect/ai/AiError/A
  * console.log(AiError.isAiError(aiError)) // true
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isAiError = u => Predicate.hasProperty(u, TypeId);
 /**
  * Type guard to check if a value is an `AiErrorReason`.
  *
- * @param u - The value to check
- * @returns `true` if the value is an `AiErrorReason`, `false` otherwise
+ * **Example** (Checking for an AI error reason)
  *
- * @example
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1181,14 +1234,15 @@ export const isAiError = u => Predicate.hasProperty(u, TypeId);
  * console.log(AiError.isAiErrorReason(genericError)) // false
  * ```
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isAiErrorReason = u => Predicate.hasProperty(u, ReasonTypeId);
 /**
  * Creates an `AiError` with the given reason.
  *
- * @example
+ * **Example** (Creating an AI error)
+ *
  * ```ts
  * import { Duration } from "effect"
  * import { AiError } from "effect/unstable/ai"
@@ -1205,8 +1259,8 @@ export const isAiErrorReason = u => Predicate.hasProperty(u, ReasonTypeId);
  * // "OpenAI.completion: Rate limit exceeded. Retry after 1 minute"
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = params => new AiError(params);
 /**
@@ -1214,7 +1268,8 @@ export const make = params => new AiError(params);
  *
  * Provider packages can use this as a base for provider-specific mapping.
  *
- * @example
+ * **Example** (Mapping an HTTP status to a reason)
+ *
  * ```ts
  * import { AiError } from "effect/unstable/ai"
  *
@@ -1226,8 +1281,8 @@ export const make = params => new AiError(params);
  * console.log(reason._tag) // "RateLimitError"
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const reasonFromHttpStatus = params => {
   const {