circuschief 0.5.0 → 0.7.0

package/packages/server/src/services/sessionExecution.js

@@ -1,5 +1,6 @@
 import { sessions, messages, attachments, conversations } from '../database.js';
 import { createClaudeCodeSpawner } from './nodeSpawnHelper.js';
+import { createCodexSpawner } from './codexSpawnHelper.js';
 import { resolveProviderFromModel, buildSessionEnv } from './sessionProvider.js';
 import { agentGateway } from '../agents/AgentGateway.js';
 import { LoggingAgentWrapper } from '../agents/LoggingAgentWrapper.js';
@@ -7,6 +8,7 @@ import { VCRAgentAdapter } from '../agents/vcr/VCRAgentAdapter.js';
 import {
   buildSystemPromptConfig,
   getPermissionModeForSession,
+  getSandboxModeForSession,
   buildPromptWithAttachments,
 } from './sessionPrompts.js';
 import {
@@ -20,18 +22,38 @@ import {
 } from './streamEventHandler.js';
 import { shouldRescheduleOnError, _checkProactiveReschedule } from './sessionErrors.js';
 import { schedulerService } from './schedulerService.js';
-import { buildConversationContextForModelSwitch } from './conversationContext.js';
+import { buildConversationContextForModelSwitch, buildConversationContextForContinuation } from './conversationContext.js';
 import { broadcastToSession } from '../websocket.js';
 import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
 
+/**
+ * Build the adapter-specific default config object for
+ * {@link createAgentForSession}. Callers may pass an explicit `config` to
+ * override these defaults.
+ * @param {string} agentType
+ * @returns {Object}
+ */
+function buildAgentConfig(agentType) {
+  if (agentType === 'codex') {
+    return { spawnCodexProcess: createCodexSpawner() };
+  }
+  return {};
+}
+
 /**
  * Create the agent for a session, using gateway + logging + VCR.
  *
- * @param {string} agentType - The agent type (e.g., 'claude-code')
+ * If `config` is empty, the adapter-specific default config is applied
+ * (e.g. codex receives a fresh `spawnCodexProcess` spawner). Explicit
+ * `config` keys win over defaults.
+ *
+ * @param {string} agentType - The agent type (e.g., 'claude-code', 'codex')
+ * @param {Object} [config] - Optional adapter config forwarded to the gateway.
  * @returns {{ execute: (queryParams: any, meta?: any) => AsyncGenerator }}
  */
-export function createAgentForSession(agentType = 'claude-code') {
-  const baseAgent = agentGateway.createAgent(agentType);
+export function createAgentForSession(agentType = 'claude-code', config = {}) {
+  const mergedConfig = { ...buildAgentConfig(agentType), ...config };
+  const baseAgent = agentGateway.createAgent(agentType, mergedConfig);
 
   // Wrap with VCR adapter if in VCR mode
   const agent = process.env.VCR_MODE
@@ -43,22 +65,13 @@ export function createAgentForSession(agentType = 'claude-code') {
 }
 
 /**
- * Build query parameters for executing a session via the Claude agent.
- * Shared by runSession, continueSession, and continueSessionWithExistingMessage.
- * @param {Object} options
- * @param {string} options.prompt - The prompt text to send
- * @param {string} options.workingDirectory - Session working directory
- * @param {AbortController} options.controller - Abort controller for the session
- * @param {Object} options.session - Session object from DB
- * @param {string} options.sessionId - Session ID
- * @param {string|null} options.systemPrompt - Custom system prompt from project settings
- * @param {string|null} options.model - Model to use
- * @param {Object} options.sessionEnv - Environment variables for the session
- * @param {string|null} [options.resumeSessionId] - Claude session ID to resume (null for new session)
- * @returns {Object} Query parameters for agent.execute()
+ * Build query parameters for the Claude Code adapter.
+ * @returns {Object}
  */
-export function buildQueryParams({ prompt, workingDirectory, controller, session, sessionId, systemPrompt, model, sessionEnv, resumeSessionId = null }) {
-  // Determine model (force Haiku in VCR mode to minimize cost)
+function buildClaudeCodeQueryParams({
+  prompt, workingDirectory, controller, session, sessionId, systemPrompt,
+  model, sessionEnv, resumeSessionId = null,
+}) {
   const isVCR = Boolean(process.env.VCR_MODE);
   const effectiveModel = isVCR ? 'claude-haiku-4-5-20251001' : model;
 
@@ -69,7 +82,9 @@ export function buildQueryParams({ prompt, workingDirectory, controller, session
       abortController: controller,
       includePartialMessages: true,
       permissionMode: getPermissionModeForSession(session.mode),
-      settingSources: ['project'],
+      // Match normal Claude Code CLI behavior: load user-level settings
+      // such as configured MCP servers, then project/local overrides.
+      settingSources: ['user', 'project', 'local'],
       ...(resumeSessionId && { resume: resumeSessionId }),
       env: sessionEnv,
       spawnClaudeCodeProcess: createClaudeCodeSpawner(),
@@ -79,6 +94,67 @@ export function buildQueryParams({ prompt, workingDirectory, controller, session
   };
 }
 
+/**
+ * Build query parameters for the Codex adapter.
+ *
+ * Codex in v1 is a simple Chat-Completions-shaped executor — it doesn't need
+ * or accept Claude-specific options (permissionMode, settingSources,
+ * includePartialMessages, spawnClaudeCodeProcess, resume).
+ *
+ * Codex does have its own sandboxing model, driven from {@code session.mode}
+ * via {@link getSandboxModeForSession}. Codex CLI v0.124.0 also supports
+ * resume via `codex resume` / `codex exec resume`, but Circus Chief v1
+ * intentionally does NOT pass a resume token — wiring is deferred to a
+ * later phase (see canvas plan §Phase 4.5).
+ *
+ * @returns {Object}
+ */
+function buildCodexQueryParams({
+  prompt, workingDirectory, controller, session, sessionId, systemPrompt, model, sessionEnv,
+}) {
+  const isVCR = Boolean(process.env.VCR_MODE);
+  // In VCR mode, force the cheapest commonly-cassetted OpenAI model.
+  const effectiveModel = isVCR ? 'gpt-4o-mini' : model;
+
+  return {
+    prompt,
+    options: {
+      cwd: workingDirectory,
+      abortController: controller,
+      env: sessionEnv,
+      model: effectiveModel,
+      effortLevel: session?.effortLevel ?? null,
+      systemPrompt: buildSystemPromptConfig(sessionId, session.projectId, systemPrompt, session.mode),
+      sandboxMode: getSandboxModeForSession(session?.mode),
+    },
+  };
+}
+
+/**
+ * Build query parameters for executing a session via the configured agent.
+ * Shared by runSession, continueSession, and continueSessionWithExistingMessage.
+ *
+ * @param {Object} options
+ * @param {string} options.prompt - The prompt text to send
+ * @param {string} options.workingDirectory - Session working directory
+ * @param {AbortController} options.controller - Abort controller for the session
+ * @param {Object} options.session - Session object from DB
+ * @param {string} options.sessionId - Session ID
+ * @param {string|null} options.systemPrompt - Custom system prompt from project settings
+ * @param {string|null} options.model - Model to use
+ * @param {Object} options.sessionEnv - Environment variables for the session
+ * @param {string|null} [options.resumeSessionId] - Session ID to resume (null for new session)
+ * @param {string} [options.agentType] - 'claude-code' (default) | 'codex'
+ * @returns {Object} Query parameters for agent.execute()
+ */
+export function buildQueryParams(options) {
+  const { agentType = 'claude-code' } = options || {};
+  if (agentType === 'codex') {
+    return buildCodexQueryParams(options);
+  }
+  return buildClaudeCodeQueryParams(options);
+}
+
 /**
  * Execute the agent stream loop and handle post-turn completion, errors, and cleanup.
  * This is the shared core of runSession, continueSession, and continueSessionWithExistingMessage.
@@ -146,17 +222,26 @@ export async function _executeSession({
 }
 
 /**
- * Build prompt with conversation context when switching models.
+ * Build prompt with conversation context for a continuation.
  * When the model changes, we can't resume the previous session, so we include
  * conversation history as context so the new model can continue naturally.
- * @param {boolean} modelChanged
- * @param {string} conversationId
- * @param {string} promptWithAttachments
+ * When the adapter cannot resume, we include conversation history so the
+ * model has context of previous turns.
+ * @param {Object} opts
+ * @param {boolean} opts.modelChanged
+ * @param {Object} opts.agent - Agent instance
+ * @param {string} opts.conversationId
+ * @param {string} opts.prompt
  * @returns {Promise<string>}
  */
-async function buildPromptForContinue(modelChanged, conversationId, promptWithAttachments) {
-  if (!modelChanged) return promptWithAttachments;
-  return buildConversationContextForModelSwitch(conversationId) + promptWithAttachments;
+async function buildPromptForContinue({ modelChanged, agent, conversationId, prompt }) {
+  if (modelChanged) {
+    return buildConversationContextForModelSwitch(conversationId) + prompt;
+  }
+  if (agent.needsConversationContext()) {
+    return buildConversationContextForContinuation(conversationId) + prompt;
+  }
+  return prompt;
 }
 
 /**
@@ -201,13 +286,16 @@ function buildContinueModelAndEnv(session, sessionId, model) {
 async function buildContinueParams({
   sessionId, session, model, systemPrompt, effectiveModel, sessionEnv,
   modelChanged, activeConversation, promptWithAttachments,
-  workingDirectory, controller, agentType,
+  workingDirectory, controller, agentType, agent,
 }) {
-  // Only resume if we have a session ID AND model hasn't changed
-  const canResume = activeConversation.claudeSessionId && !modelChanged;
+  // Only resume if we have a session ID AND model hasn't changed AND the
+  // agent supports resume.
+  const canResume = activeConversation.claudeSessionId && !modelChanged && agent.supportsResume();
 
-  // Build prompt with conversation context when model changes
-  const promptWithContext = await buildPromptForContinue(modelChanged, activeConversation.id, promptWithAttachments);
+  // Build prompt with conversation context when model changes or adapter needs it
+  const promptWithContext = await buildPromptForContinue({
+    modelChanged, agent, conversationId: activeConversation.id, prompt: promptWithAttachments,
+  });
 
   const queryParams = buildQueryParams({
     prompt: promptWithContext,
@@ -219,6 +307,7 @@ async function buildContinueParams({
     model: effectiveModel,
     sessionEnv,
     resumeSessionId: canResume ? activeConversation.claudeSessionId : null,
+    agentType,
   });
 
   // Logging metadata for agent call tracking
@@ -246,6 +335,10 @@ async function setupConversationAndMessage(sessionId, content, fileAttachments)
   activeConversationIds.set(sessionId, activeConversation.id);
 
   const message = messages.create(sessionId, 'user', content, { toolUse: null, conversationId: activeConversation.id });
+
+  // Touch the session to update its updated_at timestamp so it sorts to the top
+  sessions.touch(sessionId);
+
   broadcastToSession(sessionId, WS_MESSAGE_TYPES.SESSION_MESSAGE, {
     message,
     conversationId: activeConversation.id,
@@ -307,7 +400,7 @@ export async function continueSessionCore(sessionId, content, workingDirectory,
     sessionId, session, model, systemPrompt,
     effectiveModel: modelEnv.effectiveModel, sessionEnv: modelEnv.sessionEnv,
     modelChanged: modelEnv.modelChanged, activeConversation, promptWithAttachments,
-    workingDirectory, controller, agentType,
+    workingDirectory, controller, agentType, agent,
   });
 
   await _executeSession({
@@ -384,6 +477,7 @@ export async function runSessionCore(sessionId, prompt, workingDirectory, config
     systemPrompt,
     model: effectiveModel,
     sessionEnv,
+    agentType,
   });
 
   // Log query params for debugging third-party provider issues

package/packages/server/src/services/sessionManager.js

@@ -3,7 +3,7 @@ import { broadcastToSession, broadcastToProject } from '../websocket.js';
 import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
 import * as summaryService from './summaryService.js';
 import { checkAndTriggerNextTemplate } from './templateTriggerService.js';
-import { resolveProviderFromModel, buildSessionEnv } from './sessionProvider.js';
+import { resolveProviderFromModel, buildSessionEnv, resolveAgentTypeFromModel } from './sessionProvider.js';
 import {
   shouldRescheduleOnError,
   _checkProactiveReschedule,
@@ -18,7 +18,7 @@ import {
   buildPromptWithAttachments,
   getApiBaseUrl,
 } from './sessionPrompts.js';
-import { buildConversationContextForModelSwitch, buildConversationContextForBranch } from './conversationContext.js';
+import { buildConversationContextForModelSwitch, buildConversationContextForBranch, buildConversationContextForContinuation } from './conversationContext.js';
 import {
   activeSessions,
   activeConversationIds,
@@ -220,6 +220,13 @@ function validateAndFetchContinueContext(sessionId, conversationId) {
 /**
  * Resolve the effective model, provider, and session env from a model override.
  * Detects model changes and updates the session record when needed.
+ *
+ * Defense in depth: when a new model arrives and the session has no assistant
+ * messages yet (i.e. it is still effectively a draft), re-derive agent_type
+ * and persist it together with model. Once the session has produced at least
+ * one assistant message we MUST NOT mutate agent_type — that would corrupt
+ * resume/context state across kinds.
+ *
  * @param {Object} session - Current session object
  * @param {string} sessionId - Session ID
  * @param {string|null} model - Requested model (null to keep current)
@@ -233,13 +240,35 @@ function buildModelAndProvider(session, sessionId, model) {
 
   let updatedSession = session;
   if (model) {
-    sessions.update(sessionId, { model });
+    const update = { model };
+
+    // Defense in depth: if this is still a draft (no assistant messages),
+    // also re-derive agent_type so it stays in sync with the chosen model.
+    // After the first assistant turn this is locked.
+    if (sessionHasNoAssistantMessages(sessionId)) {
+      const derivedAgentType = resolveAgentTypeFromModel(model);
+      if (derivedAgentType && derivedAgentType !== session.agentType) {
+        update.agentType = derivedAgentType;
+      }
+    }
+
+    sessions.update(sessionId, update);
     updatedSession = sessions.getById(sessionId);
   }
 
   return { effectiveModel, sessionEnv, modelChanged, session: updatedSession };
 }
 
+/**
+ * Check whether a session has no assistant messages (i.e. is still a draft).
+ * @param {string} sessionId
+ * @returns {boolean}
+ */
+function sessionHasNoAssistantMessages(sessionId) {
+  const allMessages = messages.getBySessionId(sessionId);
+  return !allMessages.some(m => m.role === 'assistant');
+}
+
 /**
  * Build query params for continueSessionWithExistingMessage.
  * Handles context building (model switch / branch) and resume detection.
@@ -248,18 +277,26 @@ function buildModelAndProvider(session, sessionId, model) {
 function buildExistingMessageQueryParams({
   sessionId, conversationId, session, model, systemPrompt,
   effectiveModel, sessionEnv, modelChanged, conversation,
-  lastUserMessage, workingDirectory, controller, agentType,
+  lastUserMessage, workingDirectory, controller, agentType, agent,
 }) {
   // Determine context needs and build context
   const { needsContext, contextType } = determineContextNeed(conversation, modelChanged);
   if (needsContext) {
     console.log(`[SESSION] ${contextType === 'modelSwitch' ? 'Model changed' : 'Branched conversation'} - including context`);
   }
-  const conversationContext = buildContextForType(conversationId, contextType);
+  let conversationContext = buildContextForType(conversationId, contextType);
+
+  // Fallback: if no specific context was built but the adapter needs
+  // conversation context (i.e. it can't resume), inject continuation history.
+  if (!conversationContext && agent.needsConversationContext()) {
+    conversationContext = buildConversationContextForContinuation(conversationId);
+  }
+
   const promptWithContext = conversationContext + lastUserMessage.content;
 
-  // Only resume if we have a session ID AND model hasn't changed
-  const canResume = conversation.claudeSessionId && !modelChanged;
+  // Only resume if we have a session ID AND model hasn't changed AND the
+  // agent supports resume.
+  const canResume = conversation.claudeSessionId && !modelChanged && agent.supportsResume();
 
   const queryParams = buildQueryParams({
     prompt: promptWithContext,
@@ -319,7 +356,7 @@ export async function continueSessionWithExistingMessage(sessionId, conversation
     sessionId, conversationId, session, model, systemPrompt,
     effectiveModel: modelEnv.effectiveModel, sessionEnv: modelEnv.sessionEnv,
     modelChanged: modelEnv.modelChanged, conversation,
-    lastUserMessage, workingDirectory, controller, agentType,
+    lastUserMessage, workingDirectory, controller, agentType, agent,
   });
 
   await _executeSession({

package/packages/server/src/services/sessionPrompts.js

@@ -1,5 +1,6 @@
 import { sessions, attachments, projects, kanbanBoards, kanbanLanes } from '../database.js';
 import { DEFAULT_SERVER_PORT, DEFAULT_SYSTEM_PROMPT } from '../../../shared/src/index.js';
+import { buildCommandButtonApiInstructions } from './commandButtonPrompts.js';
 
 /**
  * Get the base API URL for canvas and session operations.
@@ -108,6 +109,31 @@ export function getPermissionModeForSession(mode) {
   }
 }
 
+/**
+ * Map session mode to the Codex CLI --sandbox flag value.
+ *
+ *   plan     → read-only           (parity with Claude plan mode's read-mostly posture)
+ *   standard → workspace-write     (default; Codex can edit files in cwd)
+ *   yolo     → danger-full-access  (parallels Claude's bypassPermissions)
+ *
+ * Note: `--full-auto` is intentionally NOT used — it is a shorthand that also
+ * overrides approval policies, which would conflate two orthogonal concerns.
+ *
+ * @param {string} mode - Session mode ('plan', 'standard', 'yolo')
+ * @returns {string} Codex sandbox mode
+ */
+export function getSandboxModeForSession(mode) {
+  switch (mode) {
+    case 'plan':
+      return 'read-only';
+    case 'yolo':
+      return 'danger-full-access';
+    case 'standard':
+    default:
+      return 'workspace-write';
+  }
+}
+
 /** Plan mode system prompt instructions */
 export const PLAN_MODE_PROMPT = `## Plan Mode Active
 
@@ -397,10 +423,12 @@ This session is part of a multi-session workflow:
  * @returns {string} System prompt string
  */
 export function buildSystemPromptConfig(sessionId, projectId, customSystemPrompt, mode) {
+  const apiUrl = getApiBaseUrl();
   const session = sessions.getById(sessionId);
   const canvasWriteInstructions = buildCanvasWriteSystemPrompt(session);  // Pass session object
   const canvasReadInstructions = buildCanvasReadSystemPrompt(session);    // Pass session object
   const sessionApiInstructions = buildSessionApiInstructions(sessionId, projectId);
+  const commandButtonApiInstructions = buildCommandButtonApiInstructions(apiUrl, sessionId, projectId);
   const kanbanApiInstructions = buildKanbanApiInstructions(sessionId, projectId);
   const attachmentsContext = getSessionAttachmentsContext(sessionId);
   const worktreeContext = buildWorktreeContext(session);
@@ -420,6 +448,7 @@ export function buildSystemPromptConfig(sessionId, projectId, customSystemPrompt
     canvasWriteInstructions,
     canvasReadInstructions,
     sessionApiInstructions,
+    commandButtonApiInstructions,
     kanbanApiInstructions
   ].filter(Boolean);
 

package/packages/server/src/services/sessionProvider.js

@@ -12,7 +12,34 @@ export function resolveProviderFromModel(modelId) {
 }
 
 /**
- * Build environment variables from provider configuration
+ * Resolve the agent type (claude-code vs codex) for a given model ID.
+ * Uses the owning provider's kind:
+ *   - anthropic → claude-code
+ *   - openai    → codex
+ * Falls back to 'claude-code' for null / unknown / tier-name inputs.
+ * @param {string|null} modelId
+ * @returns {string} 'claude-code' | 'codex'
+ */
+export function resolveAgentTypeFromModel(modelId) {
+  if (!modelId) return 'claude-code';
+  const provider = modelProviders.getProviderByModelId(modelId);
+  if (!provider) return 'claude-code';
+  if (typeof modelProviders.getAgentTypeForProvider === 'function') {
+    const agentType = modelProviders.getAgentTypeForProvider(provider.id);
+    return agentType || 'claude-code';
+  }
+  // Fallback for test doubles that don't implement getAgentTypeForProvider:
+  // derive from kind directly.
+  if (provider.kind === 'openai') return 'codex';
+  return 'claude-code';
+}
+
+/**
+ * Build environment variables from provider configuration.
+ * Branches on provider.kind so Anthropic-kind and OpenAI-kind providers
+ * emit only their own wire-protocol env vars (no cross-kind leaks).
+ * Providers without a `kind` field default to Anthropic behavior for
+ * backward compatibility.
  * @param {Object|null} provider - Provider object
  * @returns {Object} Environment variables to add to session env
  */
@@ -22,41 +49,68 @@ export function buildProviderEnv(provider) {
     return {}; // Use SDK defaults
   }
 
-  const env = {};
+  const kind = provider.kind || 'anthropic';
+  const env = kind === 'openai'
+    ? buildOpenAIProviderEnv(provider)
+    : buildAnthropicProviderEnv(provider);
 
-  if (provider.baseUrl) {
-    env.ANTHROPIC_BASE_URL = provider.baseUrl;
+  if (provider.apiTimeoutMs) {
+    env.API_TIMEOUT_MS = String(provider.apiTimeoutMs);
   }
-  if (provider.authToken) {
-    // Set BOTH ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN
-    // The SDK prioritizes ANTHROPIC_API_KEY, so we must set it to override
-    // any user's existing ANTHROPIC_API_KEY in their environment
-    env.ANTHROPIC_API_KEY = provider.authToken;
-    env.ANTHROPIC_AUTH_TOKEN = provider.authToken;
+
+  // Parse additional env vars (applied last so users can override anything above)
+  if (provider.additionalEnvVars) {
+    Object.assign(env, provider.additionalEnvVars);
   }
 
-  // Derive default model env vars from provider_models by tier (single source of truth)
-  if (Array.isArray(provider.models)) {
-    const opusModel = provider.models.find((m) => m.tier === 'opus');
-    if (opusModel) env.ANTHROPIC_DEFAULT_OPUS_MODEL = opusModel.modelId;
+  logProviderEnv(provider, kind, env);
+
+  return env;
+}
 
-    const sonnetModel = provider.models.find((m) => m.tier === 'sonnet');
-    if (sonnetModel) env.ANTHROPIC_DEFAULT_SONNET_MODEL = sonnetModel.modelId;
+function buildOpenAIProviderEnv(provider) {
+  const env = {};
+  if (provider.baseUrl) env.OPENAI_BASE_URL = provider.baseUrl;
+  if (provider.authToken) env.OPENAI_API_KEY = provider.authToken;
+  return env;
+}
 
-    const haikuModel = provider.models.find((m) => m.tier === 'haiku');
-    if (haikuModel) env.ANTHROPIC_DEFAULT_HAIKU_MODEL = haikuModel.modelId;
+function buildAnthropicProviderEnv(provider) {
+  const env = {};
+  if (provider.baseUrl) env.ANTHROPIC_BASE_URL = provider.baseUrl;
+  if (provider.authToken) {
+    env.ANTHROPIC_API_KEY = provider.authToken;
+    env.ANTHROPIC_AUTH_TOKEN = provider.authToken;
   }
+  addAnthropicModelEnv(env, provider.models);
+  return env;
+}
 
-  if (provider.apiTimeoutMs) {
-    env.API_TIMEOUT_MS = String(provider.apiTimeoutMs);
+function addAnthropicModelEnv(env, models) {
+  if (!Array.isArray(models)) return;
+  const target = env;
+  const tiers = {
+    opus: 'ANTHROPIC_DEFAULT_OPUS_MODEL',
+    sonnet: 'ANTHROPIC_DEFAULT_SONNET_MODEL',
+    haiku: 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  };
+  for (const [tier, envKey] of Object.entries(tiers)) {
+    const model = models.find((entry) => entry.tier === tier);
+    if (model) target[envKey] = model.modelId;
   }
+}
 
-  // Parse additional env vars
-  if (provider.additionalEnvVars) {
-    Object.assign(env, provider.additionalEnvVars);
+function logProviderEnv(provider, kind, env) {
+  if (kind === 'openai') {
+    console.log(`[SessionManager] buildProviderEnv: Provider "${provider.name}" (openai) env vars:`, {
+      OPENAI_BASE_URL: env.OPENAI_BASE_URL,
+      OPENAI_API_KEY: env.OPENAI_API_KEY ? '[SET]' : '[NOT SET]',
+      API_TIMEOUT_MS: env.API_TIMEOUT_MS,
+    });
+    return;
   }
 
-  console.log(`[SessionManager] buildProviderEnv: Provider "${provider.name}" env vars:`, {
+  console.log(`[SessionManager] buildProviderEnv: Provider "${provider.name}" (anthropic) env vars:`, {
     ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL,
     ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY ? '[SET]' : '[NOT SET]',
     ANTHROPIC_AUTH_TOKEN: env.ANTHROPIC_AUTH_TOKEN ? '[SET]' : '[NOT SET]',
@@ -64,15 +118,24 @@ export function buildProviderEnv(provider) {
     ANTHROPIC_DEFAULT_OPUS_MODEL: env.ANTHROPIC_DEFAULT_OPUS_MODEL,
     ANTHROPIC_DEFAULT_HAIKU_MODEL: env.ANTHROPIC_DEFAULT_HAIKU_MODEL,
   });
-
-  return env;
 }
 
 /**
- * Build environment variables for Claude SDK based on provider and session settings.
+ * Build environment variables for the agent runtime based on provider and session settings.
  * Always returns a robust env with Node in PATH to prevent ENOENT errors.
- * @param {Object|null} provider - Provider object or null for Anthropic defaults
+ *
+ * Kind-aware behavior:
+ *   - provider.kind === 'anthropic' (or legacy/unspecified): keeps today's behavior
+ *     (MAX_THINKING_TOKENS + CLAUDE_CODE_EFFORT_LEVEL are applied as before).
+ *   - provider.kind === 'openai': Claude-only envs (MAX_THINKING_TOKENS,
+ *     CLAUDE_CODE_EFFORT_LEVEL) are NOT set, and any ANTHROPIC_* vars from
+ *     process.env are stripped so Claude env doesn't leak into Codex sessions.
+ *   - provider === null: strip BOTH kinds' auth/base-url vars so host env
+ *     doesn't bleed into the SDK defaults.
+ *
+ * @param {Object|null} provider - Provider object or null for agent defaults
  * @param {boolean} thinkingEnabled - Whether thinking mode is enabled
+ * @param {string|null} effortLevel - Optional effort level
  * @returns {Object}
  */
 export function buildSessionEnv(provider, thinkingEnabled = false, effortLevel = null) {
@@ -82,26 +145,82 @@ export function buildSessionEnv(provider, thinkingEnabled = false, effortLevel =
   // Combine all env vars
   const sessionEnv = {
     ...baseEnv,
-    ...providerEnv, // Add provider env vars
+    ...providerEnv, // Add provider env vars (wins over host env for its own keys)
   };
 
-  // When no custom provider is configured, explicitly exclude ANTHROPIC_* variables
-  // from the environment to ensure SDK uses its defaults (not user's env vars)
+  const kind = provider?.kind || (provider ? 'anthropic' : null);
+
   if (!provider) {
-    delete sessionEnv.ANTHROPIC_API_KEY;
-    delete sessionEnv.ANTHROPIC_AUTH_TOKEN;
-    delete sessionEnv.ANTHROPIC_BASE_URL;
+    stripProviderRuntimeEnv(sessionEnv);
+  } else if (kind === 'openai') {
+    applyOpenAISessionEnv(sessionEnv, providerEnv);
+  } else {
+    stripOpenAIHostEnv(sessionEnv);
   }
 
-  // Add thinking tokens if enabled (but suppress in VCR mode to minimize cost)
-  if (thinkingEnabled && !process.env.VCR_MODE) {
-    sessionEnv.MAX_THINKING_TOKENS = '10240';
-  }
+  // Claude-only session env vars. Only set for Anthropic-kind providers
+  // (or when no provider is configured → Claude-default flow).
+  const isClaudeFlow = !provider || kind === 'anthropic';
+
+  if (isClaudeFlow) {
+    // Add thinking tokens if enabled (but suppress in VCR mode to minimize cost)
+    if (thinkingEnabled && !process.env.VCR_MODE) {
+      sessionEnv.MAX_THINKING_TOKENS = '10240';
+    }
 
-  // Set effort level if provided
-  if (effortLevel) {
-    sessionEnv.CLAUDE_CODE_EFFORT_LEVEL = effortLevel;
+    // Set effort level if provided
+    if (effortLevel) {
+      sessionEnv.CLAUDE_CODE_EFFORT_LEVEL = effortLevel;
+    }
   }
 
   return sessionEnv;
 }
+
+function stripProviderRuntimeEnv(env) {
+  const target = env;
+  delete target.ANTHROPIC_API_KEY;
+  delete target.ANTHROPIC_AUTH_TOKEN;
+  delete target.ANTHROPIC_BASE_URL;
+  delete target.OPENAI_API_KEY;
+  delete target.OPENAI_BASE_URL;
+}
+
+function applyOpenAISessionEnv(sessionEnv, providerEnv) {
+  stripAnthropicHostEnv(sessionEnv);
+  if (!providerEnv.OPENAI_API_KEY) {
+    replaceWithCodexCliEnv(sessionEnv, providerEnv);
+    return;
+  }
+  stripOpenAIBaseUrlUnlessProvided(sessionEnv, providerEnv);
+}
+
+function stripAnthropicHostEnv(env) {
+  const target = env;
+  delete target.ANTHROPIC_API_KEY;
+  delete target.ANTHROPIC_AUTH_TOKEN;
+  delete target.ANTHROPIC_BASE_URL;
+}
+
+function replaceWithCodexCliEnv(sessionEnv, providerEnv) {
+  const target = sessionEnv;
+  delete target.OPENAI_API_KEY;
+  delete target.OPENAI_BASE_URL;
+  delete target.OPENAI_API_BASE;
+  delete target.OPENAI_ORG_ID;
+  delete target.OPENAI_PROJECT;
+  Object.assign(target, providerEnv);
+}
+
+function stripOpenAIBaseUrlUnlessProvided(sessionEnv, providerEnv) {
+  if (providerEnv.OPENAI_BASE_URL || providerEnv.OPENAI_API_BASE) return;
+  const target = sessionEnv;
+  delete target.OPENAI_BASE_URL;
+  delete target.OPENAI_API_BASE;
+}
+
+function stripOpenAIHostEnv(env) {
+  const target = env;
+  delete target.OPENAI_API_KEY;
+  delete target.OPENAI_BASE_URL;
+}