@xandreed/plugin-models 0.12.0 → 0.14.0

package/dist/llm/compat.d.ts

@@ -1,7 +1,7 @@
-import { AiError, LanguageModel, Tool } from "effect/ai";
-import type { Prompt } from "effect/ai";
+import { AiError, LanguageModel, Prompt, Tool } from "effect/ai";
 import { Effect } from "effect";
-import type { CompletionUsage } from "./sse.js";
+import type { CompletionUsage, UsageReading } from "./sse.js";
+import type { ModelsFetch } from "../ports/models-transport.port.js";
 /**
  * A generic OpenAI-compatible `/chat/completions` `LanguageModel` over raw
  * `fetch`. The official `@effect/ai-openai` client targets api.openai.com;
@@ -32,16 +32,47 @@ export interface CompatConfig {
      *  thinking defaults or call policy — for endpoints that reject the
      *  gateway extensions (Gemini's OpenAI-compatible API). */
     readonly standardOnly?: boolean;
-    /** Injectable for tests; defaults to global fetch. */
-    readonly fetchImpl?: typeof fetch;
+    /** How the endpoint's usage is read (default: every count, reasoning
+     *  included; see `UsageReading`). */
+    readonly usage?: UsageReading;
+    /** The model reads images: send them as `image_url` parts (default false: label lines; see `toChatMessages`). */
+    readonly images?: boolean;
+    /** The fetch requests go through (the models plugin passes its `ModelsTransport`'s, which knows the proxy); defaults to the global fetch. */
+    readonly fetchImpl?: ModelsFetch;
     /** Host-owned admission (e.g. reserve a worst-case cost) before every call. */
     readonly beforeRequest?: (body: Readonly<Record<string, unknown>>) => Effect.Effect<void, AiError.AiError>;
     /** Per-call accounting/resource boundary. Non-streaming responses are fully
      * buffered inside request so interruption also aborts body consumption. */
     readonly aroundRequest?: (body: Readonly<Record<string, unknown>>, request: Effect.Effect<Response, AiError.AiError>) => Effect.Effect<Response, AiError.AiError>;
 }
-/** Decoded `Prompt` messages → chat-completions message objects. */
-export declare const toChatMessages: (prompt: Prompt.Prompt) => ReadonlyArray<Json>;
+/** How `toChatMessages` writes a request. */
+export interface ChatMessageOptions {
+    /** Send images as `image_url` parts (default false: label lines). */
+    readonly images?: boolean;
+}
+/**
+ * Decoded `Prompt` messages → chat-completions message objects. A
+ * text-only user message is its text, as before. Without `images`, a user
+ * message is one string: its text, then a label line per file part, and a
+ * tool result is its text with a label line per image. With `images`, a
+ * user message with images is a content array of its parts in order (an
+ * image as an `image_url` part with a `data:` URL), and a tool result is its
+ * text in the tool message, while its images, which a tool message cannot
+ * carry, follow all the batch's tool messages in one user message, each
+ * result's captioned `Images returned by <tool> (call <id>):`; a user
+ * message right after the batch is merged into it, so no two user messages
+ * follow each other, captioned `The user's message:` when it has images of
+ * its own.
+ */
+export declare const toChatMessages: (prompt: Prompt.Prompt, options?: ChatMessageOptions) => ReadonlyArray<Json>;
+/**
+ * A prompt with every file part a label line: what a route that reads no
+ * images is sent (the models plugin rewrites a request so on such routes).
+ * A user message with file parts becomes one text part (its text, then a
+ * label line each); a tool result with model output becomes its text with a
+ * label line per file part, as its result. Messages without files are kept.
+ */
+export declare const promptWithImageLabels: (prompt: Prompt.Prompt) => Prompt.Prompt;
 /** User-defined tools → chat-completions function declarations (empty when
  *  the request carries none — the caller omits the `tools` key entirely). */
 export declare const toChatTools: (tools: ReadonlyArray<Tool.Any>) => ReadonlyArray<Json>;
