@xandreed/plugin-models 0.13.0 → 0.15.0

package/dist/llm/openAiCodex.js

@@ -1,76 +1,87 @@
 import { AiError, LanguageModel } from "effect/ai";
 import { OpenAiClient, OpenAiLanguageModel } from "@effect/ai-openai";
 import { HttpClient, HttpClientRequest } from "effect/http";
-import { Effect, Result, Option, Redacted, Stream } from "effect";
-import { CurrentModelCallPolicy, CurrentPromptCacheKey, describeModel, foldStreamParts } from "@xandreed/core";
-import { OpenAiCodexWebSocketHttpClient } from "./openAiCodexWebSocket.js";
+import { Effect, Option, Predicate, Redacted, Schema, Stream } from "effect";
+import { isTurnError, ModelId, ModelSelection, ProviderId, CurrentModelCallPolicy, CurrentPromptCacheKey, describeModel, ENGINE_KEY, ModelFailureStamp, modelFailureOf, stampAiErrorFailure } from "@xandreed/core";
+import { foldStreamParts } from "@xandreed/core/internal";
+import { CurrentOpenAiCodexSessions, makeOpenAiCodexSessions, makeOpenAiCodexWebSocketHttpClient } from "./openAiCodexWebSocket.js";
+import { OPENAI_CODEX_ORIGINATOR } from "../auth/openAiCodexOAuth.js";
+import { classifyAiError } from "./provider-failure.entity.functions.js";
+import { withOpenAiFailures } from "./provider-client.adapter.js";
+import { resilientHttpClient, withModelRequestCall, withModelRequestStream } from "../transport/resilient-http-client.adapter.js";
 export const OPENAI_CODEX_API_URL = "https://chatgpt.com/backend-api/codex";
-const record = (value) => typeof value === "object" && value !== null ? value : {}, instructionText = (message) => {
-  const value = record(message);
-  if (value.role !== "developer" && value.role !== "system")
-    return [];
-  const content = value.content;
-  if (typeof content === "string")
-    return [content];
-  if (!Array.isArray(content))
-    return [];
-  return content.flatMap((part) => {
-    const item = record(part);
-    return typeof item.text === "string" ? [item.text] : [];
-  });
-};
-export const toOpenAiCodexRequestBody = (body, reasoningEffort) => {
-  const value = record(body), input = Array.isArray(value.input) ? value.input : [], instructions = input.flatMap(instructionText).join(`
+const ResponsesRequest = Schema.StructWithRest(Schema.Struct({
+  input: Schema.optionalKey(Schema.Array(Schema.Json)),
+  text: Schema.optionalKey(Schema.Struct({ verbosity: Schema.optionalKey(Schema.Json) })),
+  reasoning: Schema.optionalKey(Schema.JsonObject),
+  tool_choice: Schema.optionalKey(Schema.Json),
+  parallel_tool_calls: Schema.optionalKey(Schema.Json)
+}), [Schema.Record(Schema.String, Schema.Json)]), decodeRequest = Schema.decodeUnknownOption(ResponsesRequest), decodeRequestText = Schema.decodeUnknownOption(Schema.fromJsonString(ResponsesRequest)), InstructionMessage = Schema.Struct({
+  role: Schema.Literals(["developer", "system"]),
+  content: Schema.Union([Schema.String, Schema.Array(Schema.Json)])
+}), decodeInstruction = Schema.decodeUnknownOption(InstructionMessage), decodeTextPart = Schema.decodeUnknownOption(Schema.Struct({ text: Schema.String })), instructionText = (message) => Option.match(decodeInstruction(message), {
+  onNone: () => [],
+  onSome: ({ content }) => Predicate.isString(content) ? [content] : content.flatMap((part) => Option.toArray(Option.map(decodeTextPart(part), ({ text }) => text)))
+}), subscriptionBody = (value, reasoningEffort) => {
+  const input = value.input ?? [], instructions = input.flatMap(instructionText).join(`
 
-`), conversationalInput = input.filter((message) => instructionText(message).length === 0), configuredText = record(value.text);
+`), conversationalInput = input.filter((message) => instructionText(message).length === 0);
   return {
     ...Object.fromEntries(Object.entries(value).filter(([key]) => key !== "max_output_tokens")),
     store: !1,
     stream: !0,
     instructions: instructions.length > 0 ? instructions : "You are a helpful assistant.",
     input: conversationalInput,
-    text: { verbosity: configuredText.verbosity ?? "low" },
+    text: { verbosity: value.text?.verbosity ?? "low" },
     include: ["reasoning.encrypted_content"],
     tool_choice: value.tool_choice ?? "auto",
     parallel_tool_calls: value.parallel_tool_calls ?? !0,
-    ...reasoningEffort === void 0 ? {} : { reasoning: { ...record(value.reasoning), effort: reasoningEffort, summary: "auto" } }
+    ...Option.match(reasoningEffort, {
+      onNone: () => ({}),
+      onSome: (effort) => ({ reasoning: { ...value.reasoning, effort, summary: "auto" } })
+    })
   };
 };
