@parall/codex-agent 1.26.3 → 1.27.0

package/dist/dispatch.d.ts

@@ -5,6 +5,7 @@ type CodexAppServerAdapterOptions = Pick<CodexAgentConfig, "approvalPolicy" | "c
     sessionManager: CodexSessionManager;
     log?: GatewayLogger;
     contextFilePath?: string;
+    useParallProvider?: boolean;
 };
 /**
  * Bridge driver backed by `codex app-server --listen stdio://`.

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IA6B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA5BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAE/D,YAAY,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAK/E,QAAQ,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IAgLxG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMjD,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAuBhG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKhB,IAAI;YAaI,aAAa;YAyBb,OAAO;IA8DrB,OAAO,CAAC,qBAAqB;YAiCf,UAAU;IAwCxB,OAAO,CAAC,iBAAiB;CA2B1B"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IA6B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA5BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAE/D,YAAY,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAK/E,QAAQ,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IAwMxG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMjD,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAuBhG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKhB,IAAI;YAaI,aAAa;YAyBb,OAAO;IA8DrB,OAAO,CAAC,qBAAqB;YAiCf,UAAU;IA2CxB,OAAO,CAAC,iBAAiB;CA2B1B"}

package/dist/dispatch.js

@@ -163,6 +163,11 @@ export class CodexAppServerAdapter {
                 // resume normally instead of permanently losing conversation context.
                 // Fork sessions don't retry: agent-core spawns a fresh fork next trigger.
                 if (!isMainSession) {
+                    yield {
+                        type: "runtime_session",
+                        runtimeSessionId: threadId,
+                        runtimeLaneKey: sessionKey,
+                    };
                     yield { type: "error", message: `Codex turn/start failed: ${message}` };
                     return;
                 }
@@ -173,6 +178,11 @@ export class CodexAppServerAdapter {
                     freshThreadId = await this.openThread(client, { resumeId: undefined });
                 }
                 catch (createErr) {
+                    yield {
+                        type: "runtime_session",
+                        runtimeSessionId: threadId,
+                        runtimeLaneKey: sessionKey,
+                    };
                     yield { type: "error", message: `Codex turn/start failed; could not create replacement thread: ${errToString(createErr)}` };
                     return;
                 }
@@ -185,6 +195,11 @@ export class CodexAppServerAdapter {
                     // issue. Don't clobber the persisted threadId; next dispatch will try
                     // resume again.
                     this.activeTurns.delete(freshThreadId);
+                    yield {
+                        type: "runtime_session",
+                        runtimeSessionId: threadId,
+                        runtimeLaneKey: sessionKey,
+                    };
                     yield { type: "error", message: `Codex turn/start failed after retry: ${errToString(retryErr)}` };
                     return;
                 }
@@ -196,6 +211,11 @@ export class CodexAppServerAdapter {
                 threadId = freshThreadId;
             }
             void turnStartResult; // turnId comes back here but isn't needed — we key by threadId
+            yield {
+                type: "runtime_session",
+                runtimeSessionId: threadId,
+                runtimeLaneKey: sessionKey,
+            };
             while (true) {
                 const envelope = await sink.next();
                 if (envelope.kind === "turn_end") {
@@ -211,6 +231,10 @@ export class CodexAppServerAdapter {
                     yield runtimeEvent;
                     continue;
                 }
+                if (runtimeEvent.type === "runtime_session") {
+                    yield runtimeEvent;
+                    continue;
+                }
                 if (runtimeEvent.type === "text") {
                     // Layer 0 symmetric output contract: Codex's plain text is never
                     // projected as a chat message. Outbound messages must come from the
@@ -407,6 +431,9 @@ export class CodexAppServerAdapter {
         const commonParams = {
             approvalPolicy: normalizeApprovalPolicy(this.opts.approvalPolicy),
         };
+        if (this.opts.useParallProvider) {
+            commonParams.modelProvider = "parall";
+        }
         commonParams.sandbox = normalizeSandbox(this.opts.sandbox);
         if (this.opts.model)
             commonParams.model = this.opts.model;

package/dist/index.js

@@ -5,7 +5,7 @@ import { ApiError, ParallClient, ParallWs } from "@parall/sdk";
 import { buildCodexRuntimeKey, contextFilePathForSession, resolveCodexAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from "./config.js";
 import { CodexAppServerAdapter } from "./dispatch.js";
 import { CodexSessionManager } from "./session-manager.js";
-import { ensureCodexWorkspace, ensureWorkspaceTrusted } from "./workspace.js";
+import { ensureCodexWorkspace, ensureParallProvider, ensureWorkspaceTrusted, isParallProxyMode } from "./workspace.js";
 function createLogger(prefix) {
     return {
         info: (msg) => console.log(`[${prefix}] ${msg}`),
@@ -36,6 +36,11 @@ async function main() {
     const me = await getAgentMeWithLegacyFallback(client, config.orgId);
     const agentUserId = me.id;
     ensureWorkspaceTrusted(config.codexHome, config.workspaceDir, log);
+    const useParallProvider = isParallProxyMode();
+    if (useParallProvider) {
+        ensureParallProvider(config.codexHome, config.apiUrl, log);
+        log.info("parall custom provider configured (Responses API HTTP/SSE mode)");
+    }
     ensureCodexWorkspace(config.workspaceDir, log, {
         userId: agentUserId,
         displayName: me.display_name,
@@ -70,6 +75,7 @@ async function main() {
         sessionManager,
         log,
         contextFilePath: mainContextFilePath,
+        useParallProvider,
     });
     const gateway = new ParallAgentGateway({
         accountId: agentUserId,

package/dist/workspace.d.ts

@@ -12,6 +12,29 @@ import type { AgentIdentity } from "@parall/agent-core";
 export declare function ensureWorkspaceTrusted(codexHome: string, workspaceDir: string, log?: {
     warn: (msg: string) => void;
 }): void;
+/**
+ * Returns true when the agent is using the Parall LLM proxy (llm_source=parall)
+ * rather than a BYO custom provider or runtime_auth. Detected by checking
+ * whether OPENAI_BASE_URL points to the Parall API.
+ */
+export declare function isParallProxyMode(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Ensure a custom `parall` model provider is configured in the global Codex
+ * config. Codex CLI's built-in `openai` provider hardcodes
+ * `wss://api.openai.com` for the Responses API, ignoring OPENAI_BASE_URL.
+ * A custom provider with `supports_websockets = false` forces HTTP/SSE
+ * transport that correctly routes through `base_url`.
+ *
+ * Only written when the agent uses the Parall proxy (llm_source=parall).
+ * BYO custom providers (llm_source=custom) use the built-in openai
+ * provider with their own real API key, which works with the hardcoded
+ * api.openai.com endpoint.
+ *
+ * Provider-managed: overwritten on every boot (env vars are the SSOT).
+ */
+export declare function ensureParallProvider(codexHome: string, apiUrl: string, log?: {
+    warn: (msg: string) => void;
+}): void;
 export declare function ensureCodexWorkspace(workspaceDir: string, log?: {
     warn: (msg: string) => void;
 }, agentIdentity?: AgentIdentity): void;

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAyEN;AASD,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,CAqBN"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CAyEN;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAK/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpC,IAAI,CA+CN;AASD,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,CAqBN"}