@@ -76,6 +107,6 @@ interface ChatCompletion {
     readonly usage?: CompletionUsage;
 }
 /** Parse one non-streaming completion into `@effect/ai` encoded parts. */
-export declare const fromChatCompletion: (moduleName: string, body: ChatCompletion) => Effect.Effect<ReadonlyArray<unknown>, AiError.AiError>;
+export declare const fromChatCompletion: (moduleName: string, body: ChatCompletion, reading?: UsageReading) => Effect.Effect<ReadonlyArray<unknown>, AiError.AiError>;
 export declare const makeCompatLanguageModel: (config: CompatConfig) => Effect.Effect<LanguageModel.LanguageModel>;
 export {};

package/dist/llm/compat.js

@@ -1,7 +1,8 @@
-import { AiError, LanguageModel, Tool } from "effect/ai";
-import { Effect, Result, Option, Stream } from "effect";
-import { CurrentModelCallPolicy, CurrentPromptCacheKey, describeModel, strictJsonSchema, toolParametersSchema } from "@xandreed/core";
+import { AiError, LanguageModel, Prompt, Tool } from "effect/ai";
+import { Effect, Result, Option, Schema, Stream } from "effect";
+import { CurrentModelCallPolicy, CurrentPromptCacheKey, describeModel, ImageMediaType, mediaLabel, strictJsonSchema, toolParametersSchema } from "@xandreed/core";
 import { finishReasonFromWire, sseStreamParts, usageFromCompletion } from "./sse.js";
+import { redactCredentials } from "../transport/http-proxy.entity.functions.js";
 const record = (value) => typeof value === "object" && value !== null ? value : {}, semanticGatewayError = (moduleName, method, body) => Option.flatMap(Option.fromNullishOr(Result.getOrUndefined(Result.try(() => JSON.parse(body)))), (decoded) => {
   const error = record(record(decoded).error), type = typeof error.type === "string" ? error.type : "", message = typeof error.message === "string" ? error.message : "";
   if (type === "ModelError" || /model .*not supported/i.test(message))
@@ -19,18 +20,57 @@ const record = (value) => typeof value === "object" && value !== null ? value :
       reason: new AiError.UnknownError({ description: `CreditsError: ${message || "provider quota exhausted"}` })
     }));
   return Option.none();
