effect 4.0.7 → 4.1.1

package/src/SchemaGetter.ts

@@ -1535,7 +1535,10 @@ export function stringifyJson(options?: StringifyJsonOptions): Getter<string, un
  * The getter is pure and never fails. It splits the string by `separator`
  * (default `,`) and then each pair at the first `keyValueSeparator` (default `=`),
  * preserving the rest of the value. An empty `keyValueSeparator` uses the first
- * two characters as the key and value. Pairs missing a key or value are skipped.
+ * two characters as the key and value. Pairs without a `keyValueSeparator` or
+ * with an empty key are skipped. Pairs with an empty value are skipped unless
+ * `keepEmptyValues` is `true`, in which case the value is `""`. When `trim` is
+ * `true`, keys and values are trimmed before these checks.
  *
  * **Example** (Parsing a key-value string)
  *
@@ -1557,23 +1560,32 @@ export function stringifyJson(options?: StringifyJsonOptions): Getter<string, un
 export function splitKeyValue<E extends string>(options?: {
   readonly separator?: string | undefined
   readonly keyValueSeparator?: string | undefined
+  readonly trim?: boolean | undefined
+  readonly keepEmptyValues?: boolean | undefined
 }): Getter<Record<string, string>, E> {
   const separator = options?.separator ?? ","
   const keyValueSeparator = options?.keyValueSeparator ?? "="
+  const trim = options?.trim ?? false
+  const keepEmptyValues = options?.keepEmptyValues ?? false
   return transform((input) =>
     input.split(separator).reduce((acc, pair) => {
+      let key: string
+      let value: string
       if (keyValueSeparator === "") {
-        const [key, value] = pair.split("")
-        if (key && value) InternalRecord.assignProperty(acc, key, value)
-        return acc
+        key = pair.slice(0, 1)
+        value = pair.slice(1, 2)
+      } else {
+        const index = pair.indexOf(keyValueSeparator)
+        if (index === -1) return acc
+        key = pair.slice(0, index)
+        value = pair.slice(index + keyValueSeparator.length)
       }
-      const index = pair.indexOf(keyValueSeparator)
-      if (index <= 0) return acc
-      const key = pair.slice(0, index)
-      const value = pair.slice(index + keyValueSeparator.length)
-      if (value) {
-        InternalRecord.assignProperty(acc, key, value)
+      if (trim) {
+        key = key.trim()
+        value = value.trim()
       }
+      if (key === "" || (value === "" && !keepEmptyValues)) return acc
+      InternalRecord.assignProperty(acc, key, value)
       return acc
     }, {} as Record<string, string>)
   )
@@ -2271,7 +2283,11 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
     return [""]
   }
 
-  const replaced = bracketPath.replace(/\[(.*?)\]/g, ".$1")
+  // Consume unmatched bracket runs too, avoiding repeated scans for a closing bracket.
+  const replaced = bracketPath.replace(
+    /\[([^\]\r\n\u2028\u2029]*)(\])?/g,
+    (match, content, closing) => closing ? `.${content}` : match
+  )
   const parts = replaced.split(".")
   // if bracket path started with "[...]" we get ".foo" => ["", "foo"]; drop the synthetic first ""
   const start = replaced.startsWith(".") ? 1 : 0

package/src/SchemaRepresentation.ts

@@ -928,6 +928,25 @@ export const isULIDReviver: FilterReviver<null> = makeReviverFilter(
   ({ annotations }) => Schema.isULID(annotations)
 )
 
