circuschief 0.6.0 → 0.7.0

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

@@ -0,0 +1,48 @@
+import { commandButtons } from '../database.js';
+
+/**
+ * Build Command Button API instructions for system prompt if the project has command buttons.
+ * @param {string} apiUrl - Base API URL
+ * @param {string} sessionId - Current session ID
+ * @param {string} projectId - Current project ID
+ * @returns {string} Command button instructions or empty string if no buttons configured
+ */
+export function buildCommandButtonApiInstructions(apiUrl, sessionId, projectId) {
+  const buttons = commandButtons.getByProjectId(projectId);
+  if (!buttons || buttons.length === 0) {
+    return '';
+  }
+
+  return `## Command Buttons API
+
+This project has command buttons configured - reusable shell commands you can execute. Use the Bash tool to run these curl commands.
+
+### List Available Buttons
+\`\`\`bash
+curl ${apiUrl}/api/projects/${projectId}/command-buttons
+\`\`\`
+
+### Run a Button
+\`\`\`bash
+curl -X POST ${apiUrl}/api/sessions/${sessionId}/command-buttons/<button_id>/run
+\`\`\`
+
+Response: { runId, buttonId, status: "running", output: "" }
+
+### Check Run Status & Output
+\`\`\`bash
+curl ${apiUrl}/api/sessions/${sessionId}/command-buttons/runs/<run_id>
+\`\`\`
+
+Response: { runId, buttonId, status, exitCode, output, startedAt, completedAt }
+
+### List All Runs for This Session
+\`\`\`bash
+curl ${apiUrl}/api/sessions/${sessionId}/command-buttons/runs
+\`\`\`
+
+### Kill a Running Command
+\`\`\`bash
+curl -X POST ${apiUrl}/api/sessions/${sessionId}/command-buttons/runs/<run_id>/kill
+\`\`\``;
+}

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

