@parall/codex-agent 1.31.0 → 1.32.1

package/src/index.ts

@@ -1,8 +1,24 @@
 #!/usr/bin/env node
 
-import * as os from "node:os";
-import { ParallAgentGateway, createPlatformConfigManager, createLogger, childLogger, isPlatformManagedProfile, parseShutdownDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource } from "@parall/agent-core";
-import { ApiError, ParallClient, ParallWs } from "@parall/sdk";
+import * as os from 'node:os';
+import {
+  ParallAgentGateway,
+  createPlatformConfigManager,
+  createLogger,
+  createOtelLogger,
+  childLogger,
+  isPlatformManagedProfile,
+  isPlatformModelOverride,
+  resolveRuntimeModel,
+  parseShutdownDeadlineMs,
+  parseForkDeadlineMs,
+  parseDispatchDeadlineMs,
+  parseProviderConfig,
+  clearAllProviderCreds,
+  llmSource,
+  initAgentTelemetry,
+} from '@parall/agent-core';
+import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import {
   buildCodexRuntimeKey,
   contextFilePathForSession,
@@ -10,12 +26,17 @@ import {
   resolveWsUrl,
   sessionStateFilePathForRuntime,
   stepIdFilePathForSession,
-} from "./config.js";
-import { CodexAppServerAdapter } from "./dispatch.js";
-import { CodexSessionManager } from "./session-manager.js";
-import { ensureCodexWorkspace, ensureParallProvider, ensureWorkspaceTrusted, isParallProxyMode } from "./workspace.js";
+} from './config.js';
+import { CodexAppServerAdapter } from './dispatch.js';
+import { CodexSessionManager } from './session-manager.js';
+import {
+  ensureCodexWorkspace,
+  ensureParallProvider,
+  ensureWorkspaceTrusted,
+  isParallProxyMode,
+} from './workspace.js';
 
