@effect/ai-openai-compat

Patch Changes

• Add an optional batchKey to EmbeddingModel.make to group concurrent embed calls by provider-relevant context. OpenAI and OpenAI-compatible providers now separate batches with different configuration overrides or client transforms. Undeclared context, such as per-call FetchHttpClient.RequestInit, still uses the first caller's value.

• Add typed HTTP date and Retry-After header values to Headers, and parse them consistently across the HTTP client, OTLP exporter, GraphQL client, AI clients and static server.

  • Headers.parseHttpDate / Headers.formatHttpDate read all three RFC 9110 date formats as UTC, whatever the process time zone, and emit IMF-fixdate.

  • Headers.parseRetryAfter, Headers.formatRetryAfter and Headers.retryAfterDelay accept whole non-negative seconds of any size, read exactly, or an HTTP date, and the delay is never negative. HTTP dates accept the 23:59:60 leap second, read as the following second.

  • Headers.RetryAfter holds either a Duration (RetryAfterDuration) or a DateTime.Utc (RetryAfterDateTime). Headers.retryAfterDuration builds the first from any Duration.Input: infinite durations throw, finite negative ones become zero, and fractional seconds are rounded up when formatted.

  • Parse failures are reported as Headers.HeaderParseError.

  • Schema.DateTimeUtcFromHttpDate and Schema.RetryAfterFromString expose the same parsing as string codecs for HTTP API headers.

  • Invalid Retry-After values such as -5, 1.5, 1e3 or Infinity are now ignored everywhere. HttpClient.retryTransient and HttpClient.withRateLimiter no longer honour fractional seconds, and the AI clients no longer produce negative or infinite retryAfter durations.

  • HttpStaticServer reads If-Modified-Since and Last-Modified as UTC; asctime dates were previously shifted by the process time zone.

• Add non-retryable AiError.InvalidResponseError for provider response schema and SSE decoding failures, with optional HTTP context; model-generated output validation remains retryable. Update exhaustive matches on AiErrorReason to handle the new tag, and update serialized-error consumers to accept it.

• Consistently nest authentication, internal provider, and unknown error metadata under the openai or openai-compat provider key, including error codes, error types, and request IDs.

Patch Changes

• Emit each streamed chat completion event's parts as one chunk instead of creating an inner stream per event.

• Use "openai-compat" instead of "openai" as the provider key for error metadata, prompt part options, and response part metadata, so @effect/ai-openai-compat no longer shares module augmentation keys with @effect/ai-openai.

• Avoid creating a child stream for each SSE event when streaming chat completions.

• Avoid intermediate content allocations for single text-part user messages.

Patch Changes

• Add toolCallValidation: "deferred" for callers using disableToolCallResolution: true. Model-generated tool calls return with unknown parameters, including invalid parameters and undeclared tool names, even without a toolkit. Supported by the Anthropic, OpenAI, and OpenAI-compatible providers. Strict validation remains the default; provider-executed calls remain validated.

• Replay assistant text, reasoning, and tool calls in Chat Completions requests even when their parts carry item IDs. Remove unused Responses API include bookkeeping and the unsupported store and conversation configuration options. Neither option is sent to the provider.

• Replay assistant reasoning alongside text and tool calls in a single chat message, preserving the provider’s reasoning field (defaulting to reasoning_content).

• Convert each tool's parameter schema once per request, instead of again for every returned tool call.

Patch Changes

• Preserve tool call extra_content from OpenAI-compatible providers, so Gemini receives its thought signatures on follow-up tool turns. It is exposed as metadata.openai.extraContent on tool call response parts and sent back from the openai.extraContent tool call prompt option.

• Ignore empty content deltas in streamed chat completions. Providers such as Ollama send content: "" with every reasoning chunk, which split a single reasoning block into one part per token and opened the text part before the reasoning finished.

Patch Changes

• Update AI tracing to use current OpenTelemetry GenAI conventions:

  • Replace gen_ai.system with gen_ai.provider.name. The system option, BaseAttributes and WellKnownSystem are removed in favor of provider: { name }, ProviderAttributes and WellKnownProviderName.

  • Remove gen_ai.token.type, which is not a span attribute in the current conventions, along with the token option, TokenAttributes and the AllAttributes types.

  • LanguageModel spans are client spans and record gen_ai.output.type (text or json) for every provider. The OpenAI responseFormat telemetry option and WellKnownResponseFormat are removed.

  • Move OpenAI service-tier and system-fingerprint attributes from gen_ai.openai.* to openai.*.

  • Rename concurrency, toolChoice and objectName span attributes to effect.ai.concurrency, effect.ai.tool_choice and effect.ai.object_name. Tool choices record the resolved value, defaulting to "auto"; object choices are JSON-encoded.

  • Include cached tokens in Anthropic gen_ai.usage.input_tokens and report cache reads and writes as gen_ai.usage.cache_read.input_tokens and gen_ai.usage.cache_write.input_tokens. The duplicate Anthropic cacheCreationInputTokens and cacheReadInputTokens response options are removed.

• Tag every module and directly importable export with an explicit @stability. @stability stable follows strict semver, and @stability unstable may receive breaking changes in minor releases.

Patch Changes

