circuschief 0.5.0 → 0.6.0

package/packages/server/src/db/SessionRepository.js

@@ -1,6 +1,6 @@
 import { BaseRepository } from './BaseRepository.js';
 import { databaseManager } from './DatabaseManager.js';
-import { messages, conversations } from './index.js';
+import { messages, conversations, modelProviders } from './index.js';
 import {
   ACTIVITY_FIELDS_SQL,
   mapTokenUsage,
@@ -9,6 +9,26 @@ import {
   buildUpdateClauses,
 } from './session-helpers.js';
 
+const DEFAULT_AGENT_TYPE = 'claude-code';
+
+/**
+ * Resolve the agent type ('claude-code' or 'codex') from a model ID by looking
+ * up which provider owns the model. This is the same logic as
+ * sessionProvider.resolveAgentTypeFromModel but inlined here to avoid a
+ * circular dependency:
+ *   database.js (index) → SessionRepository → sessionProvider → database.js
+ * @param {string|null} modelId
+ * @returns {'claude-code'|'codex'}
+ */
+function resolveAgentTypeFromModel(modelId) {
+  if (!modelId) return DEFAULT_AGENT_TYPE;
+  const provider = modelProviders.getProviderByModelId(modelId);
+  if (!provider) return DEFAULT_AGENT_TYPE;
+  // ProviderRepository.getAgentTypeForProvider maps kind → agent adapter
+  const agentType = modelProviders.getAgentTypeForProvider(provider.id);
+  return agentType || DEFAULT_AGENT_TYPE;
+}
+
 /**
  * Session repository class
  */
@@ -42,6 +62,8 @@ export class SessionRepository extends BaseRepository {
       effortLevel: row.effort_level || null,
       autoSendPendingPrompt: Boolean(row.auto_send_pending_prompt),
       slashCommands: row.slash_commands || null,
+      // Agent runtime driving this session (fallback to 'claude-code' for legacy rows).
+      agentType: row.agent_type || DEFAULT_AGENT_TYPE,
       ...mapTokenUsage(row),
       ...mapScheduling(row),
       // Kanban fields
@@ -49,7 +71,7 @@ export class SessionRepository extends BaseRepository {
       laneTriggerDepth: row.lane_trigger_depth || 0,
       createdAt: row.created_at,
       updatedAt: row.updated_at,
-      lastActivityAt: row.last_activity_at || row.updated_at || row.created_at,
+      lastActivityAt: row.last_activity_at ?? null,
       activeTimeMs: row.active_time_ms || 0,
     };
   }
@@ -62,18 +84,38 @@ export class SessionRepository extends BaseRepository {
     return this.map(row);
   }
 
-  /** Create a new session with optional config (mode, thinkingEnabled, gitBranch, parentSessionId, status, model, effortLevel) */
+  /** Create a new session with optional config (mode, thinkingEnabled, gitBranch, parentSessionId, status, model, effortLevel, agentType) */
   create(projectId, name, prompt, options = {}) {
     const config = parseCreateConfig(options, Array.prototype.slice.call(arguments, 4));
 
+    // Resolve agentType: explicit override → model-based derivation → fallback
+    const agentType =
+      config.agentType
+      ?? (config.model ? resolveAgentTypeFromModel(config.model) : null)
+      ?? DEFAULT_AGENT_TYPE;
+
     const id = databaseManager.generateId();
     const now = Date.now();
     this.db
       .prepare(
-        `INSERT INTO sessions (id, project_id, name, status, mode, thinking_enabled, git_branch, parent_session_id, model, effort_level, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO sessions (id, project_id, name, status, mode, thinking_enabled, git_branch, parent_session_id, model, effort_level, agent_type, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       )
-      .run(id, projectId, name, config.status, config.mode, config.thinkingEnabled ? 1 : 0, config.gitBranch, config.parentSessionId, config.model, config.effortLevel, now, now);
+      .run(
+        id,
+        projectId,
+        name,
+        config.status,
+        config.mode,
+        config.thinkingEnabled ? 1 : 0,
+        config.gitBranch,
+        config.parentSessionId,
+        config.model,
+        config.effortLevel,
+        agentType,
+        now,
+        now
+      );
 
     // Create initial conversation
     const conversation = conversations.create(id, 'Initial', true);
@@ -103,6 +145,7 @@ export class SessionRepository extends BaseRepository {
 
     sql += ` ORDER BY
       starred DESC,
+      COALESCE(last_activity_at, updated_at, created_at) DESC,
       updated_at DESC,
       created_at DESC,
       rowid DESC`;
@@ -141,7 +184,7 @@ export class SessionRepository extends BaseRepository {
         `SELECT s.*, p.name as project_name, p.working_directory as project_working_directory, ${ACTIVITY_FIELDS_SQL}
          FROM sessions s JOIN projects p ON s.project_id = p.id
          WHERE s.status IN ('starting', 'running', 'waiting') AND s.archived = 0
-         ORDER BY s.starred DESC, s.updated_at DESC, s.created_at DESC, s.rowid DESC`
+         ORDER BY s.starred DESC, COALESCE(last_activity_at, s.updated_at, s.created_at) DESC, s.updated_at DESC, s.created_at DESC, s.rowid DESC`
       )
       .all();
     return rows.map(row => ({
@@ -157,7 +200,7 @@ export class SessionRepository extends BaseRepository {
       .prepare(
         `SELECT s.*, ${ACTIVITY_FIELDS_SQL} FROM sessions s
          WHERE parent_session_id = ?
-         ORDER BY updated_at DESC, created_at DESC, rowid DESC`
+         ORDER BY COALESCE(last_activity_at, updated_at, created_at) DESC, updated_at DESC, created_at DESC, rowid DESC`
       )
       .all(parentSessionId);
     return this.mapAll(rows);
@@ -213,6 +256,18 @@ export class SessionRepository extends BaseRepository {
     return this.getById(id);
   }
 
+  /**
+   * Touch a session to update its updated_at timestamp without changing other fields.
+   * This is used to mark a session as recently active (e.g., when a message is added).
+   * @param {string} id - Session ID
+   * @returns {Object|null} The updated session or null if not found
+   */
+  touch(id) {
+    const now = Date.now();
+    this.db.prepare('UPDATE sessions SET updated_at = ? WHERE id = ?').run(now, id);
+    return this.getById(id);
+  }
+
   /** Duplicate a session with a new ID and reset state (does NOT handle git or conversation setup) */
   duplicate(sourceSessionId, { name } = {}) {
     const source = this.getById(sourceSessionId);
@@ -227,10 +282,10 @@ export class SessionRepository extends BaseRepository {
     // Insert new session with same settings but new ID and status
     this.db
       .prepare(
-        `INSERT INTO sessions (id, project_id, name, status, mode, thinking_enabled, git_branch, model, effort_level, context_window,
+        `INSERT INTO sessions (id, project_id, name, status, mode, thinking_enabled, git_branch, model, effort_level, agent_type, context_window,
                                input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens,
                                web_search_requests, cost_usd, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       )
       .run(
         id,
@@ -242,6 +297,7 @@ export class SessionRepository extends BaseRepository {
         source.gitBranch,  // Copy branch name (NOT worktree path)
         source.model,
         source.effortLevel,
+        source.agentType || DEFAULT_AGENT_TYPE,
         source.contextWindow,
         source.inputTokens,
         source.outputTokens,
@@ -261,7 +317,7 @@ export class SessionRepository extends BaseRepository {
     const rows = this.db
       .prepare(
         `SELECT s.*, ${ACTIVITY_FIELDS_SQL} FROM sessions s
-         WHERE pr_url IS NOT NULL ORDER BY updated_at DESC, created_at DESC, rowid DESC`
+         WHERE pr_url IS NOT NULL ORDER BY COALESCE(last_activity_at, updated_at, created_at) DESC, updated_at DESC, created_at DESC, rowid DESC`
       )
       .all();
     return this.mapAll(rows);

package/packages/server/src/db/migrations/index.js

@@ -168,7 +168,9 @@ export const allMigrations = validateMigrations([
 
   // --- Providers + provider_models tables + seed ---
   m.get('providers-create-tables'),
+  m.get('providers-add-kind'),
   m.get('providers-seed-built-in'),
+  m.get('providers-seed-built-in-openai'),
 
   // --- Sessions provider_id (from providers FK) ---
   s.get('sessions-add-provider_id-from-providers'),

package/packages/server/src/db/migrations/miscMigrations.js

@@ -4,12 +4,13 @@
  * Each export is an array of { name, up(db) } migration objects.
  */
 import { randomUUID } from 'node:crypto';
+import { OPENAI_MODELS } from '../../../../shared/src/index.js';
 import { addColumnIfMissing, tableExists } from './migrationUtils.js';
 
 /**
  * Seed the built-in Anthropic provider if it doesn't exist.
  */
-function seedBuiltInProvider(db) {
+function seedBuiltInAnthropicProvider(db) {
   const providerId = 'anthropic-default';
 
   const existing = db
@@ -43,6 +44,35 @@ function seedBuiltInProvider(db) {
   }
 }
 
+/**
+ * Seed the built-in OpenAI/Codex provider if it doesn't exist.
+ */
+function seedBuiltInOpenAIProvider(db) {
+  const providerId = 'openai-default';
+  const now = Date.now();
+
+  db.prepare(
+    `INSERT OR IGNORE INTO providers (
+       id, name, base_url, auth_token, kind, is_built_in, created_at, updated_at
+     )
+     VALUES (?, ?, NULL, NULL, 'openai', 1, ?, ?)`
+  ).run(providerId, 'OpenAI (Official)', now, now);
+
+  const insertModel = db.prepare(
+    `INSERT OR IGNORE INTO provider_models (id, provider_id, model_id, display_name, description, tier, created_at)
+     VALUES (?, ?, ?, ?, ?, 'custom', ?)`
+  );
+
+  for (const model of OPENAI_MODELS) {
+    insertModel.run(model.seedId, providerId, model.id, model.name, model.description, now);
+  }
+}
+
+function seedBuiltInProviders(db) {
+  seedBuiltInAnthropicProvider(db);
+  seedBuiltInOpenAIProvider(db);
+}
+
 /**
  * Update built-in models to 4.6 versions.
  */
@@ -217,6 +247,7 @@ export const miscMigrations = [
           api_timeout_ms INTEGER,
           additional_env_vars TEXT,
           is_built_in INTEGER NOT NULL DEFAULT 0,
+          kind TEXT NOT NULL DEFAULT 'anthropic' CHECK(kind IN ('anthropic','openai')),
           created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
           updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
         );
@@ -235,10 +266,29 @@ export const miscMigrations = [
     },
   },
 
-  // --- Seed built-in provider ---
+  // --- Add `kind` column to providers (for DBs that predate the CREATE TABLE change) ---
+  {
+    name: 'providers-add-kind',
+    up(db) {
+      addColumnIfMissing(
+        db,
+        'providers',
+        'kind',
+        "TEXT NOT NULL DEFAULT 'anthropic' CHECK(kind IN ('anthropic','openai'))"
+      );
+    },
+  },
+
+  // --- Seed built-in providers ---
   {
     name: 'providers-seed-built-in',
-    up(db) { seedBuiltInProvider(db); },
+    up(db) { seedBuiltInProviders(db); },
+  },
+
+  // --- Seed built-in OpenAI provider for DBs that already ran the original seed ---
+  {
+    name: 'providers-seed-built-in-openai',
+    up(db) { seedBuiltInOpenAIProvider(db); },
   },
 
   // --- Update built-in models to 4.6 ---

package/packages/server/src/db/session-helpers.js

@@ -59,6 +59,10 @@ const CONFIG_DEFAULTS = {
   status: 'starting',
   model: null,
   effortLevel: null,
+  // Agent runtime for the session: 'claude-code' (default) or 'codex'.
+  // Defaults to null so SessionRepository.create() can resolve it from the model.
+  // Explicit values from callers are preserved as-is.
+  agentType: null,
 };
 
 function buildConfig(src) {
@@ -109,6 +113,7 @@ export const DIRECT_FIELD_MAP = {
   effortLevel: 'effort_level',
   targetLaneId: 'target_lane_id',
   laneTriggerDepth: 'lane_trigger_depth',
+  agentType: 'agent_type',
 };
 
 /** camelCase -> snake_case column mapping for boolean fields (converted to 1/0) */

package/packages/server/src/schema.sql

@@ -233,6 +233,7 @@ CREATE TABLE IF NOT EXISTS providers (
   api_timeout_ms INTEGER,
   additional_env_vars TEXT,
   is_built_in INTEGER NOT NULL DEFAULT 0,
+  kind TEXT NOT NULL DEFAULT 'anthropic' CHECK(kind IN ('anthropic','openai')),
   created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
   updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
 );

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

@@ -0,0 +1,37 @@
+import { spawn } from 'child_process';
+import { createRobustEnv } from './nodeSpawnHelper.js';
+
+/**
+ * Create a custom spawn function for the Codex CLI.
+ *
+ * Mirrors {@link createClaudeCodeSpawner} but keeps stderr piped (the Codex
+ * adapter surfaces stderr bytes as error events rather than silently ignoring
+ * them).
+ *
+ * As with the Claude helper:
+ *   - The command 'node' is replaced with {@link process.execPath} so child
+ *     processes use the same Node binary that's running the app (important
+ *     for nvm/fnm/volta users).
+ *   - `createRobustEnv` guarantees the Node bin directory is on PATH.
+ *
+ * @returns {Function} Spawn function of shape (options) => childProcess
+ */
+export function createCodexSpawner() {
+  return (options) => {
+    const { command, args, cwd, env, signal } = options;
+
+    // Replace 'node' with the absolute path to the current Node executable
+    const actualCommand = command === 'node' ? process.execPath : command;
+
+    // Ensure PATH includes the directory containing Node
+    const robustEnv = createRobustEnv(env);
+
+    return spawn(actualCommand, args, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      signal,
+      env: robustEnv,
+      windowsHide: true,
+    });
+  };
+}

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

@@ -70,3 +70,30 @@ ${transcript}
 
 `;
 }
+
+/**
+ * Build context for a continuation where the adapter cannot resume.
+ * This is the generic case for any non-resumable adapter (Codex, future adapters).
+ * @param {string} conversationId
+ * @returns {string}
+ */
+export function buildConversationContextForContinuation(conversationId) {
+  const conversationMessages = messages.getByConversationId(conversationId);
+
+  // Don't include the last user message (that's the current prompt)
+  const previousMessages = conversationMessages.slice(0, -1);
+
+  if (previousMessages.length === 0) {
+    return '';
+  }
+
+  const transcript = formatConversationHistory(previousMessages);
+
+  return `<conversation_history>
+The following is the conversation history from this session so far. Continue naturally from where the conversation left off.
+
+${transcript}
+</conversation_history>
+
+`;
+}

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

@@ -2,6 +2,7 @@ import { sessions, messages, projects, conversations, attachments } from '../dat
 import { broadcastToSession, broadcastToProject } from '../websocket.js';
 import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
 import * as slashCommandService from './slashCommandService.js';
+import { resolveAgentTypeFromModel } from './sessionProvider.js';
 
 /**
  * Validates that a session is a draft (waiting status with no assistant messages).
@@ -125,6 +126,11 @@ export async function startDraft(session, options = {}) {
   // Model to use for this session (optional - SDK will use default if not provided)
   const model = options.model || session.pendingModel || session.model || null;
 
+  // Resolve the agent type from the selected model before launching.
+  // Draft sessions have no assistant messages yet, so the session is still
+  // choosing its initial runtime – the selected model determines agentType.
+  const agentType = model ? resolveAgentTypeFromModel(model) : session.agentType;
+
   // Get or create the initial user message
   const initialMessage = getOrCreateInitialMessage(session, options);
   const finalPrompt = initialMessage.content;
@@ -132,8 +138,13 @@ export async function startDraft(session, options = {}) {
   // Get session attachments for context
   const sessionAttachments = attachments.getBySessionId(session.id);
 
-  // Update session status to starting and clear pendingModel (mirrors pendingPrompt cleanup above)
-  sessions.update(session.id, { status: 'starting', pendingModel: null });
+  // Update session status to starting, clear pendingModel, and persist the
+  // resolved model + agentType BEFORE runSession() reads them from storage.
+  sessions.update(session.id, {
+    status: 'starting',
+    pendingModel: null,
+    ...(model ? { model, agentType } : {}),
+  });
 
   // Resolve skill/command invocations so skill body goes into system prompt
   const resolved = await slashCommandService.resolvePromptSkillOrCommand(

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

@@ -9,6 +9,7 @@ import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
 import { renderTemplatePrompt, getRootSession } from './templateTriggerService.js';
 import { setupGitForSession } from './gitSessionSetup.js';
 import { runSession } from './sessionManager.js';
+import { resolveAgentTypeFromModel } from './sessionProvider.js';
 
 // Maximum depth for recursive lane-entry template triggers
 export const MAX_LANE_TRIGGER_DEPTH = 5;
@@ -147,6 +148,7 @@ async function buildChildSessionFromTemplate(template, session, lane, depth) {
     gitBranch: settings.gitBranch,
     status: 'starting',
     model: settings.model,
+    agentType: resolveAgentTypeFromModel(settings.model),
   });
 
   // Configure session
@@ -240,6 +242,7 @@ async function buildChildSessionFromPrompt(lane, session, depth) {
   const newSession = sessions.create(session.projectId, `Lane prompt (lane: ${lane.name})`, renderedPrompt, {
     ...settings,
     status: 'starting',
+    agentType: resolveAgentTypeFromModel(settings.model),
   });
 
   // Configure session

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

@@ -1,35 +1,53 @@
 import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
 
 /**
- * Test a provider configuration by making a minimal API call
- * @param {Object} config - Provider configuration to test
+ * Test a provider configuration by making a minimal API call.
+ * Branches on `kind`:
+ *   - 'anthropic' → send a tiny `messages.create` via `@anthropic-ai/sdk`.
+ *   - 'openai'    → prefer `models.list()` via `openai`; fall back to a
+ *                   `chat.completions.create({ max_tokens: 1 })` if
+ *                   `models.list` is not supported (chat-only endpoints).
+ *
+ * Both branches return the same response shape:
+ *   - Success: { success: true, message, details: { model, usage? } }
+ *   - Failure: { success: false, message, details: { code, type } }
+ * This function never throws. Errors are mapped to the failure shape above.
+ *
+ * @param {Object} config
+ * @param {'anthropic'|'openai'} [config.kind='anthropic'] - Provider kind
  * @param {string} [config.baseUrl] - Base URL for the provider
  * @param {string} [config.authToken] - Auth token for the provider
- * @param {string} [config.defaultSonnetModel] - Default Sonnet model ID
+ * @param {string} [config.defaultSonnetModel] - For anthropic: model to test against
  * @param {number} [config.apiTimeoutMs] - API timeout in milliseconds
  * @returns {Promise<{success: boolean, message: string, details?: Object}>}
  */
 export async function testProviderConnection(config) {
+  const { kind = 'anthropic' } = config || {};
+  if (kind === 'openai') {
+    return testOpenAIConnection(config);
+  }
+  return testAnthropicConnection(config);
+}
+
+/**
+ * Anthropic-kind connection test (unchanged from pre-kind behavior).
+ * @private
+ */
+async function testAnthropicConnection(config) {
   const { baseUrl, authToken, defaultSonnetModel, apiTimeoutMs } = config;
 
   try {
-    // Build client options
     const clientOptions = {};
 
-    if (baseUrl) {
-      clientOptions.baseURL = baseUrl;
-    }
-    if (authToken) {
-      clientOptions.apiKey = authToken;
-    }
-    if (apiTimeoutMs) {
-      clientOptions.timeout = apiTimeoutMs;
-    }
+    if (baseUrl) clientOptions.baseURL = baseUrl;
+    if (authToken) clientOptions.apiKey = authToken;
+    if (apiTimeoutMs) clientOptions.timeout = apiTimeoutMs;
 
     const client = new Anthropic(clientOptions);
 
-    // Use a minimal message to test connectivity
-    // This verifies: network, auth, and model availability
+    // Use a minimal message to test connectivity.
+    // This verifies: network, auth, and model availability.
     const testModel = defaultSonnetModel || 'claude-sonnet-4-20250514';
 
     const response = await client.messages.create({
@@ -58,6 +76,88 @@ export async function testProviderConnection(config) {
   }
 }
 
+/**
+ * OpenAI-kind connection test. Tries `models.list()` first; if the endpoint
+ * does not implement that (common for chat-only proxies like LM Studio), falls
+ * back to a minimal `chat.completions.create({ max_tokens: 1 })`.
+ * @private
+ */
+async function testOpenAIConnection(config) {
+  try {
+    const client = createOpenAIClient(config);
+    return await testOpenAIClient(client, config);
+  } catch (error) {
+    return failureResponse(error);
+  }
+}
+
+function createOpenAIClient(config) {
+  const { baseUrl, authToken, apiTimeoutMs } = config;
+  const clientOptions = { apiKey: authToken || 'missing' };
+  if (baseUrl) clientOptions.baseURL = baseUrl;
+  if (apiTimeoutMs) clientOptions.timeout = apiTimeoutMs;
+  return new OpenAI(clientOptions);
+}
+
+async function testOpenAIClient(client, config) {
+  try {
+    return await testOpenAIModelsEndpoint(client, config);
+  } catch (error) {
+    if (error?.status !== 404) throw error;
+    return testOpenAIChatEndpoint(client, config);
+  }
+}
+
+async function testOpenAIModelsEndpoint(client, config) {
+  const listResult = await client.models.list();
+  const first = pickFirstModel(listResult) || config.defaultSonnetModel || null;
+  return connectionSuccess(first ? { model: first } : {});
+}
+
+async function testOpenAIChatEndpoint(client, config) {
+  const testModel = config.defaultSonnetModel || 'gpt-4o-mini';
+  const response = await client.chat.completions.create({
+    model: testModel,
+    max_tokens: 1,
+    messages: [{ role: 'user', content: 'Hi' }],
+  });
+  return connectionSuccess({
+    model: response?.model || testModel,
+    ...(response?.usage ? { usage: response.usage } : {}),
+  });
+}
+
+function connectionSuccess(details) {
+  return {
+    success: true,
+    message: 'Connection successful',
+    details,
+  };
+}
+
+function failureResponse(error) {
+  return {
+    success: false,
+    message: getErrorMessage(error),
+    details: { code: error.status || error.code, type: error.type || error.name },
+  };
+}
+
+/**
+ * Extract a representative model ID from whatever shape `models.list()` returns.
+ * @private
+ */
+function pickFirstModel(listResult) {
+  if (!listResult) return null;
+  // Newer SDKs expose .data; older ones are plain arrays / async iterables.
+  const data = Array.isArray(listResult) ? listResult : listResult.data;
+  if (Array.isArray(data) && data.length > 0) {
+    const entry = data[0];
+    return entry?.id || entry?.model || null;
+  }
+  return null;
+}
+
 /**
  * Get a human-readable error message from an error object
  * @param {Error} error - The error object

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

@@ -0,0 +1,38 @@
+import { resolveAgentTypeFromModel } from './sessionProvider.js';
+
+// Human-readable labels used in the cross-kind switch error message.
+export const AGENT_TYPE_LABELS = Object.freeze({
+  'claude-code': 'Claude Code',
+  codex: 'Codex',
+});
+
+/**
+ * @param {string} agentType
+ * @returns {string}
+ */
+export function agentLabel(agentType) {
+  return AGENT_TYPE_LABELS[agentType] || agentType || 'unknown';
+}
+
+/**
+ * Cross-kind model switch guard. A session is bound to one agent type for its
+ * lifetime. If the caller selected a model that resolves to a different agent
+ * than the session's existing agentType, reject BEFORE dispatching
+ * continueSession or updating session.model — mixing Claude and Codex
+ * mid-conversation would produce a broken resume/context state. Same-kind
+ * model changes (sonnet↔opus, gpt-4o↔o1-mini) pass through.
+ *
+ * @param {Object} session - The session row (must include agentType + model).
+ * @param {string|null} requestedModel - Model ID from req.body.model, or null.
+ * @returns {{ error: string, message: string }|null} 400-body on block, or null to allow.
+ */
+export function checkCrossKindSwitch(session, requestedModel) {
+  const sessionAgentType = session.agentType || 'claude-code';
+  const effectiveModel = requestedModel || session.model;
+  const requestedAgentType = resolveAgentTypeFromModel(effectiveModel);
+  if (requestedAgentType === sessionAgentType) return null;
+  return {
+    error: 'CROSS_KIND_MODEL_SWITCH',
+    message: `Cannot switch agent kind mid-session (${agentLabel(sessionAgentType)} → ${agentLabel(requestedAgentType)})`,
+  };
+}