-}), aiUnknown = (moduleName, method, e) => AiError.make({ module: moduleName, method, reason: new AiError.UnknownError({ description: String(e) }) }), invalidOutput = (moduleName, method, description) => AiError.make({ module: moduleName, method, reason: new AiError.InvalidOutputError({ description }) }), requestInfo = (chatUrl) => ({
+}), aiUnknown = (moduleName, method, e) => AiError.make({ module: moduleName, method, reason: new AiError.UnknownError({ description: redactCredentials(String(e)) }) }), invalidOutput = (moduleName, method, description) => AiError.make({ module: moduleName, method, reason: new AiError.InvalidOutputError({ description }) }), requestInfo = (chatUrl) => ({
   method: "POST",
   url: chatUrl,
   urlParams: [],
   headers: { "content-type": "application/json" }
-});
-export const toChatMessages = (prompt) => prompt.content.flatMap((message) => {
-  if (message.role === "system")
-    return [{ role: "system", content: message.content }];
-  if (message.role === "user")
-    return [{ role: "user", content: message.content.flatMap((p) => p.type === "text" ? [p.text] : []).join("") }];
-  if (message.role === "assistant") {
+}), isImageType = Schema.is(ImageMediaType), decodedBytes = (data) => {
+  if (typeof data !== "string")
+    return data.length;
+  const base64 = data.replace(/^data:[^,]*;base64,/i, "").replace(/\s+/g, ""), padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor(base64.length * 3 / 4) - padding);
+}, filePartLabel = (part) => {
+  const data = part.data;
+  return isImageType(part.mediaType) && !(data instanceof URL) ? mediaLabel({ mediaType: part.mediaType, bytes: decodedBytes(data), ...part.fileName === void 0 ? {} : { name: part.fileName } }) : `[file omitted: ${[part.mediaType, ...part.fileName === void 0 ? [] : [part.fileName]].join(", ")}]`;
+}, encodeBase64 = Schema.encodeSync(Schema.Uint8ArrayFromBase64), isSendableImage = (part) => isImageType(part.mediaType), imageUrlPart = (part) => {
+  const data = part.data;
+  return { type: "image_url", image_url: { url: data instanceof URL ? data.toString() : data instanceof Uint8Array ? `data:${part.mediaType};base64,${encodeBase64(data)}` : /^(data:|https?:\/\/)/i.test(data) ? data : `data:${part.mediaType};base64,${data}` } };
+}, nonEmpty = (line) => line.length > 0, toolResultText = (part, images) => part.modelOutput === void 0 ? typeof part.result === "string" ? part.result : JSON.stringify(part.result ?? null) : part.modelOutput.flatMap((output) => output.type === "text" ? [output.text] : images && isSendableImage(output) ? [] : [filePartLabel(output)]).filter(nonEmpty).join(`
+`), userText = (message) => {
+  const text = message.content.flatMap((p) => p.type === "text" ? [p.text] : []).join(""), labels = message.content.flatMap((p) => p.type === "file" ? [filePartLabel(p)] : []);
+  return [text, ...labels].filter(nonEmpty).join(`
+`);
+}, contentParts = (content) => typeof content === "string" ? content.length === 0 ? [] : [{ type: "text", text: content }] : Array.isArray(content) ? content : [], USER_CAPTION = "The user's message:", flush = (fold) => fold.pending.length === 0 ? fold.out : [...fold.out, { role: "user", content: fold.pending }];
+export const toChatMessages = (prompt, options = {}) => {
+  const images = options.images ?? !1, userMessage = (message) => {
+    if (!(images && message.content.some((p) => p.type === "file" && isSendableImage(p))))
+      return { role: "user", content: userText(message) };
+    return {
+      role: "user",
+      content: message.content.flatMap((p) => p.type === "text" ? p.text.length === 0 ? [] : [{ type: "text", text: p.text }] : isSendableImage(p) ? [imageUrlPart(p)] : [{ type: "text", text: filePartLabel(p) }])
+    };
+  }, folded = prompt.content.reduce((fold, message) => {
+    if (message.role === "user") {
+      const user = userMessage(message);
+      if (fold.pending.length === 0)
+        return { out: [...fold.out, user], pending: [] };
+      const parts = contentParts(user.content), own = parts.some((part) => typeof part === "object" && part !== null && ("type" in part) && part.type === "image_url");
+      return { out: [...fold.out, { role: "user", content: [...fold.pending, ...own ? [{ type: "text", text: USER_CAPTION }] : [], ...parts] }], pending: [] };
+    }
+    if (message.role === "tool") {
+      const results = message.content.flatMap((p) => p.type === "tool-result" ? [p] : []), sent = results.flatMap((p) => {
+        const parts = images ? (p.modelOutput ?? []).flatMap((output) => output.type === "file" && isSendableImage(output) ? [output] : []) : [];
+        return parts.length === 0 ? [] : [{ type: "text", text: `Images returned by ${p.name} (call ${p.id}):` }, ...parts.map(imageUrlPart)];
+      }), toolMessages = results.map((p) => {
+        const text = toolResultText(p, images), hasImages = images && (p.modelOutput ?? []).some((output) => output.type === "file" && isSendableImage(output));
+        return { role: "tool", tool_call_id: p.id, content: text.length === 0 && hasImages ? "[the images this call returned follow]" : text };
+      });
+      return { out: [...fold.out, ...toolMessages], pending: [...fold.pending, ...sent] };
+    }
+    const out = flush(fold);
+    if (message.role === "system")
+      return { out: [...out, { role: "system", content: message.content }], pending: [] };
     const text = message.content.flatMap((p) => p.type === "text" ? [p.text] : []).join(""), toolCalls = message.content.flatMap((p) => p.type === "tool-call" ? [
       {
         id: p.id,
@@ -38,22 +78,33 @@ export const toChatMessages = (prompt) => prompt.content.flatMap((message) => {
         function: { name: p.name, arguments: JSON.stringify(p.params ?? {}) }
       }
     ] : []);
-    return [
-      {
+    return {
+      out: [...out, {
         role: "assistant",
         content: text.length > 0 ? text : null,
         ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {}
-      }
-    ];
-  }
-  return message.content.flatMap((p) => p.type === "tool-result" ? [
-    {
-      role: "tool",
-      tool_call_id: p.id,
-      content: typeof p.result === "string" ? p.result : JSON.stringify(p.result ?? null)
-    }
-  ] : []);
-}), toChatTools = (tools) => tools.flatMap((tool) => Tool.isUserDefined(tool) ? [
+      }],
+      pending: []
+    };
+  }, { out: [], pending: [] });
+  return flush(folded);
+}, promptWithImageLabels = (prompt) => Prompt.fromMessages(prompt.content.map((message) => {
+  if (message.role === "user")
+    return message.content.some((p) => p.type === "file") ? Prompt.makeMessage("user", { content: [Prompt.makePart("text", { text: userText(message) })], options: message.options }) : message;
+  if (message.role === "tool")
+    return message.content.some((p) => p.type === "tool-result" && p.modelOutput !== void 0) ? Prompt.makeMessage("tool", {
+      content: message.content.map((p) => p.type !== "tool-result" || p.modelOutput === void 0 ? p : Prompt.makePart("tool-result", {
+        id: p.id,
+        name: p.name,
+        isFailure: p.isFailure,
+        result: toolResultText(p, !1),
+        providerExecuted: p.providerExecuted,
+        options: p.options
+      })),
+      options: message.options
+    }) : message;
+  return message;
+})), toChatTools = (tools) => tools.flatMap((tool) => Tool.isUserDefined(tool) ? [
   {
     type: "function",
     function: {
@@ -81,7 +132,7 @@ export const thinkingParams = (model) => {
   if (/qwen/i.test(model))
     return { enable_thinking: !0 };
   return {};
-}, fromChatCompletion = (moduleName, body) => Effect.gen(function* () {
+}, fromChatCompletion = (moduleName, body, reading = {}) => Effect.gen(function* () {
   const choice = body.choices?.[0];
   if (choice === void 0)
     return yield* Effect.fail(invalidOutput(moduleName, "generateText", "the completion carried no choices"));
@@ -101,7 +152,7 @@ export const thinkingParams = (model) => {
     {
       type: "finish",
       reason: toolCalls.length > 0 ? "tool-calls" : finishReasonFromWire(choice.finish_reason),
-      usage: usageFromCompletion(body.usage)
+      usage: usageFromCompletion(body.usage, reading)
     }
   ];
 });
@@ -124,7 +175,7 @@ const requestSettings = (config, cacheKey, policy) => ({
   return {
     model: config.model,
     ...settings.sampling,
-    messages: toChatMessages(options.prompt),
+    messages: toChatMessages(options.prompt, { images: config.images ?? !1 }),
     stream: streaming,
     ...options.responseFormat.type === "json" ? { response_format: {
       type: "json_schema",
@@ -184,7 +235,7 @@ export const makeCompatLanguageModel = (config) => LanguageModel.make({
       try: () => JSON.parse(text),
       catch: () => invalidOutput(config.moduleName, "generateText", `the completion body was not JSON: ${text.slice(0, 200)}`)
     });
-    return yield* fromChatCompletion(config.moduleName, parsed);
+    return yield* fromChatCompletion(config.moduleName, parsed, config.usage);
   }),
   streamText: (options) => Stream.unwrap(Effect.gen(function* () {
     const res = yield* postChat(config, "streamText", yield* chatRequestBody(config, options, !0));
@@ -193,7 +244,7 @@ export const makeCompatLanguageModel = (config) => LanguageModel.make({
     const body = res.body;
     if (body === null)
       return yield* Effect.fail(invalidOutput(config.moduleName, "streamText", "the streaming response carried no body"));
-    return sseStreamParts({ moduleName: config.moduleName, body });
+    return sseStreamParts({ moduleName: config.moduleName, body, ...config.usage === void 0 ? {} : { usage: config.usage } });
   }))
 }).pipe(Effect.map((model) => describeModel(model, Effect.all({ cacheKey: Effect.service(CurrentPromptCacheKey), policy: Effect.service(CurrentModelCallPolicy) }).pipe(Effect.map(({ cacheKey, policy }) => {
   const settings = requestSettings(config, cacheKey, policy);

package/dist/llm/modelCatalog.d.ts

@@ -1,10 +1,29 @@
 import { Layer } from "effect";
 import { AuthStore, ModelCatalog } from "@xandreed/core";
 import type { Credential, ModelCatalogEntryType } from "@xandreed/core";
-export declare const configuredModelCatalog: (credentials: ReadonlyMap<string, Credential>) => ReadonlyArray<ModelCatalogEntryType>;
+import type { ModelEndpoints } from "../ports/model-endpoints.port.js";
+/** OpenCode serves its GPT models through the OpenAI Responses protocol, the others through chat completions. */
+export declare const usesOpenCodeResponses: (modelId: string) => boolean;
+/**
+ * Whether a built-in route sends a model images: Anthropic's Messages API,
+ * the OpenAI Responses routes (`openai`, `openai-codex` but its text-only
+ * Spark model, OpenCode's `gpt-*`) and Gemini's chat completions do;
+ * OpenCode's other models are text-only until each is verified. A
+ * configured endpoint says so itself (`ModelEndpoint.images`). Where it is
+ * false, a request's images are sent as label lines.
+ */
+export declare const imageInputFor: (selection: string) => boolean;
+/**
+ * The models of every provider with a credential. Each entry's `input` is
+ * what its route reads, as `buildProvider` routes it: `endpoints` (the
+ * models plugin's configured ones; none by default) replace a built-in
+ * route of their name.
+ */
+export declare const configuredModelCatalog: (credentials: ReadonlyMap<string, Credential>, endpoints?: ModelEndpoints) => ReadonlyArray<ModelCatalogEntryType>;
 export type ReasoningEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max";
 /** The reasoning controls accepted by each routed model. `none` on the
  * gpt-5.6 subscription dialect is live-probed (2026-07-16: accepted,
  * reasoning_tokens 0; `minimal` rejected). */
 export declare const reasoningEffortsFor: (selection: string) => ReadonlyArray<ReasoningEffort>;
+/** The catalog over the AuthStore's credentials and the configured endpoints (`CurrentModelEndpoints`). */
 export declare const ConfiguredModelCatalogLive: Layer.Layer<ModelCatalog, never, AuthStore>;

package/dist/llm/modelCatalog.js

@@ -1,5 +1,6 @@
-import { Effect, Layer } from "effect";
-import { AuthStore, ModelCatalog } from "@xandreed/core";
+import { Effect, Layer, Option } from "effect";
+import { AuthStore, ModelCatalog, parseModelSelection } from "@xandreed/core";
+import { CurrentModelEndpoints } from "../ports/model-endpoints.port.js";
 const OPENCODE_MODELS = [
   "glm-5.2",
   "glm-5.1",
@@ -40,11 +41,22 @@ const OPENCODE_MODELS = [
   anthropic: ["claude-fable-5", "claude-haiku-4-5", "claude-opus-4-8", "claude-sonnet-5"],
   google: ["gemini-3-flash", "gemini-3.1-pro", "gemini-3.5-flash"]
 };
-export const configuredModelCatalog = (credentials) => [...credentials].flatMap(([provider, credential]) => (MODELS[provider] ?? []).map((model) => ({
+export const usesOpenCodeResponses = (modelId) => /^gpt-/i.test(modelId);
+const TEXT_ONLY_CODEX = new Set(["gpt-5.3-codex-spark"]);
+export const imageInputFor = (selection) => Option.match(parseModelSelection(selection), {
+  onNone: () => !1,
+  onSome: ({ provider, modelId }) => provider === "anthropic" || provider === "openai" || provider === "google" || provider === "openai-codex" && !TEXT_ONLY_CODEX.has(modelId) || provider === "opencode" && usesOpenCodeResponses(modelId)
+});
+const routeReadsImages = (provider, model, credential, endpoints) => Option.match(Option.fromNullishOr(endpoints[provider]), {
+  onSome: (endpoint) => endpoint.images ?? !1,
+  onNone: () => !(credential.type === "local" && credential.baseUrl !== void 0) && imageInputFor(`${provider}:${model}`)
+});
+export const configuredModelCatalog = (credentials, endpoints = {}) => [...credentials].flatMap(([provider, credential]) => (MODELS[provider] ?? []).map((model) => ({
   selection: `${provider}:${model}`,
   label: provider === "openai-codex" ? `OpenAI subscription \xB7 ${model}` : provider === "openai" ? `OpenAI API key \xB7 ${model}` : void 0,
   provider,
-  credential: credential.type
+  credential: credential.type,
+  input: routeReadsImages(provider, model, credential, endpoints) ? ["text", "image"] : ["text"]
 }))), reasoningEffortsFor = (selection) => {
   if (/^openai-codex:gpt-5\.6-(luna|sol|terra)$/.test(selection))
     return ["none", "low", "medium", "high", "xhigh", "max"];
@@ -53,6 +65,6 @@ export const configuredModelCatalog = (credentials) => [...credentials].flatMap(
   if (/^openai:gpt-5/.test(selection))
     return ["low", "medium", "high"];
   return [];
-}, ConfiguredModelCatalogLive = Layer.effect(ModelCatalog, Effect.map(AuthStore, (auth) => ({
-  list: auth.all.pipe(Effect.orElseSucceed(() => new Map), Effect.map(configuredModelCatalog))
-})));
+}, ConfiguredModelCatalogLive = Layer.effect(ModelCatalog, Effect.all({ auth: AuthStore, endpoints: Effect.service(CurrentModelEndpoints) }).pipe(Effect.map(({ auth, endpoints }) => ({
+  list: auth.all.pipe(Effect.orElseSucceed(() => new Map), Effect.map((credentials) => configuredModelCatalog(credentials, endpoints)))
+}))));

package/dist/llm/openAiCodex.d.ts

@@ -1,6 +1,7 @@
 import { LanguageModel } from "effect/ai";
 import { HttpClient } from "effect/http";
-import { Effect, Redacted } from "effect";
+import { Effect, Option, Redacted } from "effect";
+import type { WebSocketProxy } from "../ports/models-transport.port.js";
 export declare const OPENAI_CODEX_API_URL = "https://chatgpt.com/backend-api/codex";
 type Json = Record<string, unknown>;
 /** Translate the standard Responses request into the Codex subscription dialect. */
@@ -10,5 +11,7 @@ export declare const makeOpenAiCodexLanguageModel: (args: {
     readonly model: string;
     readonly accessToken: Redacted.Redacted<string>;
     readonly accountId: string;
+    /** How the WebSocket reaches ChatGPT (`ModelsTransport.webSocketAgent`); default: directly. */
+    readonly webSocketProxy?: Option.Option<WebSocketProxy>;
 }) => Effect.Effect<LanguageModel.LanguageModel, never, HttpClient.HttpClient>;
 export {};

package/dist/llm/openAiCodex.js

@@ -3,7 +3,7 @@ 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 { makeOpenAiCodexWebSocketHttpClient } from "./openAiCodexWebSocket.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);
@@ -69,7 +69,7 @@ export const mapOpenAiCodexError = (model, error) => responseStatus(error) === 4
 }).pipe(Effect.flatMap(({ cacheKey, policy }) => 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)))))
+  transformClient: () => makeOpenAiCodexWebSocketHttpClient(args.webSocketProxy ?? Option.none()).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({
   model: args.model,
   config: {

package/dist/llm/openAiCodexWebSocket.d.ts

@@ -1,4 +1,7 @@
-import { HttpClient } from "effect/http";
+import { HttpClient, HttpClientError } from "effect/http";
+import { Option } from "effect";
+import type { WebSocketProxy } from "../ports/models-transport.port.js";
+type Json = Record<string, unknown>;
 /** 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. */
@@ -6,9 +9,26 @@ export declare const openAiCodexUuidV7: (now?: number) => string;
 /** 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;
+/**
+ * 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<Json>;
 export declare const isOpenAiCodexControlEvent: (type: unknown) => boolean;
 /** 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.
+ * The response is the stream once the first event arrives, unless that
+ * event is an `error` refusing the request (`openAiCodexRefusal`): the
+ * request then fails with a 400 status and the OpenAI error body, as the
+ * HTTP endpoint answers it, so a refused image is an `InvalidRequestError`. */
+export declare const makeOpenAiCodexWebSocketHttpClient: (proxy: Option.Option<WebSocketProxy>) => HttpClient.HttpClient.With<HttpClientError.HttpClientError, never>;
+/** The subscription client connecting directly, with no proxy. */
+export declare const OpenAiCodexWebSocketHttpClient: HttpClient.HttpClient.With<HttpClientError.HttpClientError, never>;
+export {};

package/dist/llm/openAiCodexWebSocket.js

@@ -1,7 +1,9 @@
 import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
-import { Effect, Result } from "effect";
+import { Effect, Match, Option, Redacted, Result } from "effect";
 import { release } from "node:os";
 import WebSocket from "ws";
+import { redactCredentials } from "../transport/http-proxy.entity.functions.js";
+import { currentRuntime } from "../transport/models-transport.adapter.js";
 const WEBSOCKET_BETA = "responses_websockets=2026-02-06", sessionIds = new Map, decodeBody = (request) => {
   if (request.body._tag !== "Uint8Array")
     return {};
@@ -46,77 +48,129 @@ export const normalizeOpenAiCodexWebSocketEvent = (value) => {
     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;
+};
+const recordOf = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? Option.some(value) : Option.none(), stringOf = (value) => typeof value === "string" ? Option.some(value) : Option.none();
+export const openAiCodexRefusal = (event) => Option.flatMap(Option.filter(recordOf(event), (frame) => frame.type === "error"), (frame) => {
+  const error = Option.getOrElse(recordOf(frame.error), () => frame), message = Option.getOrElse(stringOf(error.message), () => ""), type = stringOf(error.type), code = stringOf(error.code);
+  return frame.status === 400 || /image/i.test(message) || Option.contains(type, "invalid_request_error") || Option.contains(code, "invalid_request_error") ? Option.some({ error: {
+    message: message.length > 0 ? message : "the request was refused",
+    type: Option.getOrElse(Option.filter(type, (value) => value !== "error"), () => "invalid_request_error"),
+    code: Option.getOrNull(code),
+    param: Option.getOrNull(stringOf(error.param))
+  } }) : Option.none();
+}), isOpenAiCodexControlEvent = (type) => typeof type === "string" && (type.startsWith("codex.") || type === "responsesapi.websocket_timing");
+const wsSocket = (socket) => ({
+  send: (data) => socket.send(data),
+  close: (code, reason) => socket.close(code, reason),
+  onOpen: (listener) => socket.addEventListener("open", () => listener()),
+  onMessage: (listener) => socket.addEventListener("message", (event) => listener(event.data)),
+  onError: (listener) => socket.addEventListener("error", (event) => listener(event.error instanceof Error ? event.error : Error(event.message || "WebSocket handshake failed"))),
+  onClose: (listener) => socket.addEventListener("close", (event) => listener(event.code, event.reason))
+}), bunSocket = (url, options) => {
+  const socket = Reflect.construct(globalThis.WebSocket, [url, options]);
+  return {
+    send: (data) => socket.send(data),
+    close: (code, reason) => socket.close(code, reason),
+    onOpen: (listener) => socket.addEventListener("open", () => listener()),
+    onMessage: (listener) => socket.addEventListener("message", (event) => listener(event.data)),
+    onError: (listener) => socket.addEventListener("error", (event) => listener(Error("message" in event && typeof event.message === "string" && event.message.length > 0 ? event.message : "WebSocket handshake failed"))),
+    onClose: (listener) => socket.addEventListener("close", (event) => listener(event.code, event.reason))
+  };
+}, openSocket = (url, headers, proxy) => Option.match(proxy, {
+  onNone: () => wsSocket(new WebSocket(url, { headers })),
+  onSome: (route) => Match.value(route).pipe(Match.tag("Agent", ({ agent }) => wsSocket(new WebSocket(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`));
+}, transportFailure = (request, 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: ${redactCredentials(cause instanceof Error ? cause.message : String(cause))}`,
+    cause
+  })
+});
+export const makeOpenAiCodexWebSocketHttpClient = (proxy) => HttpClient.make((request, url, signal) => Option.match(Option.flatMap(proxy, routeMismatch), {
+  onSome: (why) => Effect.fail(transportFailure(request, Error(why))),
+  onNone: () => 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 = openSocket(websocketUrl(url), headers, proxy), state = { phase: "connecting" }, stream = new ReadableStream({
+        start: (value) => {
+          state.controller = value;
+        },
+        cancel: () => socket.close(1000, "cancelled")
+      }), respond = (response) => {
+        state.phase = "settled";
+        resolve(HttpClientResponse.fromWeb(safeRequest, response));
+      }, streaming = () => {
+        if (state.phase === "sent")
+          respond(new Response(stream, { status: 200, headers: { "content-type": "text/event-stream" } }));
+      }, fail = (cause) => {
+        if (state.phase === "connecting") {
+          state.phase = "settled";
+          reject(cause);
+        } else {
+          streaming();
+          state.controller?.error(cause);
         }
-        state.controller?.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(parsed)}
+        socket.close(1011, "transport error");
+      }, abort = () => fail(Error("OpenAI subscription request aborted"));
+      signal.addEventListener("abort", abort, { once: !0 });
+      socket.onOpen(() => {
+        Result.match(Result.try(() => {
+          socket.send(JSON.stringify({ type: "response.create", ...body }));
+          state.phase = "sent";
+        }), { onFailure: fail, onSuccess: () => {
+          return;
+        } });
+      });
+      socket.onMessage((data) => {
+        Result.match(Result.try(() => {
+          const text = eventText(data);
+          if (text === void 0)
+            return;
+          const parsed = normalizeOpenAiCodexWebSocketEvent(JSON.parse(text)), type = parsed.type;
+          if (isOpenAiCodexControlEvent(type))
+            return;
+          const refused = state.phase === "sent" ? openAiCodexRefusal(parsed) : Option.none();
+          if (Option.isSome(refused)) {
+            respond(new Response(JSON.stringify(refused.value), { status: 400, headers: { "content-type": "application/json" } }));
+            signal.removeEventListener("abort", abort);
+            socket.close(1000, "refused");
+            return;
+          }
+          streaming();
+          if (type === "error") {
+            fail(Error(JSON.stringify(parsed)));
+            return;
+          }
+          state.controller?.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(parsed)}
 
 `));
-        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
-    })
+          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.onError(fail);
+      socket.onClose((code, reason) => {
+        if (code !== 1000)
+          fail(Error(`OpenAI subscription WebSocket closed ${code}: ${reason}`));
+      });
+    }),
+    catch: (cause) => transportFailure(request, cause)
   })
-}));
+})).pipe(HttpClient.filterStatusOk), OpenAiCodexWebSocketHttpClient = makeOpenAiCodexWebSocketHttpClient(Option.none());

package/dist/llm/openAiCodexWebSocket.test.d.ts

@@ -0,0 +1 @@
+export {};