-const log = createLogger("codex-agent");
+const log = createLogger('codex-agent');
 let activeLog = log;
 
 async function getAgentMeWithLegacyFallback(client: ParallClient, orgId: string) {
@@ -35,136 +56,181 @@ function resolveProviderEnv(): void {
   if (!pc) return;
   clearAllProviderCreds(process.env);
   const source = llmSource(pc);
-  if (source === "parall") {
+  if (source === 'parall') {
     process.env.OPENAI_API_KEY = process.env.PRLL_API_KEY;
     process.env.OPENAI_BASE_URL = `${process.env.PRLL_API_URL}/api/llm/v1`;
-  } else if (source === "custom") {
+  } else if (source === 'custom') {
     if (pc.openai_api_key) process.env.OPENAI_API_KEY = pc.openai_api_key;
     if (pc.openai_base_url) process.env.OPENAI_BASE_URL = pc.openai_base_url;
   }
 }
 
 async function main() {
-  resolveProviderEnv();
-  const config = resolveCodexAgentConfig(process.env);
+  const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex');
+  activeLog = createOtelLogger('agent', 'codex-agent');
+  try {
+    resolveProviderEnv();
+    const config = resolveCodexAgentConfig(process.env);
 
-  const client = new ParallClient({
-    baseUrl: config.apiUrl,
-    token: config.apiKey,
-    swimlaneName: config.swimlaneName,
-  });
+    const client = new ParallClient({
+      baseUrl: config.apiUrl,
+      token: config.apiKey,
+      swimlaneName: config.swimlaneName,
+    });
 
-  const me = await getAgentMeWithLegacyFallback(client, config.orgId);
-  const agentUserId = me.id;
-  const agentLog = childLogger(log, agentUserId);
-  activeLog = agentLog;
-  ensureWorkspaceTrusted(config.codexHome, config.workspaceDir, agentLog);
-  const useParallProvider = isParallProxyMode();
-  if (useParallProvider) {
-    ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
-    agentLog.info("parall custom provider configured (Responses API HTTP/SSE mode)");
-  }
-  ensureCodexWorkspace(config.workspaceDir, agentLog, {
-    userId: agentUserId,
-    displayName: me.display_name,
-    description: me.agent_profile?.description ?? undefined,
-  });
-  const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
-  const mainContextFilePath = contextFilePathForSession(config.stateDir, runtimeKey);
-  const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
-  const sessionManager = new CodexSessionManager(
-    runtimeKey,
-    sessionStateFilePath,
-    agentLog,
-  );
+    const me = await getAgentMeWithLegacyFallback(client, config.orgId);
+    const agentUserId = me.id;
+    const agentLog = childLogger(activeLog, agentUserId);
+    activeLog = agentLog;
+    ensureWorkspaceTrusted(config.codexHome, config.workspaceDir, agentLog);
+    const useParallProvider = isParallProxyMode();
+    if (useParallProvider) {
+      ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
+      agentLog.info('parall custom provider configured (Responses API HTTP/SSE mode)');
+    }
+    ensureCodexWorkspace(config.workspaceDir, agentLog, {
+      userId: agentUserId,
+      displayName: me.display_name,
+      description: me.agent_profile?.description ?? undefined,
+    });
+    const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
+    const mainContextFilePath = contextFilePathForSession(config.stateDir, runtimeKey);
+    const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
+    const sessionManager = new CodexSessionManager(runtimeKey, sessionStateFilePath, agentLog);
 
-  const resolvedWsUrl = resolveWsUrl(config.apiUrl, config.wsUrl, config.swimlaneName);
-  const ws = new ParallWs({
-    getTicket: () => client.getWsTicket(),
-    wsUrl: resolvedWsUrl,
-  });
+    const resolvedWsUrl = resolveWsUrl(config.apiUrl, config.wsUrl, config.swimlaneName);
+    const ws = new ParallWs({
+      getTicket: () => client.getWsTicket(),
+      wsUrl: resolvedWsUrl,
+    });
 
-  const configMgr = createPlatformConfigManager({ client, stateDir: config.stateDir, runtimeType: "codex", log: agentLog });
-  const platformDefaults = await configMgr.fetch();
-  let platformManaged = isPlatformManagedProfile(me.agent_profile);
-  const resolvedModel = platformManaged ? (platformDefaults.model ?? config.model) : config.model;
-  const resolvedEffort = platformManaged ? (platformDefaults.thinkingEffort ?? config.reasoningEffort) : config.reasoningEffort;
-  if (platformDefaults.model) agentLog.info(`platform config: model=${platformDefaults.model} (${platformManaged ? "applied" : "ignored, model_management=self"})`);
-  if (platformDefaults.thinkingEffort) agentLog.info(`platform config: reasoning_effort=${platformDefaults.thinkingEffort} (${platformManaged ? "applied" : "ignored, model_management=self"})`);
+    const configMgr = createPlatformConfigManager({
+      client,
+      stateDir: config.stateDir,
+      runtimeType: 'codex',
+      log: agentLog,
+    });
+    const platformDefaults = await configMgr.fetch();
+    let platformManaged = isPlatformManagedProfile(me.agent_profile);
+    // Model precedence: operator override (platform-managed) > env > server floor.
+    // The server delivers a model floor for Parall-proxy routes even when
+    // model_management=self, so the CLI never falls back to a built-in default
+    // the catalog might reject — but that floor must lose to an explicit env
+    // override. A profile is an operator-override only when it is platform-managed
+    // AND not explicitly self-managed: this treats legacy hosted agents
+    // (model_management=null, resolved to platform server-side) as overrides,
+    // while excluding local self agents whose delivered model is a floor.
+    // reasoning_effort stays an operator override (platform).
+    let platformModelOverride = isPlatformModelOverride(me.agent_profile);
+    const resolvedModel = resolveRuntimeModel(
+      platformModelOverride,
+      platformDefaults.model,
+      config.model,
+    );
+    const resolvedEffort = platformManaged
+      ? (platformDefaults.thinkingEffort ?? config.reasoningEffort)
+      : config.reasoningEffort;
+    if (platformDefaults.model)
+      agentLog.info(
+        `platform config: model=${platformDefaults.model} → resolved=${resolvedModel ?? 'cli-default'} (${platformModelOverride ? 'platform-managed' : 'floor/self'})`,
+      );
+    if (platformDefaults.thinkingEffort)
+      agentLog.info(
+        `platform config: reasoning_effort=${platformDefaults.thinkingEffort} (${platformModelOverride ? 'applied' : 'ignored, model_management=self'})`,
+      );
 
-  const adapter = new CodexAppServerAdapter({
-    codexBin: config.codexBin,
-    codexHome: config.codexHome,
-    workspaceDir: config.workspaceDir,
-    model: resolvedModel,
-    reasoningEffort: resolvedEffort,
-    sandbox: config.sandbox,
-    approvalPolicy: config.approvalPolicy,
-    sessionManager,
-    log: agentLog,
-    contextFilePath: mainContextFilePath,
-    useParallProvider,
-  });
+    const adapter = new CodexAppServerAdapter({
+      codexBin: config.codexBin,
+      codexHome: config.codexHome,
+      workspaceDir: config.workspaceDir,
+      model: resolvedModel,
+      reasoningEffort: resolvedEffort,
+      sandbox: config.sandbox,
+      approvalPolicy: config.approvalPolicy,
+      sessionManager,
+      log: agentLog,
+      contextFilePath: mainContextFilePath,
+      useParallProvider,
+    });
 
-  const gateway = new ParallAgentGateway({
-    accountId: agentUserId,
-    client,
-    ws,
-    connectionLabel: resolvedWsUrl,
-    config: {
-      parall_url: config.apiUrl,
-      api_key: config.apiKey,
-      org_id: config.orgId,
-    },
-    agentUserId,
-    runtimeType: "codex",
-    runtimeKey,
-    runtimeRef: {
-      hostname: os.hostname(),
-      pid: process.pid,
-      workspace_dir: config.workspaceDir,
-      codex_home: config.codexHome,
-      driver: "app-server",
-    },
-    dispatchAdapter: adapter,
-    log: agentLog,
-    shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
-    contextFilePathForSession: (sessionKey) => contextFilePathForSession(config.stateDir, sessionKey),
-    stepIdFilePathForSession: (sessionKey) => stepIdFilePathForSession(config.stateDir, sessionKey),
-    onConfigUpdate: async () => {
-      const refreshed = await getAgentMeWithLegacyFallback(client, config.orgId);
-      platformManaged = isPlatformManagedProfile(refreshed.agent_profile);
-      const updated = await configMgr.fetch();
-      adapter.updateConfig({
-        model: platformManaged ? (updated.model ?? config.model) : (config.model ?? null),
-        reasoningEffort: platformManaged ? (updated.thinkingEffort ?? config.reasoningEffort) : (config.reasoningEffort ?? null),
-      });
-    },
-    onSessionReady: async () => {
-      const refreshed = await getAgentMeWithLegacyFallback(client, config.orgId);
-      platformManaged = isPlatformManagedProfile(refreshed.agent_profile);
-      const updated = await configMgr.fetch();
-      adapter.updateConfig({
-        model: platformManaged ? (updated.model ?? config.model) : (config.model ?? null),
-        reasoningEffort: platformManaged ? (updated.thinkingEffort ?? config.reasoningEffort) : (config.reasoningEffort ?? null),
-      });
-    },
-    onNewSession: () => { sessionManager.clearMainThread(); },
-    onSessionStale: () => { sessionManager.clearMainThread(); },
-  });
+    const gateway = new ParallAgentGateway({
+      accountId: agentUserId,
+      client,
+      ws,
+      connectionLabel: resolvedWsUrl,
+      config: {
+        parall_url: config.apiUrl,
+        api_key: config.apiKey,
+        org_id: config.orgId,
+      },
+      agentUserId,
+      runtimeType: 'codex',
+      runtimeKey,
+      runtimeRef: {
+        hostname: os.hostname(),
+        pid: process.pid,
+        workspace_dir: config.workspaceDir,
+        codex_home: config.codexHome,
+        driver: 'app-server',
+      },
+      dispatchAdapter: adapter,
+      log: agentLog,
+      shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
+      forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
+      dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),
+      contextFilePathForSession: (sessionKey) =>
+        contextFilePathForSession(config.stateDir, sessionKey),
+      stepIdFilePathForSession: (sessionKey) =>
+        stepIdFilePathForSession(config.stateDir, sessionKey),
+      onConfigUpdate: async () => {
+        const refreshed = await getAgentMeWithLegacyFallback(client, config.orgId);
+        platformManaged = isPlatformManagedProfile(refreshed.agent_profile);
+        platformModelOverride = isPlatformModelOverride(refreshed.agent_profile);
+        const updated = await configMgr.fetch();
+        adapter.updateConfig({
+          model: resolveRuntimeModel(platformModelOverride, updated.model, config.model) ?? null,
+          reasoningEffort: platformManaged
+            ? (updated.thinkingEffort ?? config.reasoningEffort)
+            : (config.reasoningEffort ?? null),
+        });
+      },
+      onSessionReady: async () => {
+        const refreshed = await getAgentMeWithLegacyFallback(client, config.orgId);
+        platformManaged = isPlatformManagedProfile(refreshed.agent_profile);
+        platformModelOverride = isPlatformModelOverride(refreshed.agent_profile);
+        const updated = await configMgr.fetch();
+        adapter.updateConfig({
+          model: resolveRuntimeModel(platformModelOverride, updated.model, config.model) ?? null,
+          reasoningEffort: platformManaged
+            ? (updated.thinkingEffort ?? config.reasoningEffort)
+            : (config.reasoningEffort ?? null),
+        });
+      },
+      onNewSession: () => {
+        sessionManager.clearMainThread();
+      },
+      onSessionStale: () => {
+        sessionManager.clearMainThread();
+      },
+    });
 
-  const abortController = new AbortController();
-  const abort = () => abortController.abort();
-  process.on("SIGINT", abort);
-  process.on("SIGTERM", abort);
+    const abortController = new AbortController();
+    const abort = () => abortController.abort();
+    process.on('SIGINT', abort);
+    process.on('SIGTERM', abort);
 
-  try {
-    agentLog.info(`starting self-hosted Codex runtime (app-server driver) for ${me.display_name} (${agentUserId})`);
-    await gateway.run(abortController.signal);
+    try {
+      agentLog.info(
+        `starting self-hosted Codex runtime (app-server driver) for ${me.display_name} (${agentUserId})`,
+      );
+      await gateway.run(abortController.signal);
+    } finally {
+      await adapter.stop();
+      process.off('SIGINT', abort);
+      process.off('SIGTERM', abort);
+    }
   } finally {
-    await adapter.stop();
-    process.off("SIGINT", abort);
-    process.off("SIGTERM", abort);
+    await telemetry.shutdown();
   }
 }
 

package/src/jsonrpc-client.ts

@@ -1,22 +1,22 @@
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 
 type JsonRpcId = number | string;
 
 export type JsonRpcRequest = {
-  jsonrpc: "2.0";
+  jsonrpc: '2.0';
   id: JsonRpcId;
   method: string;
   params?: unknown;
 };
 
 export type JsonRpcNotification = {
-  jsonrpc: "2.0";
+  jsonrpc: '2.0';
   method: string;
   params?: unknown;
 };
 
 export type JsonRpcResponse = {
-  jsonrpc: "2.0";
+  jsonrpc: '2.0';
   id: JsonRpcId;
   result?: unknown;
   error?: { code: number; message: string; data?: unknown };
@@ -44,7 +44,7 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 export class JsonRpcStdioClient {
   private nextId = 1;
   private readonly pending = new Map<JsonRpcId, Pending>();
-  private buffer = "";
+  private buffer = '';
   private onNotification: NotificationHandler | null = null;
   private disposed = false;
 
@@ -53,11 +53,11 @@ export class JsonRpcStdioClient {
     private readonly requestTimeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     private readonly killProcess?: (proc: ChildProcessWithoutNullStreams) => void,
   ) {
-    proc.stdout.setEncoding("utf8");
-    proc.stdout.on("data", (chunk: string) => this.ingest(chunk));
-    proc.once("close", () => this.dispose(new Error("app-server subprocess closed")));
-    proc.once("error", (err) => this.dispose(err));
-    proc.stdin.on("error", (err) => this.killUnhealthy(err));
+    proc.stdout.setEncoding('utf8');
+    proc.stdout.on('data', (chunk: string) => this.ingest(chunk));
+    proc.once('close', () => this.dispose(new Error('app-server subprocess closed')));
+    proc.once('error', (err) => this.dispose(err));
+    proc.stdin.on('error', (err) => this.killUnhealthy(err));
   }
 
   setNotificationHandler(handler: NotificationHandler) {
@@ -66,16 +66,18 @@ export class JsonRpcStdioClient {
 
   sendRequest(method: string, params?: unknown): Promise<unknown> {
     if (this.disposed) {
-      return Promise.reject(new Error("JSON-RPC client disposed"));
+      return Promise.reject(new Error('JSON-RPC client disposed'));
     }
     const id = this.nextId++;
-    const request: JsonRpcRequest = { jsonrpc: "2.0", id, method, params };
+    const request: JsonRpcRequest = { jsonrpc: '2.0', id, method, params };
     const promise = new Promise<unknown>((resolve, reject) => {
       const timer = setTimeout(() => {
         const pending = this.pending.get(id);
         if (!pending) return;
         this.pending.delete(id);
-        reject(new Error(`JSON-RPC request "${method}" timed out after ${this.requestTimeoutMs}ms`));
+        reject(
+          new Error(`JSON-RPC request "${method}" timed out after ${this.requestTimeoutMs}ms`),
+        );
         this.killUnhealthy(new Error(`request "${method}" timed out; subprocess assumed hung`));
       }, this.requestTimeoutMs);
       this.pending.set(id, { resolve, reject, timer });
@@ -86,7 +88,7 @@ export class JsonRpcStdioClient {
 
   sendNotification(method: string, params?: unknown) {
     if (this.disposed) return;
-    const notification: JsonRpcNotification = { jsonrpc: "2.0", method, params };
+    const notification: JsonRpcNotification = { jsonrpc: '2.0', method, params };
     this.writeFrame(notification);
   }
 
@@ -118,19 +120,19 @@ export class JsonRpcStdioClient {
       if (this.killProcess) {
         this.killProcess(this.proc);
       } else {
-        this.proc.kill("SIGTERM");
+        this.proc.kill('SIGTERM');
       }
     }
   }
 
   private ingest(chunk: string) {
     this.buffer += chunk;
-    let newlineIndex = this.buffer.indexOf("\n");
+    let newlineIndex = this.buffer.indexOf('\n');
     while (newlineIndex >= 0) {
       const line = this.buffer.slice(0, newlineIndex).trim();
       this.buffer = this.buffer.slice(newlineIndex + 1);
       if (line) this.handleLine(line);
-      newlineIndex = this.buffer.indexOf("\n");
+      newlineIndex = this.buffer.indexOf('\n');
     }
   }
 
@@ -148,7 +150,7 @@ export class JsonRpcStdioClient {
       this.pending.delete(message.id);
       clearTimeout(pending.timer);
       if (message.error) {
-        pending.reject(new Error(message.error.message || "JSON-RPC error"));
+        pending.reject(new Error(message.error.message || 'JSON-RPC error'));
       } else {
         pending.resolve(message.result);
       }
@@ -162,9 +164,9 @@ export class JsonRpcStdioClient {
 }
 
 function isResponse(m: unknown): m is JsonRpcResponse {
-  return !!m && typeof m === "object" && "id" in m && ("result" in m || "error" in m);
+  return !!m && typeof m === 'object' && 'id' in m && ('result' in m || 'error' in m);
 }
 
 function isNotification(m: unknown): m is JsonRpcNotification {
-  return !!m && typeof m === "object" && "method" in m && !("id" in m);
+  return !!m && typeof m === 'object' && 'method' in m && !('id' in m);
 }

package/src/session-manager.ts

@@ -1,6 +1,6 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ForkSessionHandle } from "@parall/agent-core";
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { ForkSessionHandle } from '@parall/agent-core';
 
 type PersistedThread = {
   runtimeKey: string;
@@ -66,13 +66,17 @@ export class CodexSessionManager {
 
   private restore() {
     try {
-      const raw = fs.readFileSync(this.stateFilePath, "utf8");
+      const raw = fs.readFileSync(this.stateFilePath, 'utf8');
       const parsed = JSON.parse(raw) as Partial<PersistedThread>;
-      if (parsed.runtimeKey === this.mainSessionKey && typeof parsed.threadId === "string" && parsed.threadId.trim()) {
+      if (
+        parsed.runtimeKey === this.mainSessionKey &&
+        typeof parsed.threadId === 'string' &&
+        parsed.threadId.trim()
+      ) {
         this.threadIds.set(this.mainSessionKey, parsed.threadId.trim());
       }
     } catch (error) {
-      if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
         this.logger?.warn(
           `codex-agent: could not restore main thread state from ${this.stateFilePath}: ${String(error)}`,
         );