+/**
+ * Reviver for persisted `isAscii` checks.
+ *
+ * **When to use**
+ *
+ * Use when reconstructing documents that may contain checks created by {@link Schema.isAscii}.
+ *
+ * @see {@link Schema.isAscii} for creating the corresponding check
+ *
+ * @stability unstable
+ * @category validation
+ * @since 4.0.6
+ */
+export const isAsciiReviver: FilterReviver<null> = makeReviverFilter(
+  "effect/schema/isAscii",
+  Schema.Null,
+  ({ annotations }) => Schema.isAscii(annotations)
+)
+
 /**
  * Reviver for persisted `isBase64` checks.
  *
@@ -3183,7 +3202,8 @@ export function fromRepresentations(
  * - Objects and arrays used as `const` values or `enum` members are rejected. Only strings, numbers, booleans, and null
  *   are supported.
  * - Intersections of overlapping unions are limited to disjoint root-type partitions and finite primitive `anyOf`
- *   literal sets. Other union intersections, including cases that would duplicate a nested choice, are rejected.
+ *   literal sets, which may also be duplicated across branches. Other union intersections, including cases that would
+ *   duplicate any other nested choice, are rejected.
  * - Unknown extension keywords are ignored and their semantics are not enforced.
  * - Only local references to top-level definitions in the form `#/$defs/<escaped-token>` are supported, optionally
  *   followed by a pointer below the definition. A pointer target becomes a definition keyed by its escaped tokens, such
@@ -3232,7 +3252,8 @@ export function fromJsonSchemaDocument(
  * - Objects and arrays used as `const` values or `enum` members are rejected. Only strings, numbers, booleans, and null
  *   are supported.
  * - Intersections of overlapping unions are limited to disjoint root-type partitions and finite primitive `anyOf`
- *   literal sets. Other union intersections, including cases that would duplicate a nested choice, are rejected.
+ *   literal sets, which may also be duplicated across branches. Other union intersections, including cases that would
+ *   duplicate any other nested choice, are rejected.
  * - Only local references to top-level definitions in the form `#/$defs/<escaped-token>` are supported, optionally
  *   followed by a pointer below the definition. A pointer target becomes a definition keyed by its escaped tokens, such
  *   as `Name/properties/field`, and is rejected if a top-level definition already uses that key. Root references and

package/src/SchemaTransformation.ts

@@ -812,9 +812,12 @@ export function uncapitalize(): Transformation<string, string> {
  * **Details**
  *
  * Decoding splits the string by `separator` (default `","`) into pairs, then
- * splits each pair by `keyValueSeparator` (default `"="`). Encoding joins the
- * record back into a string using the same separators. The transformation is
- * round-trippable when keys and values do not contain the separators.
+ * splits each pair by `keyValueSeparator` (default `"="`). Set `trim` to trim
+ * keys and values, and `keepEmptyValues` to keep pairs with an empty value as
+ * `""` instead of skipping them (see {@link SchemaGetter.splitKeyValue}).
+ * Encoding joins the record back into a string using the same separators. The
+ * transformation is round-trippable when keys and values do not contain the
+ * separators and, with `trim`, have no surrounding whitespace.
  *
  * **Example** (Parsing key-value pairs)
  *
@@ -840,6 +843,8 @@ export function uncapitalize(): Transformation<string, string> {
 export function splitKeyValue(options?: {
   readonly separator?: string | undefined
   readonly keyValueSeparator?: string | undefined
+  readonly trim?: boolean | undefined
+  readonly keepEmptyValues?: boolean | undefined
 }): Transformation<Record<string, string>, string> {
   return new Transformation(
     SchemaGetter.splitKeyValue(options),
@@ -1702,8 +1707,8 @@ export const urlFromString: Transformation<URL, string> = transformEffect<URL, s
  * **Details**
  *
  * Decoding calls `BigDecimal.fromString(s)` and fails with `InvalidValue` if
- * the string is not a valid `BigDecimal` representation. Encoding returns
- * `BigDecimal.format(bd)`.
+ * the string is not a valid `BigDecimal` representation or its scale is
+ * outside ±10,000. Encoding returns `BigDecimal.format(bd)`.
  *
  * @stability stable
  * @category transforming

package/src/ScopedCache.ts

@@ -29,7 +29,6 @@ import * as MutableHashMap from "./MutableHashMap.ts"
 import * as Option from "./Option.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import * as Predicate from "./Predicate.ts"
-import { UnhandledLogLevel } from "./References.ts"
 import * as Scope from "./Scope.ts"
 
 const TypeId = "~effect/ScopedCache"
@@ -411,12 +410,9 @@ const hasExpired = <A, E>(entry: Entry<A, E>, fiber: Fiber.Fiber<unknown, unknow
 
 // Expiry and capacity eviction report cleanup failures without failing unrelated readers.
 const closeEvicted = <A, E>(entry: Entry<A, E>): Effect.Effect<void> =>
-  effect.catchCause(Scope.close(entry.scope, effect.exitVoid), reportUnhandledError)
-
-const reportUnhandledError = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
-  core.withFiber((fiber) => {
-    const level = fiber.getRef(UnhandledLogLevel)
-    return level ? effect.logWithLevel(level)("Unhandled error in ScopedCache finalizer", cause) : effect.void
+  effect.ignoreCause(Scope.close(entry.scope, effect.exitVoid), {
+    log: "Unhandled",
+    message: "Unhandled error in ScopedCache finalizer"
   })
 
 const checkCapacity = <K, A, E>(
@@ -1184,7 +1180,7 @@ export const keys = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effe
         keys.push(key)
       } else {
         MutableHashMap.remove(state.map, key)
-        fibers.push(effect.forkUnsafe(fiber, Scope.close(entry.scope, effect.exitVoid), true, true))
+        fibers.push(effect.forkUnsafe(fiber, closeEvicted(entry), true, true))
       }
     }
     return fibers.length === 0 ? effect.succeed(keys) : effect.as(effect.fiberAwaitAll(fibers), keys)
@@ -1249,7 +1245,7 @@ export const entries = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.E
         }
       } else {
         MutableHashMap.remove(state.map, key)
-        fibers.push(effect.forkUnsafe(fiber, Scope.close(entry.scope, effect.exitVoid), true, true))
+        fibers.push(effect.forkUnsafe(fiber, closeEvicted(entry), true, true))
       }
     }
     return fibers.length === 0

package/src/Semaphore.ts

@@ -17,6 +17,7 @@ import { dual, identity } from "./Function.ts"
 import * as core from "./internal/core.ts"
 import * as internal from "./internal/effect.ts"
 import type * as Option from "./Option.ts"
+import type * as Scope from "./Scope.ts"
 
 /**
  * A counting semaphore that coordinates concurrent access with permits.
@@ -134,6 +135,24 @@ export interface Semaphore {
    */
   take(this: Semaphore, permits: number): Effect.Effect<number>
 