@@ -112,6 +112,7 @@ function getOrCreateInitialMessage(session, options) {
  * @param {object} options
  * @param {string} [options.prompt] - Optional new prompt to use/override
  * @param {string} [options.model] - Optional model override
+ * @param {string|null} [options.providerId] - Optional provider override
  * @returns {Promise<object>} The updated session
  */
 export async function startDraft(session, options = {}) {
@@ -144,6 +145,7 @@ export async function startDraft(session, options = {}) {
     status: 'starting',
     pendingModel: null,
     ...(model ? { model, agentType } : {}),
+    ...(options.providerId !== undefined ? { providerId: options.providerId } : {}),
   });
 
   // Resolve skill/command invocations so skill body goes into system prompt

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

@@ -82,7 +82,9 @@ function buildClaudeCodeQueryParams({
       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(),

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.
@@ -422,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);
@@ -445,6 +448,7 @@ export function buildSystemPromptConfig(sessionId, projectId, customSystemPrompt
     canvasWriteInstructions,
     canvasReadInstructions,
     sessionApiInstructions,
+    commandButtonApiInstructions,
     kanbanApiInstructions
   ].filter(Boolean);
 

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

@@ -204,14 +204,12 @@ function stripAnthropicHostEnv(env) {
 
 function replaceWithCodexCliEnv(sessionEnv, providerEnv) {
   const target = sessionEnv;
-  const allowed = ['HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TMPDIR'];
-  const cleaned = {};
-  for (const key of allowed) {
-    if (target[key] !== undefined) cleaned[key] = target[key];
-  }
-  Object.assign(cleaned, providerEnv);
-  for (const key of Object.keys(target)) delete target[key];
-  Object.assign(target, cleaned);
+  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) {

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

@@ -3,71 +3,102 @@ import { broadcastToSession } from '../websocket.js';
 import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
 import * as summaryService from './summaryService.js';
 import * as kanbanService from './kanbanService.js';
+import { createVisibleFinalErrorMessage } from './visibleFinalErrorMessage.js';
 import {
   lastMessageIds,
   activeSessions,
   activeConversationIds,
+  finalErrorSessionIds,
   associateAndBroadcastWorkLogs,
   broadcastSessionStatus,
   broadcastChangesUpdate,
 } from './streamEventHandler.js';
 
 /**
- * Handle post-turn completion logic (after stream loop ends successfully)
- * Encapsulates the duplicated completion block from runSession/continueSession/continueSessionWithExistingMessage
+ * Associate work logs with the last message and clean up tracking state.
  * @param {string} sessionId
- * @param {string} workingDirectory
- * @param {{ handleTemplateTriggerIfNeeded?: Function, checkProactiveReschedule?: Function, handleAutoSendIfNeeded?: Function }} callbacks
  */
-export async function handleTurnCompletion(sessionId, workingDirectory, callbacks = {}) {
-  const { handleTemplateTriggerIfNeeded, checkProactiveReschedule: _checkProactiveReschedule, handleAutoSendIfNeeded } = callbacks;
-  // Associate work logs with the last message now that the turn is complete
+function associateAndCleanupWorkLogs(sessionId) {
   const lastMessageId = lastMessageIds.get(sessionId);
   if (lastMessageId) {
     associateAndBroadcastWorkLogs(sessionId, lastMessageId);
     lastMessageIds.delete(sessionId);
   }
+}
 
-  // Session ready for follow-up - set to waiting instead of completed
-  const activeSession = activeSessions.get(sessionId);
-  if (activeSession && !activeSession.controller?.signal?.aborted) {
-    sessions.update(sessionId, { status: 'waiting' });
-    broadcastSessionStatus(sessionId, 'waiting');
-
-    // Check if session should be proactively rescheduled based on token threshold
-    if (_checkProactiveReschedule) {
-      const wasRescheduled = await _checkProactiveReschedule(sessionId);
-      if (wasRescheduled) {
-        return true; // Session was rescheduled, don't continue with normal completion
-      }
+/**
+ * Handle post-turn activities for a session that's ready for follow-up.
+ * @param {string} sessionId
+ * @param {string} workingDirectory
+ * @param {{ checkProactiveReschedule?: Function, handleAutoSendIfNeeded?: Function, handleTemplateTriggerIfNeeded?: Function }} callbacks
+ * @returns {Promise<boolean>} True if rescheduled, false otherwise
+ */
+async function handleActiveSessionCompletion(sessionId, workingDirectory, callbacks) {
+  sessions.update(sessionId, { status: 'waiting', error: null });
+  broadcastSessionStatus(sessionId, 'waiting');
+
+  // Check if session should be proactively rescheduled based on token threshold
+  const { checkProactiveReschedule } = callbacks;
+  if (checkProactiveReschedule) {
+    const wasRescheduled = await checkProactiveReschedule(sessionId);
+    if (wasRescheduled) {
+      return true; // Session was rescheduled, don't continue with normal completion
     }
+  }
 
-    // Extract PR URL immediately (lightweight, no API call)
-    summaryService.extractPrUrlIfNeeded(sessionId);
-    // Trigger debounced summary generation on turn completion (not complete yet)
-    summaryService.onSessionActivity(sessionId);
+  // Extract PR URL immediately (lightweight, no API call)
+  summaryService.extractPrUrlIfNeeded(sessionId);
+  // Trigger debounced summary generation on turn completion (not complete yet)
+  summaryService.onSessionActivity(sessionId);
 
-    // Broadcast changes update when turn completes (real-time indicator)
-    const currentSession = sessions.getById(sessionId);
-    if (currentSession) {
-      await broadcastChangesUpdate(sessionId, currentSession.projectId, workingDirectory);
-    }
+  // Broadcast changes update when turn completes (real-time indicator)
+  const currentSession = sessions.getById(sessionId);
+  if (currentSession) {
+    await broadcastChangesUpdate(sessionId, currentSession.projectId, workingDirectory);
+  }
 
-    // Handle kanban lane movements based on targetLaneId
-    await kanbanService.handleTurnCompletion(sessionId);
+  // Handle kanban lane movements based on targetLaneId
+  await kanbanService.handleTurnCompletion(sessionId);
 
-    // Auto-send queued prompt if enabled (runs BEFORE template trigger)
-    let autoSendFired = false;
-    if (handleAutoSendIfNeeded) {
-      autoSendFired = await handleAutoSendIfNeeded(sessionId);
-    }
+  // Auto-send queued prompt if enabled (runs BEFORE template trigger)
+  const { handleAutoSendIfNeeded, handleTemplateTriggerIfNeeded } = callbacks;
+  let autoSendFired = false;
+  if (handleAutoSendIfNeeded) {
+    autoSendFired = await handleAutoSendIfNeeded(sessionId);
+  }
 
-    // Only trigger next template if auto-send did NOT fire
-    // (if auto-send fired, template will trigger after that turn completes)
-    if (!autoSendFired && handleTemplateTriggerIfNeeded) {
-      await handleTemplateTriggerIfNeeded(sessionId);
-    }
+  // Only trigger next template if auto-send did NOT fire
+  // (if auto-send fired, template will trigger after that turn completes)
+  if (!autoSendFired && handleTemplateTriggerIfNeeded) {
+    await handleTemplateTriggerIfNeeded(sessionId);
   }
+
+  return false;
+}
+
+/**
+ * Handle post-turn completion logic (after stream loop ends successfully)
+ * Encapsulates the duplicated completion block from runSession/continueSession/continueSessionWithExistingMessage
+ * @param {string} sessionId
+ * @param {string} workingDirectory
+ * @param {{ handleTemplateTriggerIfNeeded?: Function, checkProactiveReschedule?: Function, handleAutoSendIfNeeded?: Function }} callbacks
+ */
+export async function handleTurnCompletion(sessionId, workingDirectory, callbacks = {}) {
+  // Associate work logs with the last message now that the turn is complete
+  associateAndCleanupWorkLogs(sessionId);
+
+  // Sessions with final errors should not transition to waiting
+  if (finalErrorSessionIds.has(sessionId)) {
+    finalErrorSessionIds.delete(sessionId);
+    return false;
+  }
+
+  // Session ready for follow-up - set to waiting instead of completed
+  const activeSession = activeSessions.get(sessionId);
+  if (activeSession && !activeSession.controller?.signal?.aborted) {
+    return handleActiveSessionCompletion(sessionId, workingDirectory, callbacks);
+  }
+
   return false;
 }
 
@@ -149,6 +180,7 @@ export async function handleSessionError(sessionId, error, options = {}) {
 
   // Normal error handling (no reschedule or reschedule limits reached)
   sessions.update(sessionId, { status: 'error', error: error.message });
+  createVisibleFinalErrorMessage(sessionId, error, activeConversationIds);
   broadcastToSession(sessionId, WS_MESSAGE_TYPES.SESSION_ERROR, { sessionId, error: error.message });
 
   // Optionally broadcast final conversation state (continueSession does this)

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

@@ -10,6 +10,10 @@ import {
   handleTextDelta as _handleTextDelta,
   handleResultUsage,
 } from './streamUsageHandler.js';
+import {
+  createVisibleFinalErrorMessage,
+  normalizeFinalErrorMessage,
+} from './visibleFinalErrorMessage.js';
 
 // ── Shared module-level state ──────────────────────────────────────────────
 
@@ -34,6 +38,9 @@ export const currentModels = new Map();
 /** @type {Map<string, Set<string>>} Track tool_use IDs that have already been logged per session */
 export const loggedToolUseIds = new Map();
 
+/** @type {Set<string>} Track sessions that received a final result.error event */
+export const finalErrorSessionIds = new Set();
+
 // ── Helper functions ───────────────────────────────────────────────────────
 
 /**
@@ -404,8 +411,11 @@ function handleResultEvent(sessionId, event) {
  * @param {Object} event
  */
 function handleResultError(sessionId, event) {
-  sessions.update(sessionId, { status: 'error', error: event.error });
-  broadcastToSession(sessionId, WS_MESSAGE_TYPES.SESSION_ERROR, { sessionId, error: event.error });
+  const errorMessage = normalizeFinalErrorMessage(event.error);
+  finalErrorSessionIds.add(sessionId);
+  sessions.update(sessionId, { status: 'error', error: errorMessage });
+  createVisibleFinalErrorMessage(sessionId, errorMessage, activeConversationIds);
+  broadcastToSession(sessionId, WS_MESSAGE_TYPES.SESSION_ERROR, { sessionId, error: errorMessage });
   // Broadcast error status to project subscribers for session list updates
   broadcastSessionStatus(sessionId, 'error');
   // Extract PR URL before generating summary (PR may have been created before error)
@@ -481,6 +491,7 @@ export function cleanupSessionState(sessionId, includeConversationId = false) {
   thinkingAccumulators.delete(sessionId);
   currentModels.delete(sessionId);
   loggedToolUseIds.delete(sessionId);
+  finalErrorSessionIds.delete(sessionId);
   activeSessions.delete(sessionId);
   if (includeConversationId) {
     activeConversationIds.delete(sessionId);

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

@@ -74,6 +74,7 @@ export function handleTextDelta(sessionId, delta, textAccumulators) {
   const turnData = currentTurnUsage.get(conversationId) || {
     inputTokens: 0,
     outputTokens: 0,
+    thinkingTokens: 0,
     lastMessageOutput: 0,
     cacheReadInputTokens: 0,
     cacheCreationInputTokens: 0,
@@ -83,6 +84,7 @@ export function handleTextDelta(sessionId, delta, textAccumulators) {
   const broadcastUsage = {
     inputTokens: turnData.inputTokens,
     outputTokens: turnData.outputTokens + Math.max(turnData.lastMessageOutput, newEstimate),
+    thinkingTokens: turnData.thinkingTokens,
     cacheReadInputTokens: turnData.cacheReadInputTokens,
     cacheCreationInputTokens: turnData.cacheCreationInputTokens,
   };
@@ -123,6 +125,7 @@ export function extractTurnUsage(sessionId, event) {
   return {
     inputTokens: resolveTokenField(modelUsageEntry, event.usage, { camel: 'inputTokens', snake: 'input_tokens' }),
     outputTokens: resolveTokenField(modelUsageEntry, event.usage, { camel: 'outputTokens', snake: 'output_tokens' }),
+    thinkingTokens: resolveTokenField(modelUsageEntry, event.usage, { camel: 'thinkingTokens', snake: 'thinking_tokens' }),
     cacheReadInputTokens: resolveTokenField(modelUsageEntry, event.usage, { camel: 'cacheReadInputTokens', snake: 'cache_read_input_tokens' }),
     cacheCreationInputTokens: resolveTokenField(modelUsageEntry, event.usage, { camel: 'cacheCreationInputTokens', snake: 'cache_creation_input_tokens' }),
     webSearchRequests: modelUsageEntry?.webSearchRequests || 0,
@@ -142,6 +145,7 @@ export function buildCumulativeSessionUsage(sessionId, turnUsage) {
   return {
     inputTokens: (currentSession.inputTokens || 0) + turnUsage.inputTokens,
     outputTokens: (currentSession.outputTokens || 0) + turnUsage.outputTokens,
+    thinkingTokens: (currentSession.thinkingTokens || 0) + turnUsage.thinkingTokens,
     cacheReadInputTokens: (currentSession.cacheReadInputTokens || 0) + turnUsage.cacheReadInputTokens,
     cacheCreationInputTokens: (currentSession.cacheCreationInputTokens || 0) + turnUsage.cacheCreationInputTokens,
     webSearchRequests: (currentSession.webSearchRequests || 0) + turnUsage.webSearchRequests,
@@ -162,6 +166,7 @@ export function updateConversationUsage(conversationId, currentConversation, tur
   const cumulativeConversationUsage = {
     inputTokens: (currentConversation.inputTokens || 0) + turnUsage.inputTokens,
     outputTokens: (currentConversation.outputTokens || 0) + turnUsage.outputTokens,
+    thinkingTokens: (currentConversation.thinkingTokens || 0) + turnUsage.thinkingTokens,
     cacheReadInputTokens: (currentConversation.cacheReadInputTokens || 0) + turnUsage.cacheReadInputTokens,
     cacheCreationInputTokens: (currentConversation.cacheCreationInputTokens || 0) + turnUsage.cacheCreationInputTokens,
     webSearchRequests: (currentConversation.webSearchRequests || 0) + turnUsage.webSearchRequests,
@@ -197,6 +202,7 @@ export function handleResultUsage(sessionId, event) {
     usage: updatedConversation ? {
       inputTokens: updatedConversation.inputTokens,
       outputTokens: updatedConversation.outputTokens,
+      thinkingTokens: updatedConversation.thinkingTokens,
       cacheReadInputTokens: updatedConversation.cacheReadInputTokens,
       cacheCreationInputTokens: updatedConversation.cacheCreationInputTokens,
       webSearchRequests: updatedConversation.webSearchRequests,

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

@@ -49,11 +49,16 @@ function logResultUsage(callId, event) {
 /**
  * Build the query parameters for the Claude SDK call.
  * @param {string} prompt - The prompt to send
- * @param {{ systemPrompt?: string, jsonSchema?: Object }} options
+ * @param {{ systemPrompt?: string, jsonSchema?: Object, model?: string, env?: Object }} options
  * @returns {Object} queryParams ready for the SDK query function
  */
 function buildClaudeRequest(prompt, options) {
-  const { systemPrompt = null, jsonSchema = null } = options || {};
+  const {
+    systemPrompt = null,
+    jsonSchema = null,
+    model = 'claude-haiku-4-5-20251001',
+    env = null,
+  } = options || {};
   const schema = jsonSchema || SESSION_SUMMARY_SCHEMA;
 
   return {
@@ -62,7 +67,8 @@ function buildClaudeRequest(prompt, options) {
       cwd: process.cwd(),
       permissionMode: 'bypassPermissions',
       maxTurns: 1,
-      model: 'claude-haiku-4-5-20251001',
+      model,
+      ...(env && { env }),
       ...(systemPrompt && { systemPrompt }),
       outputFormat: {
         type: 'json_schema',
@@ -108,6 +114,21 @@ async function handleClaudeResponse(eventStream, callId) {
   return state.responseText;
 }
 
+function buildSummaryCallMetadata({ logMeta, model, providerId, selectionReason, promptLength }) {
+  return {
+    sessionId: logMeta.sessionId,
+    conversationId: logMeta.conversationId || null,
+    agentType: 'summary',
+    model,
+    callType: logMeta.callType,
+    promptLength,
+    metadata: {
+      ...(providerId ? { providerId } : {}),
+      ...(selectionReason ? { selectionReason } : {}),
+    },
+  };
+}
+
 export const SESSION_SUMMARY_SCHEMA = {
   type: 'object',
   properties: {
@@ -130,11 +151,16 @@ export const SESSION_SUMMARY_SCHEMA = {
  * @param {string} prompt - The prompt to send
  * @param {Array} recentMessages - Messages (for mock mode context)
  * @param {string} sessionStatus - Session status (for mock mode context)
- * @param {{ logMeta?: Object, systemPrompt?: string, jsonSchema?: Object }} options - Optional parameters
+ * @param {{ logMeta?: Object, systemPrompt?: string, jsonSchema?: Object, model?: string, env?: Object, providerId?: string|null, selectionReason?: string }} options - Optional parameters
  * @returns {Promise<string>} The text response (JSON string)
  */
 export async function callClaude(prompt, recentMessages, sessionStatus, options = {}) {
-  const { logMeta = null } = options || {};
+  const {
+    logMeta = null,
+    model = 'claude-haiku-4-5-20251001',
+    providerId = null,
+    selectionReason = null,
+  } = options || {};
   // Build stable key for VCR cassette (session prompts are hardcoded strings in E2E tests)
   let keyHint = null;
   if (process.env.VCR_MODE && logMeta?.sessionId) {
@@ -151,14 +177,13 @@ export async function callClaude(prompt, recentMessages, sessionStatus, options
   // Start logging if metadata provided
   let callId = null;
   if (logMeta) {
-    callId = agentCallLogger.startCall({
-      sessionId: logMeta.sessionId,
-      conversationId: logMeta.conversationId || null,
-      agentType: 'summary',
-      model: 'claude-haiku-4-5-20251001',
-      callType: logMeta.callType,
+    callId = agentCallLogger.startCall(buildSummaryCallMetadata({
+      logMeta,
+      model,
+      providerId,
+      selectionReason,
       promptLength: prompt.length,
-    });
+    }));
   }
 
   try {

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

@@ -0,0 +1,154 @@
+import OpenAI from 'openai';
+import { callClaude, SESSION_SUMMARY_SCHEMA } from './summaryClaudeClient.js';
+import { agentCallLogger } from './agentCallLogger.js';
+import { buildProviderEnv } from './sessionProvider.js';
+import { resolveSummaryModel } from './summaryModelResolver.js';
+
+export { SESSION_SUMMARY_SCHEMA };
+
+export async function callSummaryModel(prompt, recentMessages, sessionStatus, options = {}) {
+  const resolution = options.resolvedModel || resolveSummaryModel(options.summarySettings || {});
+  if (resolution.kind === 'openai') {
+    return callOpenAISummaryModel(prompt, resolution, options);
+  }
+  return callAnthropicSummaryModel({ prompt, recentMessages, sessionStatus, resolution, options });
+}
+
+function callAnthropicSummaryModel({ prompt, recentMessages, sessionStatus, resolution, options }) {
+  const providerEnv = resolution.provider && !resolution.provider.isBuiltIn
+    ? { ...process.env, ...buildProviderEnv(resolution.provider) }
+    : null;
+
+  return callClaude(prompt, recentMessages, sessionStatus, {
+    ...options,
+    model: resolution.model,
+    providerId: resolution.providerId,
+    selectionReason: resolution.selectionReason,
+    ...(providerEnv ? { env: providerEnv } : {}),
+  });
+}
+
+async function callOpenAISummaryModel(prompt, resolution, options) {
+  const { logMeta = null, systemPrompt = null, jsonSchema = null } = options || {};
+  const schema = jsonSchema || SESSION_SUMMARY_SCHEMA;
+  const provider = resolution.provider;
+  const client = createOpenAIClient(provider);
+
+  const callId = startOpenAISummaryLog(logMeta, resolution, prompt.length);
+
+  try {
+    const response = await createOpenAIChatCompletion(client, {
+      model: resolution.model,
+      prompt,
+      systemPrompt,
+      schema,
+      structured: true,
+    }).catch(async (error) => {
+      if (!isStructuredOutputUnsupported(error)) throw error;
+      return createOpenAIChatCompletion(client, {
+        model: resolution.model,
+        prompt: withJsonOnlyInstruction(prompt, schema),
+        systemPrompt,
+        schema,
+        structured: false,
+      });
+    });
+
+    logOpenAIUsage(callId, response.usage);
+
+    if (callId) {
+      agentCallLogger.completeCall(callId, { success: true });
+    }
+    return extractOpenAIContent(response);
+  } catch (error) {
+    if (callId) {
+      agentCallLogger.completeCall(callId, { success: false, error });
+    }
+    throw error;
+  }
+}
+
+function startOpenAISummaryLog(logMeta, resolution, promptLength) {
+  if (!logMeta) return null;
+  return agentCallLogger.startCall({
+    sessionId: logMeta.sessionId,
+    conversationId: logMeta.conversationId || null,
+    agentType: 'summary',
+    model: resolution.model,
+    callType: logMeta.callType,
+    promptLength,
+    metadata: {
+      ...(resolution.providerId ? { providerId: resolution.providerId } : {}),
+      ...(resolution.selectionReason ? { selectionReason: resolution.selectionReason } : {}),
+    },
+  });
+}
+
+function logOpenAIUsage(callId, usage) {
+  if (!callId || !usage) return;
+  agentCallLogger.updateUsage(callId, {
+    inputTokens: usage.prompt_tokens || 0,
+    outputTokens: usage.completion_tokens || 0,
+    thinkingTokens: 0,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 0,
+  });
+}
+
+function createOpenAIClient(provider) {
+  const options = {
+    apiKey: provider?.authToken || process.env.OPENAI_API_KEY || 'missing',
+  };
+  if (provider?.baseUrl) options.baseURL = provider.baseUrl;
+  if (provider?.apiTimeoutMs) options.timeout = provider.apiTimeoutMs;
+  return new OpenAI(options);
+}
+
+function createOpenAIChatCompletion(client, { model, prompt, systemPrompt, schema, structured }) {
+  const messages = [];
+  if (systemPrompt) messages.push({ role: 'system', content: systemPrompt });
+  messages.push({ role: 'user', content: prompt });
+
+  const request = {
+    model,
+    messages,
+    temperature: 0,
+  };
+
+  if (structured) {
+    request.response_format = {
+      type: 'json_schema',
+      json_schema: {
+        name: 'session_summary',
+        schema,
+        strict: false,
+      },
+    };
+  } else {
+    request.response_format = { type: 'json_object' };
+  }
+
+  return client.chat.completions.create(request);
+}
+
+function extractOpenAIContent(response) {
+  const content = response?.choices?.[0]?.message?.content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => part?.text || part?.content || '')
+      .join('');
+  }
+  return content || '';
+}
+
+function isStructuredOutputUnsupported(error) {
+  const message = `${error?.message || ''} ${error?.code || ''} ${error?.type || ''}`.toLowerCase();
+  return [400, 404, 422].includes(error?.status)
+    || message.includes('response_format')
+    || message.includes('json_schema')
+    || message.includes('unsupported');
+}
+
+function withJsonOnlyInstruction(prompt, schema) {
+  return `${prompt}\n\nReturn only a valid JSON object matching this JSON Schema:\n${JSON.stringify(schema)}`;
+}