package/dist/workspace.js

@@ -91,6 +91,80 @@ export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
         log?.warn(`failed to write Codex project trust for ${normalizedPath}: ${String(err)}`);
     }
 }
+/**
+ * Returns true when the agent is using the Parall LLM proxy (llm_source=parall)
+ * rather than a BYO custom provider or runtime_auth. Detected by checking
+ * whether OPENAI_BASE_URL points to the Parall API.
+ */
+export function isParallProxyMode(env = process.env) {
+    const baseUrl = env.OPENAI_BASE_URL?.trim()?.replace(/\/+$/, "");
+    const apiUrl = env.PRLL_API_URL?.trim()?.replace(/\/+$/, "");
+    if (!baseUrl || !apiUrl)
+        return false;
+    return baseUrl === apiUrl || baseUrl.startsWith(`${apiUrl}/`);
+}
+/**
+ * Ensure a custom `parall` model provider is configured in the global Codex
+ * config. Codex CLI's built-in `openai` provider hardcodes
+ * `wss://api.openai.com` for the Responses API, ignoring OPENAI_BASE_URL.
+ * A custom provider with `supports_websockets = false` forces HTTP/SSE
+ * transport that correctly routes through `base_url`.
+ *
+ * Only written when the agent uses the Parall proxy (llm_source=parall).
+ * BYO custom providers (llm_source=custom) use the built-in openai
+ * provider with their own real API key, which works with the hardcoded
+ * api.openai.com endpoint.
+ *
+ * Provider-managed: overwritten on every boot (env vars are the SSOT).
+ */
+export function ensureParallProvider(codexHome, apiUrl, log) {
+    const configPath = path.join(codexHome, "config.toml");
+    const baseUrl = apiUrl.replace(/\/$/, "") + "/api/llm/v1";
+    try {
+        let content = "";
+        try {
+            content = fs.readFileSync(configPath, "utf8");
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        const sectionHeader = "[model_providers.parall]";
+        const authHeader = "[model_providers.parall.auth]";
+        const providerBlock = [
+            sectionHeader,
+            'name = "Parall Proxy"',
+            `base_url = "${baseUrl}"`,
+            'wire_api = "responses"',
+            "supports_websockets = false",
+            "requires_openai_auth = false",
+            "",
+            authHeader,
+            'command = "printenv"',
+            'args = ["OPENAI_API_KEY"]',
+        ].join("\n");
+        const headerIdx = content.indexOf(sectionHeader);
+        if (headerIdx !== -1) {
+            const sectionEnd = findSectionEnd(content, headerIdx + sectionHeader.length + 1);
+            // Only consume a contiguous [model_providers.parall.auth] subtable —
+            // one that sits within the provider's own section, not after unrelated
+            // tables that happen to appear between provider and auth.
+            const authIdx = content.indexOf(authHeader, headerIdx);
+            const blockEnd = authIdx !== -1 && authIdx < sectionEnd
+                ? findSectionEnd(content, authIdx + authHeader.length + 1)
+                : sectionEnd;
+            content = content.substring(0, headerIdx) + providerBlock + content.substring(blockEnd);
+        }
+        else {
+            content = content.trimEnd() + "\n\n" + providerBlock + "\n";
+        }
+        fs.mkdirSync(codexHome, { recursive: true });
+        fs.writeFileSync(configPath, content, "utf8");
+    }
+    catch (err) {
+        throw new Error(`failed to write Parall provider config: ${String(err)}`);
+    }
+}
 function findSectionEnd(content, fromIndex) {
     // A TOML section ends at the next `[` that starts a new table header.
     // Match `[` at the beginning of a line (not inside a value).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.26.3",
+  "version": "1.27.0",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -26,9 +26,9 @@
   ],
   "dependencies": {
     "smol-toml": "^1.6.1",
-    "@parall/agent-core": "1.26.3",
-    "@parall/cli": "1.26.3",
-    "@parall/sdk": "1.26.3"
+    "@parall/agent-core": "1.27.0",
+    "@parall/sdk": "1.27.0",
+    "@parall/cli": "1.27.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch.ts

@@ -36,6 +36,7 @@ type CodexAppServerAdapterOptions = Pick<
   sessionManager: CodexSessionManager;
   log?: GatewayLogger;
   contextFilePath?: string;
+  useParallProvider?: boolean;
 };
 
 type TurnEventEnvelope =
@@ -200,6 +201,11 @@ export class CodexAppServerAdapter implements DispatchAdapter {
         // resume normally instead of permanently losing conversation context.
         // Fork sessions don't retry: agent-core spawns a fresh fork next trigger.
         if (!isMainSession) {
+          yield {
+            type: "runtime_session",
+            runtimeSessionId: threadId,
+            runtimeLaneKey: sessionKey,
+          };
           yield { type: "error", message: `Codex turn/start failed: ${message}` };
           return;
         }
@@ -209,6 +215,11 @@ export class CodexAppServerAdapter implements DispatchAdapter {
         try {
           freshThreadId = await this.openThread(client, { resumeId: undefined });
         } catch (createErr) {
+          yield {
+            type: "runtime_session",
+            runtimeSessionId: threadId,
+            runtimeLaneKey: sessionKey,
+          };
           yield { type: "error", message: `Codex turn/start failed; could not create replacement thread: ${errToString(createErr)}` };
           return;
         }
@@ -220,6 +231,11 @@ export class CodexAppServerAdapter implements DispatchAdapter {
           // issue. Don't clobber the persisted threadId; next dispatch will try
           // resume again.
           this.activeTurns.delete(freshThreadId);
+          yield {
+            type: "runtime_session",
+            runtimeSessionId: threadId,
+            runtimeLaneKey: sessionKey,
+          };
           yield { type: "error", message: `Codex turn/start failed after retry: ${errToString(retryErr)}` };
           return;
         }
@@ -232,6 +248,11 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       }
 
       void turnStartResult; // turnId comes back here but isn't needed — we key by threadId
+      yield {
+        type: "runtime_session",
+        runtimeSessionId: threadId,
+        runtimeLaneKey: sessionKey,
+      };
 
       while (true) {
         const envelope = await sink.next();
@@ -248,6 +269,10 @@ export class CodexAppServerAdapter implements DispatchAdapter {
           yield runtimeEvent;
           continue;
         }
+        if (runtimeEvent.type === "runtime_session") {
+          yield runtimeEvent;
+          continue;
+        }
         if (runtimeEvent.type === "text") {
           // Layer 0 symmetric output contract: Codex's plain text is never
           // projected as a chat message. Outbound messages must come from the
@@ -456,6 +481,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     const commonParams: Record<string, unknown> = {
       approvalPolicy: normalizeApprovalPolicy(this.opts.approvalPolicy),
     };
+    if (this.opts.useParallProvider) {
+      commonParams.modelProvider = "parall";
+    }
     commonParams.sandbox = normalizeSandbox(this.opts.sandbox);
     if (this.opts.model) commonParams.model = this.opts.model;
     if (this.opts.reasoningEffort) {

package/src/index.ts

@@ -13,7 +13,7 @@ import {
 } from "./config.js";
 import { CodexAppServerAdapter } from "./dispatch.js";
 import { CodexSessionManager } from "./session-manager.js";
-import { ensureCodexWorkspace, ensureWorkspaceTrusted } from "./workspace.js";
+import { ensureCodexWorkspace, ensureParallProvider, ensureWorkspaceTrusted, isParallProxyMode } from "./workspace.js";
 
 function createLogger(prefix: string) {
   return {
@@ -48,6 +48,11 @@ async function main() {
   const me = await getAgentMeWithLegacyFallback(client, config.orgId);
   const agentUserId = me.id;
   ensureWorkspaceTrusted(config.codexHome, config.workspaceDir, log);
+  const useParallProvider = isParallProxyMode();
+  if (useParallProvider) {
+    ensureParallProvider(config.codexHome, config.apiUrl, log);
+    log.info("parall custom provider configured (Responses API HTTP/SSE mode)");
+  }
   ensureCodexWorkspace(config.workspaceDir, log, {
     userId: agentUserId,
     displayName: me.display_name,
@@ -87,6 +92,7 @@ async function main() {
     sessionManager,
     log,
     contextFilePath: mainContextFilePath,
+    useParallProvider,
   });
 
   const gateway = new ParallAgentGateway({

package/src/workspace.ts

@@ -100,6 +100,85 @@ export function ensureWorkspaceTrusted(
   }
 }
 
+/**
+ * Returns true when the agent is using the Parall LLM proxy (llm_source=parall)
+ * rather than a BYO custom provider or runtime_auth. Detected by checking
+ * whether OPENAI_BASE_URL points to the Parall API.
+ */
+export function isParallProxyMode(env: NodeJS.ProcessEnv = process.env): boolean {
+  const baseUrl = env.OPENAI_BASE_URL?.trim()?.replace(/\/+$/, "");
+  const apiUrl = env.PRLL_API_URL?.trim()?.replace(/\/+$/, "");
+  if (!baseUrl || !apiUrl) return false;
+  return baseUrl === apiUrl || baseUrl.startsWith(`${apiUrl}/`);
+}
+
+/**
+ * Ensure a custom `parall` model provider is configured in the global Codex
+ * config. Codex CLI's built-in `openai` provider hardcodes
+ * `wss://api.openai.com` for the Responses API, ignoring OPENAI_BASE_URL.
+ * A custom provider with `supports_websockets = false` forces HTTP/SSE
+ * transport that correctly routes through `base_url`.
+ *
+ * Only written when the agent uses the Parall proxy (llm_source=parall).
+ * BYO custom providers (llm_source=custom) use the built-in openai
+ * provider with their own real API key, which works with the hardcoded
+ * api.openai.com endpoint.
+ *
+ * Provider-managed: overwritten on every boot (env vars are the SSOT).
+ */
+export function ensureParallProvider(
+  codexHome: string,
+  apiUrl: string,
+  log?: { warn: (msg: string) => void },
+): void {
+  const configPath = path.join(codexHome, "config.toml");
+  const baseUrl = apiUrl.replace(/\/$/, "") + "/api/llm/v1";
+
+  try {
+    let content = "";
+    try {
+      content = fs.readFileSync(configPath, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+
+    const sectionHeader = "[model_providers.parall]";
+    const authHeader = "[model_providers.parall.auth]";
+    const providerBlock = [
+      sectionHeader,
+      'name = "Parall Proxy"',
+      `base_url = "${baseUrl}"`,
+      'wire_api = "responses"',
+      "supports_websockets = false",
+      "requires_openai_auth = false",
+      "",
+      authHeader,
+      'command = "printenv"',
+      'args = ["OPENAI_API_KEY"]',
+    ].join("\n");
+
+    const headerIdx = content.indexOf(sectionHeader);
+    if (headerIdx !== -1) {
+      const sectionEnd = findSectionEnd(content, headerIdx + sectionHeader.length + 1);
+      // Only consume a contiguous [model_providers.parall.auth] subtable —
+      // one that sits within the provider's own section, not after unrelated
+      // tables that happen to appear between provider and auth.
+      const authIdx = content.indexOf(authHeader, headerIdx);
+      const blockEnd = authIdx !== -1 && authIdx < sectionEnd
+        ? findSectionEnd(content, authIdx + authHeader.length + 1)
+        : sectionEnd;
+      content = content.substring(0, headerIdx) + providerBlock + content.substring(blockEnd);
+    } else {
+      content = content.trimEnd() + "\n\n" + providerBlock + "\n";
+    }
+
+    fs.mkdirSync(codexHome, { recursive: true });
+    fs.writeFileSync(configPath, content, "utf8");
+  } catch (err) {
+    throw new Error(`failed to write Parall provider config: ${String(err)}`);
+  }
+}
+
 function findSectionEnd(content: string, fromIndex: number): number {
   // A TOML section ends at the next `[` that starts a new table header.
   // Match `[` at the beginning of a line (not inside a value).