+export const toOpenAiCodexRequestBody = (body, reasoningEffort) => subscriptionBody(Option.getOrElse(decodeRequest(body), () => ({})), Option.fromNullishOr(reasoningEffort));
 const transformRequest = (accountId, reasoningEffort) => (request) => {
   const withHeaders = request.pipe(HttpClientRequest.setHeaders({
     "chatgpt-account-id": accountId,
-    originator: "pi",
+    originator: OPENAI_CODEX_ORIGINATOR,
     "OpenAI-Beta": "responses=experimental",
     accept: "text/event-stream"
   }));
   if (request.body._tag !== "Uint8Array")
     return withHeaders;
-  const encodedBody = request.body.body;
-  return Option.match(Result.getSuccess(Result.try(() => JSON.parse(new TextDecoder().decode(encodedBody)))), {
+  return Option.match(decodeRequestText(new TextDecoder().decode(request.body.body)), {
     onNone: () => withHeaders,
-    onSome: (decoded) => HttpClientRequest.bodyJsonUnsafe(withHeaders, toOpenAiCodexRequestBody(decoded, reasoningEffort))
+    onSome: (decoded) => HttpClientRequest.bodyJsonUnsafe(withHeaders, subscriptionBody(decoded, reasoningEffort))
   });
 }, responseStatus = (error) => AiError.isAiError(error) && ("http" in error.reason) ? error.reason.http?.response?.status : void 0;
-export const mapOpenAiCodexError = (model, error) => responseStatus(error) === 404 ? AiError.make({
-  module: "OpenAiCodex",
-  method: "responses",
-  reason: new AiError.InvalidRequestError({
-    description: `model ${model} is not available to the configured ChatGPT subscription account`
-  })
-}) : responseStatus(error) === 200 ? AiError.make({
-  module: "OpenAiCodex",
-  method: "responses",
-  reason: new AiError.InvalidOutputError({
-    description: `the ${model} subscription stream returned a rejected or incompatible event`
-  })
-}) : error, makeOpenAiCodexLanguageModel = (args) => Effect.all({
+export const mapOpenAiCodexError = (_model, error) => {
+  if (!AiError.isAiError(error))
+    return error;
+  const metadata = "metadata" in error.reason ? error.reason.metadata : {}, engine = Object.hasOwn(metadata, ENGINE_KEY) ? metadata[ENGINE_KEY] : void 0;
+  if (Predicate.isObject(engine) && Object.hasOwn(engine, "failure") && Option.isSome(Schema.decodeUnknownOption(ModelFailureStamp)(engine)))
+    return error;
+  const classified = classifyAiError(error, "openai");
+  if (Option.exists(modelFailureOf(classified), (kind) => kind !== "Unknown"))
+    return classified;
+  return responseStatus(classified) === 200 ? stampAiErrorFailure(classified, "InvalidResponse") : classified;
+}, makeOpenAiCodexLanguageModel = (args) => Effect.all({
   cacheKey: Effect.service(CurrentPromptCacheKey),
-  policy: Effect.service(CurrentModelCallPolicy)
-}).pipe(Effect.flatMap(({ cacheKey, policy }) => OpenAiClient.make({
+  policy: Effect.service(CurrentModelCallPolicy),
+  sessions: Effect.flatMap(Effect.service(CurrentOpenAiCodexSessions), Option.match({
+    onSome: Effect.succeed,
+    onNone: () => makeOpenAiCodexSessions()
+  }))
+}, { concurrency: 1 }).pipe(Effect.flatMap(({ cacheKey, policy, sessions }) => OpenAiClient.make({
   apiKey: args.accessToken,
   apiUrl: OPENAI_CODEX_API_URL,
-  transformClient: () => OpenAiCodexWebSocketHttpClient.pipe(HttpClient.mapRequest((request) => transformRequest(args.accountId, Option.getOrUndefined(Option.map(policy, (value) => value.effort)))(request.pipe(HttpClientRequest.prependUrl(OPENAI_CODEX_API_URL), HttpClientRequest.bearerToken(args.accessToken)))))
-}).pipe(Effect.flatMap((client) => OpenAiLanguageModel.make({
+  transformClient: () => makeOpenAiCodexWebSocketHttpClient(args.webSocketProxy ?? Option.none(), Option.some(sessions)).pipe(HttpClient.mapRequest((request) => transformRequest(args.accountId, Option.map(policy, (value) => value.effort))(request.pipe(HttpClientRequest.prependUrl(OPENAI_CODEX_API_URL), HttpClientRequest.bearerToken(args.accessToken)))), (client) => resilientHttpClient(client, {
+    protocol: "openai",
+    adaptResponse: (response) => response
+  }))
+}).pipe(Effect.map(withOpenAiFailures), Effect.flatMap((client) => OpenAiLanguageModel.make({
   model: args.model,
   config: {
     strictJsonSchema: !1,
@@ -89,10 +100,11 @@ export const mapOpenAiCodexError = (model, error) => responseStatus(error) === 4
     })
   }
 }).pipe(Effect.provideService(OpenAiClient.OpenAiClient, client))), Effect.map((streaming) => {
-  const streamText = (options) => streaming.streamText(options).pipe(Stream.mapError((error) => mapOpenAiCodexError(args.model, error))), model = {
+  const selection = new ModelSelection({ provider: ProviderId.make("openai-codex"), modelId: ModelId.make(args.model) }), streamText = (options) => withModelRequestStream("Stream", selection, streaming.streamText(options)).pipe(Stream.catch((error) => isTurnError(error) ? Stream.die(error) : Stream.fail(mapOpenAiCodexError(args.model, error)))), model = {
     ...streaming,
     streamText,
-    generateText: (options) => foldStreamParts(streamText(options), () => Effect.void).pipe(Effect.map((turn) => new LanguageModel.GenerateTextResponse(turn.content)))
+    generateObject: (options) => withModelRequestCall("Object", selection, streaming.generateObject(options)).pipe(Effect.catch((error) => isTurnError(error) ? Effect.die(error) : Effect.fail(error))),
+    generateText: (options) => withModelRequestCall("Text", selection, foldStreamParts(streamText(options), () => Effect.void)).pipe(Effect.map((turn) => new LanguageModel.GenerateTextResponse(turn.content)), Effect.catch((error) => isTurnError(error) ? Effect.die(error) : Effect.fail(error)))
   };
   return describeModel(model, {
     provider: "openai-codex",

package/dist/llm/openAiCodexWebSocket.d.ts

@@ -1,14 +1,67 @@
-import { HttpClient } from "effect/http";
-/** ChatGPT's Luna router currently keys its internal route on Pi's
- * time-ordered UUIDv7 session shape; UUIDv4 reaches a nonexistent rollout
- * alias. Keep one v7 id per Efferent conversation/cache key. */
-export declare const openAiCodexUuidV7: (now?: number) => string;
+import { HttpClient, HttpClientError } from "effect/http";
+import { Cache, Context, Effect, Option } from "effect";
+import type { WebSocketProxy } from "../ports/models-transport.port.js";
+/** The conversations a client keeps a session id for; past it, the least recently used one gets a fresh id on its next request. */
+export declare const OPENAI_CODEX_SESSION_CAPACITY = 1024;
+/** ChatGPT's Luna router currently keys its internal route on a
+ * time-ordered UUIDv7 session id; UUIDv4 reaches a nonexistent rollout
+ * alias. Keep one v7 id per Efferent conversation/cache key. `now` is the
+ * id's time in epoch milliseconds (`Clock.currentTimeMillis`). */
+export declare const openAiCodexUuidV7: (now: number) => string;
+/** The session id of each conversation (its prompt cache key) a client serves. */
+export type OpenAiCodexSessions = Cache.Cache<string, string>;
+/**
+ * A session cache: a key's UUIDv7 is minted on its first request and kept
+ * while it is used; past `capacity` keys the least recently used is dropped.
+ */
+export declare const makeOpenAiCodexSessions: (capacity?: number) => Effect.Effect<OpenAiCodexSessions>;
+/**
+ * The session cache of the routed model a call runs under: each of the
+ * models plugin's layers keeps its own, so two agents in one process never
+ * share session ids. A subscription model built outside them keeps one of
+ * its own.
+ */
+export declare const CurrentOpenAiCodexSessions: Context.Reference<Option.Option<OpenAiCodexSessions>>;
 /** Codex currently names the WebSocket terminal event `response.done`; the
  * public Responses stream consumed by @effect/ai names it `response.completed`. */
 export declare const normalizeOpenAiCodexWebSocketEvent: (value: unknown) => unknown;
 export declare const isOpenAiCodexControlEvent: (type: unknown) => boolean;
+/** The OpenAI error body the HTTP Responses endpoint answers a failed request with. */
+export interface OpenAiErrorBody {
+    readonly error: {
+        readonly message: string;
+        readonly type: string | null;
+        readonly code: string | null;
+        readonly param: string | null;
+    };
+}
+/**
+ * The OpenAI error body of an `error` frame that refuses the request, which
+ * the HTTP Responses endpoint would answer with a 400: the frame's status is
+ * 400, its error's type or code is `invalid_request_error`, or its message
+ * names an image. The error is the frame's `error` object, or the frame
+ * itself (the Responses stream's own `error` event). Any other frame: none.
+ */
+export declare const openAiCodexRefusal: (event: unknown) => Option.Option<OpenAiErrorBody>;
 /** Adapt the ChatGPT Codex WebSocket protocol to an SSE-shaped HttpClient
  * response. OpenAiLanguageModel remains the sole protocol decoder, so text,
  * reasoning, tool calls, tool results, usage, and errors keep their standard
- * Effect representations instead of being reimplemented here. */
-export declare const OpenAiCodexWebSocketHttpClient: HttpClient.HttpClient;
+ * Effect representations instead of being reimplemented here. `proxy` is how
+ * the socket reaches ChatGPT (`ModelsTransport.webSocketAgent`); `None`
+ * connects directly. A route this runtime cannot use fails every request.
+ * `sessions` keeps each conversation's session id (`makeOpenAiCodexSessions`);
+ * without it, every request gets a fresh one.
+ *
+ * Each request opens its own socket (Effect's `Socket`), which closes when
+ * the response's stream ends, fails or is cancelled, when the request is
+ * aborted, and when the request fails before its first event. The response
+ * is the stream once the first event arrives, unless that event is an
+ * `error`: the request then fails with the status and the OpenAI error body
+ * the HTTP endpoint would answer, so a refused image (`openAiCodexRefusal`)
+ * is an `InvalidRequestError` and an exhausted quota a
+ * `QuotaExhaustedError`. The stream ends after a terminal event or when the
+ * server closes the socket normally; a close before the first event fails
+ * the request as a transport error. */
+export declare const makeOpenAiCodexWebSocketHttpClient: (proxy: Option.Option<WebSocketProxy>, sessions?: Option.Option<OpenAiCodexSessions>) => HttpClient.HttpClient.With<HttpClientError.HttpClientError, never>;
+/** The subscription client connecting directly, with no proxy (a fresh session id per request). */
+export declare const OpenAiCodexWebSocketHttpClient: HttpClient.HttpClient.With<HttpClientError.HttpClientError, never>;

package/dist/llm/openAiCodexWebSocket.js

@@ -1,18 +1,13 @@
 import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
-import { Effect, Result } from "effect";
+import { Socket } from "effect/socket";
+import { Cache, Cause, Clock, Context, Duration, Effect, Exit, Match, Option, Predicate, Pull, Redacted, Result, Schema, Scope, Stream } from "effect";
 import { release } from "node:os";
 import WebSocket from "ws";
-const WEBSOCKET_BETA = "responses_websockets=2026-02-06", sessionIds = new Map, decodeBody = (request) => {
-  if (request.body._tag !== "Uint8Array")
-    return {};
-  const text = new TextDecoder().decode(request.body.body), parsed = JSON.parse(text);
-  return typeof parsed === "object" && parsed !== null ? parsed : {};
-}, websocketUrl = (url) => {
-  const next = new URL(url);
-  next.protocol = next.protocol === "http:" ? "ws:" : "wss:";
-  return next.toString();
-};
-export const openAiCodexUuidV7 = (now = Date.now()) => {
+import { redactCredentials } from "../transport/http-proxy.entity.functions.js";
+import { currentRuntime } from "../transport/models-transport.adapter.js";
+import { OPENAI_CODEX_ORIGINATOR } from "../auth/openAiCodexOAuth.js";
+const WEBSOCKET_BETA = "responses_websockets=2026-02-06", OPEN_TIMEOUT = Duration.seconds(30);
+export const OPENAI_CODEX_SESSION_CAPACITY = 1024, openAiCodexUuidV7 = (now) => {
   const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16)), timestamp = BigInt(now);
   bytes[0] = Number(timestamp >> 40n & 0xffn);
   bytes[1] = Number(timestamp >> 32n & 0xffn);
@@ -25,98 +20,111 @@ export const openAiCodexUuidV7 = (now = Date.now()) => {
   const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 };
-const sessionIdFor = (cacheKey) => {
-  const key = typeof cacheKey === "string" && cacheKey.length > 0 ? cacheKey : globalThis.crypto.randomUUID(), existing = sessionIds.get(key);
-  if (existing !== void 0)
-    return existing;
-  const created = openAiCodexUuidV7();
-  sessionIds.set(key, created);
-  return created;
-}, eventText = (data) => {
-  if (typeof data === "string")
-    return data;
-  if (data instanceof ArrayBuffer)
-    return new TextDecoder().decode(new Uint8Array(data));
-  if (ArrayBuffer.isView(data))
-    return new TextDecoder().decode(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
-  return;
-};
-export const normalizeOpenAiCodexWebSocketEvent = (value) => {
-  if (typeof value !== "object" || value === null)
-    return value;
-  const event = value;
-  return event.type === "response.done" ? { ...event, type: "response.completed" } : event;
-}, isOpenAiCodexControlEvent = (type) => typeof type === "string" && (type.startsWith("codex.") || type === "responsesapi.websocket_timing"), OpenAiCodexWebSocketHttpClient = HttpClient.make((request, url, signal) => Effect.tryPromise({
-  try: () => new Promise((resolve, reject) => {
-    const body = decodeBody(request), safeRequest = request.pipe(HttpClientRequest.setHeader("authorization", "[redacted]"), HttpClientRequest.setHeader("chatgpt-account-id", "[redacted]")), headers = Object.fromEntries(["authorization", "chatgpt-account-id", "originator"].flatMap((key) => {
-      const value = request.headers[key];
-      return value === void 0 ? [] : [[key, value]];
-    }));
-    headers["openai-beta"] = WEBSOCKET_BETA;
-    headers["user-agent"] = `pi (${process.platform} ${release()}; ${process.arch})`;
-    const requestId = sessionIdFor(body.prompt_cache_key);
-    body.prompt_cache_key = requestId;
-    headers["session-id"] = requestId;
-    headers["x-client-request-id"] = requestId;
-    const socket = new WebSocket(websocketUrl(url), { headers }), state = { settled: !1 }, stream = new ReadableStream({
-      start: (value) => {
-        state.controller = value;
-      },
-      cancel: () => socket.close(1000, "cancelled")
-    }), fail = (cause) => {
-      if (!state.settled) {
-        state.settled = !0;
-        reject(cause);
-      } else
-        state.controller?.error(cause);
-      socket.close(1011, "transport error");
-    }, abort = () => fail(Error("OpenAI subscription request aborted"));
-    signal.addEventListener("abort", abort, { once: !0 });
-    socket.addEventListener("open", () => {
-      Result.match(Result.try(() => {
-        socket.send(JSON.stringify({ type: "response.create", ...body }));
-        state.settled = !0;
-        return HttpClientResponse.fromWeb(safeRequest, new Response(stream, {
-          status: 200,
-          headers: { "content-type": "text/event-stream" }
-        }));
-      }), { onFailure: fail, onSuccess: resolve });
-    });
-    socket.addEventListener("message", (event) => {
-      Result.match(Result.try(() => {
-        const text = eventText(event.data);
-        if (text === void 0)
-          return;
-        const parsed = normalizeOpenAiCodexWebSocketEvent(JSON.parse(text)), type = parsed.type;
-        if (isOpenAiCodexControlEvent(type))
-          return;
-        if (type === "error") {
-          fail(Error(JSON.stringify(parsed)));
-          return;
-        }
-        state.controller?.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(parsed)}
+const mintSessionId = Effect.map(Clock.currentTimeMillis, openAiCodexUuidV7);
+export const makeOpenAiCodexSessions = (capacity = OPENAI_CODEX_SESSION_CAPACITY) => Cache.make({ capacity, lookup: (_key) => mintSessionId }), CurrentOpenAiCodexSessions = Context.Reference("@xandreed/plugin-models/CurrentOpenAiCodexSessions", {
+  defaultValue: () => Option.none()
+});
+const sessionIdFor = (sessions, cacheKey) => Option.match(Option.all([sessions, cacheKey]), {
+  onNone: () => mintSessionId,
+  onSome: ([cache, key]) => Cache.get(cache, key)
+}), websocketUrl = (url) => {
+  const next = new URL(url);
+  next.protocol = next.protocol === "http:" ? "ws:" : "wss:";
+  return next.toString();
+}, decodeRequestBody = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.JsonObject)), decodeCacheKey = Schema.decodeUnknownOption(Schema.NonEmptyString), CodexFrame = Schema.StructWithRest(Schema.Struct({ type: Schema.String }), [Schema.Record(Schema.String, Schema.Json)]), decodeFrame = Schema.decodeUnknownResult(Schema.fromJsonString(CodexFrame));
+export const normalizeOpenAiCodexWebSocketEvent = (value) => Predicate.isObject(value) && Predicate.hasProperty(value, "type") && value.type === "response.done" ? { ...value, type: "response.completed" } : value;
+const normalizeFrame = (frame) => frame.type === "response.done" ? { ...frame, type: "response.completed" } : frame, TERMINAL_EVENTS = new Set(["response.completed", "response.incomplete", "response.failed", "error"]);
+export const isOpenAiCodexControlEvent = (type) => typeof type === "string" && (type.startsWith("codex.") || type === "responsesapi.websocket_timing");
+const ErrorDetail = Schema.Struct({
+  message: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  type: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  code: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  param: Schema.optionalKey(Schema.NullOr(Schema.String))
+}), decodeErrorDetail = Schema.decodeUnknownOption(ErrorDetail), noDetail = {}, ErrorFrame = Schema.Struct({
+  type: Schema.Literal("error"),
+  status: Schema.optionalKey(Schema.Number),
+  error: Schema.optionalKey(Schema.Unknown)
+}), decodeErrorFrame = Schema.decodeUnknownOption(ErrorFrame), ERROR_STATUS = {
+  invalid_request_error: 400,
+  invalid_api_key_error: 401,
+  insufficient_quota_error: 429,
+  rate_limit_error: 429,
+  service_unavailable_error: 503
+}, statusOfName = (name) => Option.flatMap(name, (key) => Option.fromNullishOr(ERROR_STATUS[key])), errorAnswer = (event) => Option.map(decodeErrorFrame(event), (frame) => {
+  const detail = Option.getOrElse(Option.orElse(decodeErrorDetail(frame.error), () => decodeErrorDetail(event)), () => noDetail), message = Option.getOrElse(Option.fromNullishOr(detail.message), () => ""), type = Option.filter(Option.fromNullishOr(detail.type), (value) => value !== "error"), code = Option.fromNullishOr(detail.code), refused = frame.status === 400 || /image/i.test(message) || Option.contains(type, "invalid_request_error") || Option.contains(code, "invalid_request_error");
+  return {
+    status: refused ? 400 : Option.getOrElse(Option.orElse(Option.filter(Option.fromNullishOr(frame.status), (value) => value >= 400 && value < 600), () => Option.orElse(statusOfName(code), () => statusOfName(type))), () => 500),
+    refused,
+    body: { error: {
+      message: message.length > 0 ? message : refused ? "the request was refused" : "the subscription request failed",
+      type: Option.getOrElse(type, () => refused ? "invalid_request_error" : null),
+      code: Option.getOrNull(code),
+      param: Option.getOrNull(Option.fromNullishOr(detail.param))
+    } }
+  };
+});
+export const openAiCodexRefusal = (event) => Option.map(Option.filter(errorAnswer(event), (answer) => answer.refused), (answer) => answer.body);
+const bunSocket = (url, options) => {
+  return Reflect.construct(globalThis.WebSocket, [url, options]);
+}, wsSocket = (url, options) => {
+  return new WebSocket(url, options);
+}, openSocket = (url, headers, proxy) => Option.match(proxy, {
+  onNone: () => wsSocket(url, { headers }),
+  onSome: (route) => Match.value(route).pipe(Match.tag("Agent", ({ agent }) => wsSocket(url, { headers, agent })), Match.tag("Proxy", ({ url: proxyUrl }) => bunSocket(url, { headers, proxy: Redacted.value(proxyUrl) })), Match.exhaustive)
+}), routeMismatch = (route) => {
+  const runtime = currentRuntime();
+  return Match.value(route).pipe(Match.tag("Agent", () => runtime._tag === "Node" ? Option.none() : Option.some(`the WebSocket route is a Node agent, which ${runtime._tag === "Bun" ? "Bun's WebSocket" : "this runtime's WebSocket"} cannot use`)), Match.tag("Proxy", () => runtime._tag === "Bun" ? Option.none() : Option.some("the WebSocket route is a proxy URL for Bun's WebSocket, which this runtime's WebSocket would ignore")), Match.exhaustive, Option.map((why) => `${why}: refused rather than connecting directly past the proxy`));
+}, redacted = (request) => request.pipe(HttpClientRequest.setHeader("authorization", "[redacted]"), HttpClientRequest.setHeader("chatgpt-account-id", "[redacted]")), causeText = (cause) => cause instanceof Error ? cause.message : Predicate.hasProperty(cause, "error") && cause.error instanceof Error ? cause.error.message : Predicate.hasProperty(cause, "message") && Predicate.isString(cause.message) && cause.message.length > 0 ? cause.message : Predicate.isObject(cause) ? "the WebSocket handshake failed" : String(cause), socketFailureText = (error) => Match.value(error.reason).pipe(Match.tag("SocketCloseError", (close) => `closed ${close.code}${close.closeReason === void 0 || close.closeReason.length === 0 ? "" : `: ${close.closeReason}`}`), Match.tag("SocketUpgradeError", (upgrade) => upgrade.message), Match.orElse((reason) => reason._tag === "SocketOpenError" && reason.kind === "Timeout" ? reason.message : `${reason.message}: ${causeText(reason.cause)}`)), transportFailure = (request, description, cause) => new HttpClientError.HttpClientError({
+  reason: new HttpClientError.TransportError({
+    request: redacted(request),
+    description: `OpenAI subscription WebSocket failed: ${redactCredentials(description)}`,
+    cause
+  })
+}), encodeFailure = (request, error) => new HttpClientError.HttpClientError({
+  reason: new HttpClientError.EncodeError({ request: redacted(request), description: `the subscription request body is not a JSON object: ${error.message}`, cause: error })
+}), socketHeaders = (request, sessionId) => ({
+  ...Object.fromEntries(["authorization", "chatgpt-account-id", "originator"].flatMap((key) => Option.toArray(Option.map(Option.fromNullishOr(request.headers[key]), (value) => [key, value])))),
+  "openai-beta": WEBSOCKET_BETA,
+  "user-agent": `${OPENAI_CODEX_ORIGINATOR} (${process.platform} ${release()}; ${process.arch})`,
+  "session-id": sessionId,
+  "x-client-request-id": sessionId
+}), decoder = new TextDecoder, encoder = new TextEncoder, isNormalClose = (error) => error.reason._tag === "SocketCloseError" && error.reason.code === 1000, framesOf = (pull) => {
+  const next = Effect.catch(pull, (error) => isNormalClose(error) ? Cause.done() : Effect.fail(error));
+  return Stream.fromPull(Effect.succeed(next)).pipe(Stream.map((data) => Result.map(decodeFrame(typeof data === "string" ? data : decoder.decode(data)), normalizeFrame)), Stream.filter((frame) => Result.isFailure(frame) || !isOpenAiCodexControlEvent(frame.success.type)), Stream.takeUntil((frame) => Result.isSuccess(frame) && TERMINAL_EVENTS.has(frame.success.type)));
+}, sseBytes = (request) => (frame) => Result.match(frame, {
+  onFailure: (error) => Effect.fail(transportFailure(request, `a frame is not a JSON event object: ${error.message}`, error)),
+  onSuccess: (event) => Effect.succeed(encoder.encode(`data: ${JSON.stringify(Option.match(errorAnswer(event), {
+    onNone: () => event,
+    onSome: (answer) => ({ ...event, code: answer.body.error.code ?? answer.body.error.type, message: answer.body.error.message, param: answer.body.error.param })
+  }))}
 
-`));
-        if (type === "response.completed" || type === "response.incomplete" || type === "response.failed") {
-          state.controller?.close();
-          signal.removeEventListener("abort", abort);
-          socket.close(1000, "done");
-        }
-      }), { onFailure: fail, onSuccess: () => {
-        return;
-      } });
-    });
-    socket.addEventListener("error", (event) => fail(event.error ?? Error(event.message || "WebSocket handshake failed")));
-    socket.addEventListener("close", (event) => {
-      if (event.code !== 1000)
-        fail(Error(`OpenAI subscription WebSocket closed ${event.code}: ${event.reason}`));
-    });
-  }),
-  catch: (cause) => new HttpClientError.HttpClientError({
-    reason: new HttpClientError.TransportError({
-      request: request.pipe(HttpClientRequest.setHeader("authorization", "[redacted]"), HttpClientRequest.setHeader("chatgpt-account-id", "[redacted]")),
-      description: `OpenAI subscription WebSocket failed: ${cause instanceof Error ? cause.message : String(cause)}`,
-      cause
-    })
+`))
+}), exchange = (request, url, proxy, sessions, scope) => Effect.gen(function* () {
+  const encoded = request.body._tag === "Uint8Array" ? decodeRequestBody(decoder.decode(request.body.body)) : Effect.succeed({}), body = yield* Effect.mapError(encoded, (error) => encodeFailure(request, error)), sessionId = yield* sessionIdFor(sessions, decodeCacheKey(body.prompt_cache_key)), headers = socketHeaders(request, sessionId), socket = yield* Socket.fromWebSocket(Effect.acquireRelease(Effect.try({
+    try: () => openSocket(websocketUrl(url), headers, proxy),
+    catch: (cause) => new Socket.SocketError({ reason: new Socket.SocketOpenError({ kind: "Unknown", cause }) })
+  }), (ws) => Effect.sync(() => ws.close(1000, "done"))), { openTimeout: OPEN_TIMEOUT }), socketFailure = (error) => transportFailure(request, socketFailureText(error), error), { pull } = yield* Scope.provide(socket.reader, scope).pipe(Effect.mapError(socketFailure));
+  yield* (yield* Scope.provide(socket.writer, scope)).write(JSON.stringify({ type: "response.create", ...body, prompt_cache_key: sessionId })).pipe(Effect.mapError(socketFailure));
+  const events = yield* Scope.provide(Stream.toPull(framesOf(pull)), scope), first = yield* events.pipe(Effect.mapError((error) => Cause.isDone(error) ? error : socketFailure(error)), Pull.catchDone(() => Effect.fail(transportFailure(request, "the socket closed before the first event")))), head = first[0], safeRequest = redacted(request);
+  return yield* Option.match(Option.flatMap(Result.getSuccess(head), errorAnswer), {
+    onSome: (answer) => Scope.close(scope, Exit.void).pipe(Effect.as(HttpClientResponse.fromWeb(safeRequest, new Response(JSON.stringify(answer.body), {
+      status: answer.status,
+      headers: { "content-type": "application/json" }
+    })))),
+    onNone: () => Stream.fromIterable(first).pipe(Stream.concat(Stream.fromPull(Effect.succeed(events))), Stream.mapError(socketFailure), Stream.mapEffect(sseBytes(request)), Stream.tapError((error) => Effect.logWarning(error.message)), Stream.ensuring(Scope.close(scope, Exit.void)), Stream.toReadableStreamEffect(), Effect.map((stream) => HttpClientResponse.fromWeb(safeRequest, new Response(stream, {
+      status: 200,
+      headers: { "content-type": "text/event-stream" }
+    }))))
+  });
+});
+export const makeOpenAiCodexWebSocketHttpClient = (proxy, sessions = Option.none()) => HttpClient.make((request, url, signal) => Option.match(Option.flatMap(proxy, routeMismatch), {
+  onSome: (why) => Effect.fail(transportFailure(request, why)),
+  onNone: () => Effect.gen(function* () {
+    const scope = yield* Scope.make(), close = Scope.close(scope, Exit.void), run = Effect.runForkWith(yield* Effect.context()), abort = () => {
+      run(close);
+    };
+    signal.addEventListener("abort", abort, { once: !0 });
+    yield* Scope.addFinalizer(scope, Effect.sync(() => signal.removeEventListener("abort", abort)));
+    return yield* exchange(request, url, proxy, sessions, scope).pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : close));
   })
-}));
+})).pipe(HttpClient.filterStatusOk), OpenAiCodexWebSocketHttpClient = makeOpenAiCodexWebSocketHttpClient(Option.none());

package/dist/llm/prompt-cache-frame.entity.d.ts

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+/** Per-call references identify provisional controls after SDK conversion. Never encoded. */
+export declare const PromptCacheFrame: Schema.Struct<{
+    readonly candidates: Schema.$Array<Schema.Struct<{
+        readonly control: Schema.Struct<{
+            readonly type: Schema.Literal<"ephemeral">;
+            readonly ttl: Schema.optionalKey<Schema.Literals<readonly ["5m", "1h"]>>;
+        }>;
+        readonly priority: Schema.Int;
+    }>>;
+    readonly policy: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Auto", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"TopLevel", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"Off", {}>]>;
+    readonly capability: Schema.Boolean;
+}>;
+export type PromptCacheFrame = typeof PromptCacheFrame.Type;

package/dist/llm/prompt-cache-frame.entity.js

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+import { PromptCacheControl, PromptCacheSettings } from "./prompt-cache.entity.js";
+export const PromptCacheFrame = Schema.Struct({
+  candidates: Schema.Array(Schema.Struct({
+    control: PromptCacheControl,
+    priority: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+  })),
+  policy: PromptCacheSettings,
+  capability: Schema.Boolean
+});

package/dist/llm/prompt-cache.entity.d.ts

@@ -0,0 +1,57 @@
+import { Schema } from "effect";
+/** The Messages API's supported prompt-cache lifetimes. */
+export declare const PromptCacheTtl: Schema.Literals<readonly ["5m", "1h"]>;
+export type PromptCacheTtl = typeof PromptCacheTtl.Type;
+/** Per-model prompt caching; Off preserves and validates explicit caller controls. @public */
+export declare const PromptCacheSettings: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Auto", {
+    readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+}>, Schema.TaggedStruct<"TopLevel", {
+    readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+}>, Schema.TaggedStruct<"Off", {}>]>;
+export type PromptCacheSettings = typeof PromptCacheSettings.Type;
+/** A supported wire control; an omitted lifetime means five minutes. */
+export declare const PromptCacheControl: Schema.Struct<{
+    readonly type: Schema.Literal<"ephemeral">;
+    readonly ttl: Schema.optionalKey<Schema.Literals<readonly ["5m", "1h"]>>;
+}>;
+export type PromptCacheControl = typeof PromptCacheControl.Type;
+/** One actual cacheable wire position, in semantic cache-prefix order. */
+export declare const CachePosition: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unmarked", {}>, Schema.TaggedStruct<"Caller", {
+    readonly control: Schema.Unknown;
+}>, Schema.TaggedStruct<"Auto", {
+    readonly priority: Schema.Int;
+}>]>;
+export type CachePosition = typeof CachePosition.Type;
+/** All eligible positions, including unmarked blocks needed to locate the final target. */
+export declare const BreakpointInput: Schema.Struct<{
+    readonly positions: Schema.$Array<Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unmarked", {}>, Schema.TaggedStruct<"Caller", {
+        readonly control: Schema.Unknown;
+    }>, Schema.TaggedStruct<"Auto", {
+        readonly priority: Schema.Int;
+    }>]>>;
+    readonly policy: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Auto", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"TopLevel", {
+        readonly ttl: Schema.Literals<readonly ["5m", "1h"]>;
+    }>, Schema.TaggedStruct<"Off", {}>]>;
+    readonly capability: Schema.Boolean;
+    readonly callerTopLevel: Schema.optionalKey<Schema.Unknown>;
+}>;
+export type BreakpointInput = typeof BreakpointInput.Type;
+/** Automatic selections are ascending wire indexes; caller controls remain in place. */
+export declare const BreakpointPlan: Schema.Struct<{
+    readonly selectedAuto: Schema.$Array<Schema.Int>;
+    readonly topLevel: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly type: Schema.Literal<"ephemeral">;
+        readonly ttl: Schema.optionalKey<Schema.Literals<readonly ["5m", "1h"]>>;
+    }>>;
+}>;
+export type BreakpointPlan = typeof BreakpointPlan.Type;
+declare const PromptCacheError_base: Schema.Class<PromptCacheError, Schema.TaggedStruct<"PromptCacheError", {
+    readonly reason: Schema.Literals<readonly ["Control", "Capability", "Capacity", "TtlOrder", "TopLevel"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Why prepared Messages cache controls cannot form a supported request. */
+export declare class PromptCacheError extends PromptCacheError_base {
+}
+export {};

package/dist/llm/prompt-cache.entity.functions.d.ts

@@ -0,0 +1,8 @@
+import { Result } from "effect";
+import { PromptCacheError } from "./prompt-cache.entity.js";
+import type { BreakpointInput, BreakpointPlan } from "./prompt-cache.entity.js";
+/**
+ * Plan over actual cacheable wire positions, after SDK conversion. Caller controls are immutable;
+ * Auto candidates compete by priority, then later wire position, within four effective slots.
+ */
+export declare const planBreakpoints: (input: BreakpointInput) => Result.Result<BreakpointPlan, PromptCacheError>;