• Effect 4.0 is the first stable release of Effect v4. It replaces the 4.0.0 beta and release-candidate series, whose per-release notes remain below under the 4.0.0-beta.* and 4.0.0-rc.* headings. To upgrade from Effect 3, follow the migration guide.

  Packaging and versioning

  • All Effect packages share one version number and are released together. Use the same version of effect and every @effect/* package.

  • @effect/platform, @effect/rpc, @effect/cluster, @effect/cli, @effect/ai, @effect/sql, @effect/workflow, @effect/experimental and similar packages are merged into effect. Separate packages remain only for platforms (@effect/platform-*), SQL drivers (@effect/sql-*), AI providers (@effect/ai-*), framework bindings (@effect/atom-*), OpenTelemetry, Vitest and tooling.

  • Modules such as effect/http, effect/http-api, effect/rpc, effect/cluster, effect/workflow, effect/ai, effect/cli, effect/sql and effect/schema import from effect/<area>. APIs tagged @stability unstable may have breaking changes in minor releases. APIs without a stability tag follow semver.

  • APIs that expose a third-party dependency are tagged @stability unstable, because that dependency's releases can change them. This covers NodeRedis, DenoRedis, BunRedis, @effect/platform-node/Undici and the undici dispatcher APIs, the ws options and re-exports in the platform packages, driver-specific options and clients in @effect/sql-clickhouse, @effect/sql-d1, @effect/sql-libsql, @effect/sql-mssql, @effect/sql-mysql2, @effect/sql-pglite and @effect/sql-sqlite-do, the provider clients, models and generated schemas in the @effect/ai-* packages, @effect/opentelemetry, and the vitest re-export in @effect/vitest.

  • effect has no runtime dependencies.

  • New packages in v4: @effect/platform-deno, @effect/sql-pglite, @effect/ai-openai-compat, @effect/ai-typesafe, @effect/atom-react, @effect/atom-solid, @effect/atom-vue, @effect/openapi-generator and @effect/doctest. @effect/docgen now lives in this repository.

  Core

  • The fiber runtime was rewritten for lower memory use and faster execution, with smaller bundles and better tree-shaking.

  • Services are defined with Context.Service, FiberRef is replaced by Context.Reference, Cause has a flat structure, and many combinators were renamed. See the migration guide for the full list.

  • Software transactional memory is built into Effect.tx, with TxRef, TxQueue, TxHashMap, TxPubSub, TxSemaphore and related Tx* data types.

  • Clock separates wall-clock time from monotonic time.

  • New modules include Semaphore, Latch, LayerRef, ErrorReporter, ByteSize, Newtype and Crypto. Arbitrary is now a native property-based testing module and no longer depends on fast-check.

  Schema

  • Schema v4 is a new implementation with faster parsing, class-based schemas, make constructors on every schema, and effectful decoding with services.

  • SchemaRepresentation powers JSON Schema (Draft-04, Draft-07, 2020-12 and OpenAPI 3.0/3.1) import and export, TypeScript code generation, and AI structured output.

  • SchemaBinary provides a compact binary codec and is the default wire format for cluster transports.

  • Optional JIT and AOT schema compilers are available as experimental modules.

  Platform, HTTP and RPC

  • HttpApi supports typed response headers, streaming and SSE responses, the HTTP QUERY method, HttpApiTest for in-memory testing, and much faster type checking for large APIs.

  • The HTTP modules add static file serving, response compression, rate-limited clients and graceful server shutdown.

  • Socket has a pull-based reader with backpressure and STARTTLS support. Network addresses are modeled by effect/net.

  • RPC serialization is schema-aware and supports server-originated requests and notifications.

  • @effect/platform-deno adds full Deno support. The Node, Bun, Deno and browser packages all provide the platform Crypto service, and the browser package adds IndexedDB support.

  Cluster and Workflow

  • Workflows can be declared with class syntax, and DurableQueue and an in-memory WorkflowEngine are available.

  • Runner memory can be bounded with ShardingConfig limits. Shutdown, entity movement and persisted replies are more reliable.

  SQL

  • @effect/sql-pg uses a built-in PostgreSQL client with pipelining, prepared statements and binary codecs, and no longer depends on pg.

  • @effect/sql-sqlite-node uses Node's built-in node:sqlite and requires Node 22.16 or newer.

  • SqlError exposes structured reasons such as UniqueViolation.

  AI

  • effect/ai adds EmbeddingModel, the DecisionModel classification and rating API, dynamic tools and tool approvals.

  • The MCP server supports protocol versions 2024-11-05 through 2026-07-28, including elicitation, sampling with tools, resource subscriptions and typed tool output.

  • Provider packages cover Anthropic, OpenAI, OpenAI-compatible APIs and OpenRouter.

  CLI, Atom, observability and testing

  • effect/cli adds global flags, command aliases and examples, an interactive wizard mode, and shell completions for Bash, Zsh and Fish.

  • effect/reactivity and the @effect/atom-* bindings add SSR hydration, stale-while-revalidate atoms and serializable RPC and HttpApi queries.

  • The OTLP exporters can be configured with standard OpenTelemetry environment variables, and @effect/opentelemetry aligns logs and spans with the OpenTelemetry specification.

  • @effect/vitest runs property tests with the native Arbitrary module and supports Vitest fixtures.

  Requirements

  • TypeScript 5.9 or newer. TypeScript 7 is recommended.

  • @effect/vitest and @effect/doctest require Vitest 5.

  • @effect/atom-react requires React 19.

  • @effect/platform-deno requires Deno 2.8.3 or newer.