+  /**
+   * Acquires the specified number of permits for the lifetime of the current
+   * scope, suspending the task if they are not yet available.
+   *
+   * **When to use**
+   *
+   * Use to hold permits until a scope closes, such as while a scoped resource
+   * is leased.
+   *
+   * **Details**
+   *
+   * Waiting can be interrupted unless the caller is uninterruptible. The
+   * permits are taken and their release is added to the scope in one
+   * uninterruptible step, so acquired permits are always returned when the
+   * scope closes.
+   */
+  takeScoped(this: Semaphore, permits: number): Effect.Effect<void, never, Scope.Scope>
+
   /**
    * Acquires the specified number of permits only if they are immediately
    * available.
@@ -281,6 +300,15 @@ class SemaphoreImpl implements Semaphore {
     return takePermits(this, n, () => internal.succeed(n))
   }
 
+  takeScoped(n: number): Effect.Effect<void, never, Scope.Scope> {
+    return internal.uninterruptibleMask((restore) =>
+      internal.flatMap(
+        internal.scope,
+        (scope) => takePermits(this, n, () => internal.scopeAddFinalizer(scope, this.release(n)), restore)
+      )
+    )
+  }
+
   takeIfAvailable(n: number): Effect.Effect<boolean> {
     return internal.suspend(() => {
       if (this.free < n) return internal.succeed(false)
@@ -747,6 +775,119 @@ export const take: {
   (self: Semaphore, permits: number): Effect.Effect<number>
 } = dual(2, (self: Semaphore, permits: number) => self.take(permits))
 
+/**
+ * Acquires the specified number of permits until the current scope closes.
+ *
+ * **When to use**
+ *
+ * Use when permits should be held for the lifetime of a scope, such as while a
+ * scoped resource is leased.
+ *
+ * **Details**
+ *
+ * The effect waits until enough permits are available. The wait can be
+ * interrupted unless the caller is uninterruptible. The permits are taken and
+ * their release is added to the scope in one uninterruptible step, so acquired
+ * permits are always returned when the scope closes.
+ *
+ * **Example** (Holding a permit for a scope)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Semaphore } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const semaphore = yield* Semaphore.make(1)
+ *   yield* Effect.scoped(Semaphore.takeScoped(semaphore, 1))
+ *   return yield* Semaphore.takeIfAvailable(semaphore, 1)
+ * })
+ *
+ * Effect.runSync(program) // => true
+ * ```
+ *
+ * @see {@link take} for acquiring permits that are released manually
+ * @see {@link withPermits} for holding permits while one effect runs
+ *
+ * @stability stable
+ * @category combinators
+ * @since 4.0.7
+ */
+export const takeScoped: {
+  /**
+   * Acquires the specified number of permits until the current scope closes.
+   *
+   * **When to use**
+   *
+   * Use when permits should be held for the lifetime of a scope, such as while a
+   * scoped resource is leased.
+   *
+   * **Details**
+   *
+   * The effect waits until enough permits are available. The wait can be
+   * interrupted unless the caller is uninterruptible. The permits are taken and
+   * their release is added to the scope in one uninterruptible step, so acquired
+   * permits are always returned when the scope closes.
+   *
+   * **Example** (Holding a permit for a scope)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Semaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* Semaphore.make(1)
+   *   yield* Effect.scoped(Semaphore.takeScoped(semaphore, 1))
+   *   return yield* Semaphore.takeIfAvailable(semaphore, 1)
+   * })
+   *
+   * Effect.runSync(program) // => true
+   * ```
+   *
+   * @see {@link take} for acquiring permits that are released manually
+   * @see {@link withPermits} for holding permits while one effect runs
+   *
+   * @stability stable
+   * @category combinators
+   * @since 4.0.7
+   */
+  (permits: number): (self: Semaphore) => Effect.Effect<void, never, Scope.Scope>
+  /**
+   * Acquires the specified number of permits until the current scope closes.
+   *
+   * **When to use**
+   *
+   * Use when permits should be held for the lifetime of a scope, such as while a
+   * scoped resource is leased.
+   *
+   * **Details**
+   *
+   * The effect waits until enough permits are available. The wait can be
+   * interrupted unless the caller is uninterruptible. The permits are taken and
+   * their release is added to the scope in one uninterruptible step, so acquired
+   * permits are always returned when the scope closes.
+   *
+   * **Example** (Holding a permit for a scope)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Semaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* Semaphore.make(1)
+   *   yield* Effect.scoped(Semaphore.takeScoped(semaphore, 1))
+   *   return yield* Semaphore.takeIfAvailable(semaphore, 1)
+   * })
+   *
+   * Effect.runSync(program) // => true
+   * ```
+   *
+   * @see {@link take} for acquiring permits that are released manually
+   * @see {@link withPermits} for holding permits while one effect runs
+   *
+   * @stability stable
+   * @category combinators
+   * @since 4.0.7
+   */
+  (self: Semaphore, permits: number): Effect.Effect<void, never, Scope.Scope>
+} = dual(2, (self: Semaphore, permits: number) => self.takeScoped(permits))
+
 /**
  * Acquires the specified number of permits only if they are immediately
  * available.

package/src/Stream.ts

@@ -10247,6 +10247,9 @@ export const orDie = <A, E, R>(self: Stream<A, E, R>): Stream<A, never, R> => fr
  *
  * The `log` option controls whether the failure is logged before the stream
  * terminates.
+ * Set `log: "Unhandled"` to read `References.UnhandledLogLevel` when the
+ * failure occurs; `undefined` disables logging. Minimum log level filtering
+ * still applies.
  *
  * **Gotchas**
  *
@@ -10295,12 +10298,12 @@ export const orDie = <A, E, R>(self: Stream<A, E, R>): Stream<A, never, R> => fr
  */
 export const ignore: <
   Arg extends Stream<any, any, any> | {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 >(
   selfOrOptions: Arg,
   options?: {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 ) => [Arg] extends [Stream<infer A, infer _E, infer R>] ? Stream<A, never, R>
   : <A, E, R>(self: Stream<A, E, R>) => Stream<A, never, R> = dual(
@@ -10308,7 +10311,7 @@ export const ignore: <
     <A, E, R>(
       self: Stream<A, E, R>,
       options?: {
-        readonly log?: boolean | Severity | undefined
+        readonly log?: boolean | Severity | "Unhandled" | undefined
       } | undefined
     ): Stream<A, never, R> => fromChannel(Channel.ignore(self.channel, options))
   )
@@ -10321,6 +10324,12 @@ export const ignore: <
  * Use when you need to silently suppress a stream's entire failure cause,
  * including both typed errors and defects, rather than propagate it downstream.
  *
+ * **Details**
+ *
+ * Set `log: "Unhandled"` to read `References.UnhandledLogLevel` when the
+ * failure occurs; `undefined` disables logging. Minimum log level filtering
+ * still applies.
+ *
  * **Example** (Ignoring stream failure causes)
  *
  * ```ts import.meta.vitest
@@ -10345,19 +10354,19 @@ export const ignore: <
  */
 export const ignoreCause: <
   Arg extends Stream<any, any, any> | {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 >(
   streamOrOptions: Arg,
   options?: {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 ) => [Arg] extends [Stream<infer A, infer _E, infer R>] ? Stream<A, never, R>
   : <A, E, R>(self: Stream<A, E, R>) => Stream<A, never, R> = dual(
     (args) => isStream(args[0]),
     <A, E, R>(
       self: Stream<A, E, R>,
-      options?: { readonly log?: boolean | Severity | undefined } | undefined
+      options?: { readonly log?: boolean | Severity | "Unhandled" | undefined } | undefined
     ): Stream<A, never, R> => fromChannel(Channel.ignoreCause(self.channel, options))
   )
 

package/src/Terminal.ts

@@ -42,6 +42,12 @@ export interface Terminal {
    */
 
   readonly rows: Effect.Effect<number>
+  /**
+   * Subscribes to terminal size changes. The queue starts with the current
+   * dimensions, receives each resize until the scope closes, and keeps only the
+   * latest size.
+   */
+  readonly size: Effect.Effect<Queue.Dequeue<Size, Cause.Done>, never, Scope.Scope>
   /**
    * Reads input events from the default standard input.
    */
@@ -56,6 +62,18 @@ export interface Terminal {
   readonly display: (text: string) => Effect.Effect<void, PlatformError>
 }
 
+/**
+ * Terminal dimensions measured in character cells.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Size {
+  readonly columns: number
+  readonly rows: number
+}
+
 /**
  * Keyboard key metadata for terminal input, including the key name and
  * modifier state.
@@ -183,7 +201,7 @@ export const Terminal: Context.Service<Terminal, Terminal> = Context.Service("ef
  *
  * **Details**
  *
- * The implementation object supplies `columns`, `rows`, `readInput`,
+ * The implementation object supplies `columns`, `rows`, `size`, `readInput`,
  * `readLine`, and `display`; `make` attaches the `Terminal` service marker so
  * the result can be provided through the `Terminal` context service.
  *

package/src/ai/AiError.ts

@@ -15,51 +15,9 @@
 import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
 import type * as HttpClientError from "../http/HttpClientError.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"
-import * as Redacted from "../Redacted.ts"
 import * as Schema from "../Schema.ts"
 
-/**
- * Schema for HTTP requests to an AI provider.
- *
- * **Example** (Describing an HTTP request)
- *
- * ```ts import.meta.vitest
- * import type { AiError } from "effect/ai"
- *
- * const requestDetails: typeof AiError.HttpRequestDetails.Type = {
- *   method: "POST",
- *   url: "https://api.openai.com/v1/responses",
- *   urlParams: [],
- *   hash: undefined,
- *   headers: { "Content-Type": "application/json" }
- * }
- * const result = [requestDetails.method, requestDetails.urlParams] // => ["POST", []]
- * ```
- *
- * @stability unstable
- * @category schemas
- * @since 4.0.0
- */
-export const HttpRequestDetails = Schema.Struct({
-  method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE", "QUERY"]),
-  url: Schema.String,
-  urlParams: Schema.Array(
-    Schema.Tuple([Schema.String, Schema.Union([Schema.String, Schema.Redacted(Schema.String)])])
-  ),
-  hash: Schema.optional(Schema.String),
-  headers: Schema.Record(
-    Schema.String,
-    Schema.Union([
-      Schema.String,
-      Schema.Redacted(Schema.String)
-    ])
-  )
-}).annotate({ identifier: "HttpRequestDetails" })
-
 /**
  * Schema for HTTP responses from an AI provider.
  *
@@ -101,16 +59,6 @@ const providerMetadataWithDefaults = <Metadata extends ProviderMetadata>() =>
     Schema.withDecodingDefault(Effect.succeed({}))
   )
 
-const redactHeaders = (headers: Record<string, string>): Record<string, string> => {
-  const redacted = redact(headers) as Record<string, string | Redacted.Redacted>
-  const result: Record<string, string> = {}
-  for (const key in redacted) {
-    const value = redacted[key]
-    InternalRecord.assignProperty(result, key, Redacted.isRedacted(value) ? value.toString() : value)
-  }
-  return result
-}
-
 // =============================================================================
 // Http Request Error
 // =============================================================================
@@ -124,6 +72,10 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  * such as network connectivity problems, request encoding issues, or invalid
  * URLs.
  *
+ * When created with `NetworkError.fromHttpClientError`, `cause` holds the
+ * `HttpClientError` the request failed with. It is stored unchanged, so it
+ * carries the runtime's original error text without redaction.
+ *
  * **Example** (Creating a network error)
  *
  * ```ts import.meta.vitest
@@ -131,13 +83,8 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  *
  * const error = new AiError.NetworkError({
  *   reason: "TransportError",
- *   request: {
- *     method: "POST",
- *     url: "https://api.openai.com/v1/completions",
- *     urlParams: [],
- *     hash: undefined,
- *     headers: { "Content-Type": "application/json" }
- *   },
+ *   method: "POST",
+ *   url: "https://api.openai.com/v1/completions",
  *   description: "Connection timeout after 30 seconds"
  * })
  *
@@ -153,8 +100,10 @@ export class NetworkError extends Schema.Error<NetworkError>(
 )({
   _tag: Schema.tag("NetworkError"),
   reason: Schema.Literals(["TransportError", "EncodeError", "InvalidUrlError"]),
-  request: HttpRequestDetails,
-  description: Schema.optional(Schema.String)
+  method: Schema.String,
+  url: Schema.String,
+  description: Schema.optional(Schema.String),
+  cause: Schema.optional(Schema.Defect())
 }) {
   /**
    * Marks `NetworkError` as a semantic AI error reason for runtime guards.
@@ -199,18 +148,52 @@ export class NetworkError extends Schema.Error<NetworkError>(
     return new NetworkError({
       description: error.description,
       reason: error._tag,
-      request: {
-        hash: Option.getOrUndefined(error.request.hash),
-        headers: redactHeaders(error.request.headers),
-        method: error.request.method,
-        url: error.request.url,
-        urlParams: Array.from(error.request.urlParams)
-      }
+      method: error.request.method,
+      url: error.request.url
+    })
+  }
+
+  /**
+   * Creates a NetworkError from a platform HttpClientError whose reason is a
+   * request error, keeping the HttpClientError as `cause`.
+   *
+   * **Example** (Creating a network error from an HTTP client error)
+   *
+   * ```ts import.meta.vitest
+   * import { AiError } from "effect/ai"
+   * import { HttpClientError, HttpClientRequest } from "effect/http"
+   *
+   * const platformError = new HttpClientError.HttpClientError({
+   *   reason: new HttpClientError.TransportError({
+   *     request: HttpClientRequest.get("https://example.com/models"),
+   *     description: "Connection refused"
+   *   })
+   * })
+   *
+   * const aiError = AiError.NetworkError.fromHttpClientError(
+   *   platformError as HttpClientError.HttpClientError & { readonly reason: HttpClientError.RequestError }
+   * )
+   * aiError.reason // => "TransportError"
+   * aiError.cause === platformError // => true
+   * ```
+   *
+   * @stability unstable
+   * @since 4.1.0
+   */
+  static fromHttpClientError(
+    error: HttpClientError.HttpClientError & { readonly reason: HttpClientError.RequestError }
+  ): NetworkError {
+    return new NetworkError({
+      description: error.reason.description,
+      reason: error.reason._tag,
+      method: error.reason.request.method,
+      url: error.reason.request.url,
+      cause: error
     })
   }
 
   override get message(): string {
-    const methodAndUrl = `${this.request.method} ${this.request.url}`
+    const methodAndUrl = `${this.method} ${this.url}`
 
     let baseMessage = this.description
       ? `${this.reason}: ${this.description}`
@@ -418,15 +401,9 @@ export const UsageInfo = Schema.Struct({
  *
  * **When to use**
  *
- * Use to attach request details, optional response details, and optional body
- * text to AI provider errors.
- *
- * **Details**
- *
- * Includes the required request details plus optional response details and raw
- * response body.
+ * Use to attach optional response details and optional body text to AI
+ * provider errors.
  *
- * @see {@link HttpRequestDetails} for captured request details
  * @see {@link HttpResponseDetails} for captured response details
  *
  * @stability unstable
@@ -434,7 +411,6 @@ export const UsageInfo = Schema.Struct({
  * @since 4.0.0
  */
 export const HttpContext = Schema.Struct({
-  request: HttpRequestDetails,
   response: Schema.optional(HttpResponseDetails),
   body: Schema.optional(Schema.String)
 }).annotate({ identifier: "HttpContext" })
@@ -849,8 +825,8 @@ export class InternalProviderError extends Schema.Error<InternalProviderError>(
  * **Details**
  *
  * Invalid response errors are not retryable because retrying does not resolve an
- * incompatible provider response format. Optional HTTP context can retain request
- * and response details for diagnosis.
+ * incompatible provider response format. Optional HTTP context can retain response
+ * details for diagnosis.
  *
  * @see {@link InvalidOutputError} for retryable model-generated output failures
  * @stability unstable