circuschief 0.4.0 → 0.6.0

package/packages/server/src/agents/adapters/codexEventMapper.js

@@ -0,0 +1,235 @@
+/**
+ * Codex event mapper.
+ *
+ * Translates the real Codex CLI JSON-line event schema (as emitted by
+ * `codex exec --json`) into the normalized SDK-shaped events that Circus
+ * Chief's stream event handler already understands for Claude Code:
+ *
+ *   - {@code system(init)}
+ *   - {@code stream_event(content_block_delta)}
+ *   - {@code assistant}
+ *   - {@code result(success, usage)}
+ *
+ * Real Codex event types (v0.124.0, confirmed via
+ * `codex app-server generate-json-schema`):
+ *
+ *   - {@code thread.started}   — { thread_id }
+ *   - {@code turn.started}     — no payload
+ *   - {@code item.started}     — { item: ThreadItem }
+ *   - {@code item.completed}   — { item: ThreadItem }
+ *   - {@code turn.completed}   — { usage: { input_tokens, cached_input_tokens, output_tokens } }
+ *   - {@code turn.failed}      — { error: { message } }
+ *   - {@code error}            — { message } (transient, treated as fatal)
+ *
+ * ThreadItem.type variants handled in v1:
+ *   - {@code agent_message} — { id, text, ... }  → emitted as text_delta + assistant
+ *   - {@code command_execution} — { id, command, aggregated_output, exit_code, status } → tool_result
+ *   - {@code file_change} — { id, changes: [{path, kind}] } → tool_result
+ *   - {@code reasoning} — { id, text } or legacy { content: [{type, text}] } → tool_result
+ *
+ * All other variants (mcp_tool_call,
+ * dynamic_tool_call, collab_agent_tool_call, web_search, image_view, image_generation,
+ * plan, context_compaction, hook_prompt, entered_review_mode, exited_review_mode,
+ * user_message) are currently ignored.
+ *
+ * The mapper is stateful across calls so it can accumulate agent message
+ * text across multiple `item.completed` events within a turn and stash
+ * usage counters until the terminal `turn.completed`.
+ *
+ * Pure in-process — no I/O, no timers, no child processes.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.model] - Optional model name to surface in the
+ *   {@code system(init)} event. Codex's {@code thread.started} event does
+ *   not carry the model, so the adapter must pass it in.
+ * @returns {{
+ *   map: (codexEvent: Object) => Array<Object>,
+ *   reset: () => void,
+ *   finalize: () => Array<Object>
+ * }}
+ */
+export function createCodexEventMapper({ model } = {}) {
+  const mapperState = new MapperState();
+  const warnedUnknownItemTypes = new Set();
+
+  const handlers = {
+    'thread.started': (evt) => handleThreadStarted(evt, model),
+    'turn.started': () => [],
+    'item.started': () => [],
+    'item.completed': (evt) => handleItemCompleted(evt, mapperState, warnedUnknownItemTypes),
+    'turn.completed': (evt) => mapperState.onTurnCompleted(evt),
+    'turn.failed': (evt) => handleTurnFailed(evt),
+    'error': (evt) => handleError(evt),
+  };
+
+  function map(codexEvent) {
+    if (!codexEvent || typeof codexEvent !== 'object') return [];
+    const handler = handlers[codexEvent.type];
+    if (!handler) {
+      console.warn(`[codexEventMapper] Unknown Codex event type: "${codexEvent.type}"`);
+      return [];
+    }
+    return handler(codexEvent);
+  }
+
+  return {
+    map,
+    reset: () => mapperState.reset(),
+    finalize: () => mapperState.finalize(),
+  };
+}
+
+// --- Mapper state class ----------------------------------------------------
+
+class MapperState {
+  constructor() {
+    this.reset();
+  }
+
+  reset() {
+    this.lastUsage = null;
+    this.terminated = false;
+  }
+
+  /**
+   * Called by the adapter when the underlying stream ends without an explicit
+   * {@code turn.completed}. Returns a terminal result event if one hasn't been
+   * emitted yet; otherwise an empty array.
+   */
+  finalize() {
+    if (this.terminated) return [];
+    this.terminated = true;
+    return [this.buildResultEvent()];
+  }
+
+  onTurnCompleted(evt) {
+    if (evt && evt.usage) {
+      this.lastUsage = {
+        input_tokens: evt.usage.input_tokens,
+        output_tokens: evt.usage.output_tokens,
+      };
+    }
+    this.terminated = true;
+    return [this.buildResultEvent()];
+  }
+
+  buildResultEvent() {
+    const usage = this.lastUsage || { input_tokens: 0, output_tokens: 0 };
+    return {
+      type: 'result',
+      subtype: 'success',
+      usage: {
+        input_tokens: usage.input_tokens || 0,
+        output_tokens: usage.output_tokens || 0,
+      },
+    };
+  }
+}
+
+// --- Pure event handlers ---------------------------------------------------
+
+function handleThreadStarted(evt, model) {
+  const init = {
+    type: 'system',
+    subtype: 'init',
+    session_id: evt.thread_id,
+  };
+  if (model) init.model = model;
+  return [init];
+}
+
+function handleItemCompleted(evt, _state, warnedTypes) {
+  const item = evt.item;
+  if (!item || typeof item !== 'object') return [];
+
+  if (isAgentMessageItem(item)) {
+    const text = typeof item.text === 'string' ? item.text : '';
+    return [
+      {
+        type: 'stream_event',
+        event: {
+          type: 'content_block_delta',
+          delta: { type: 'text_delta', text },
+        },
+      },
+      {
+        type: 'assistant',
+        message: { content: [{ type: 'text', text }] },
+      },
+    ];
+  }
+
+  if (item.type === 'command_execution') {
+    return [mapCommandExecution(item)];
+  }
+
+  if (item.type === 'file_change') {
+    return [mapFileChange(item)];
+  }
+
+  if (item.type === 'reasoning') {
+    return [mapReasoning(item)];
+  }
+
+  // Unknown types — warn once per type
+  if (item.type && !warnedTypes.has(item.type)) {
+    warnedTypes.add(item.type);
+    console.warn(`[codexEventMapper] Ignoring unsupported item.type "${item.type}"`);
+  }
+  return [];
+}
+
+function isAgentMessageItem(item) {
+  return item.type === 'agent_message' || item.type === 'agentMessage';
+}
+
+function handleTurnFailed(evt) {
+  const message = evt?.error?.message || 'Codex turn failed';
+  throw new Error(message);
+}
+
+function handleError(evt) {
+  const message = evt?.message || 'Codex error';
+  throw new Error(message);
+}
+
+// --- Tool-use mapping helpers -----------------------------------------------
+
+function mapCommandExecution(item) {
+  const cmd = item.command || '';
+  const parts = [`$ ${cmd}`];
+  if (item.exit_code !== undefined && item.exit_code !== 0) {
+    parts.push(`exit code: ${item.exit_code}`);
+  }
+  if (item.aggregated_output) parts.push(item.aggregated_output);
+  return {
+    type: 'tool_result',
+    tool_name: 'command_execution',
+    content: parts.join('\n'),
+  };
+}
+
+function mapFileChange(item) {
+  const changes = Array.isArray(item.changes)
+    ? item.changes.map((c) => `${c.kind || 'change'}: ${c.path || 'unknown'}`).join('\n')
+    : 'unknown file change';
+  return {
+    type: 'tool_result',
+    tool_name: 'file_change',
+    content: changes,
+  };
+}
+
+function mapReasoning(item) {
+  // v0.124.0 shape: plain `text` string (e.g. gpt-5.2)
+  // Legacy shape: `content` array of {type, text} objects
+  const text = item.text
+    || (Array.isArray(item.content)
+      ? item.content.map((c) => c.text || '').join('\n')
+      : '');
+  return {
+    type: 'tool_result',
+    tool_name: 'reasoning',
+    content: text,
+  };
+}

package/packages/server/src/agents/types.js

@@ -24,6 +24,7 @@
  * @property {Object} env - Environment variables
  * @property {Function} spawnClaudeCodeProcess - Process spawner function
  * @property {string} [model] - Model to use
+ * @property {string|null} [effortLevel] - Reasoning effort override, or null/auto for provider default
  * @property {string} systemPrompt - System prompt string
  */
 

package/packages/server/src/agents/vcr/VCRAgentAdapter.js

@@ -116,6 +116,14 @@ export class VCRAgentAdapter {
     return this.innerAgent.supportsResume?.() ?? false;
   }
 
+  /**
+   * Proxy conversation context need to inner agent
+   * @returns {boolean}
+   */
+  needsConversationContext() {
+    return this.innerAgent.needsConversationContext?.() ?? true;
+  }
+
   /**
    * Proxy capabilities to inner agent
    * @returns {object}

package/packages/server/src/api/agents.js

@@ -0,0 +1,27 @@
+import { Router } from 'express';
+import { agentGateway } from '../agents/AgentGateway.js';
+
+const router = Router();
+
+/**
+ * GET /api/agents
+ *
+ * Returns the capabilities of every registered agent adapter, sourced from the
+ * adapter's static `capabilities` field (no adapter instantiation).
+ *
+ * Response shape:
+ *   [
+ *     { agentType: 'claude-code', capabilities: { streaming, thinking, reasoningEffort, toolUse, resume } },
+ *     { agentType: 'codex',       capabilities: { streaming, thinking, reasoningEffort, toolUse, resume } },
+ *   ]
+ */
+router.get('/', (_req, res) => {
+  try {
+    const agents = agentGateway.getAllAgentCapabilities();
+    res.json(agents);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+export default router;

package/packages/server/src/api/canvas.js

@@ -279,6 +279,26 @@ router.get('/:id/canvas/file/:filename/content', (req, res) => {
   });
 });
 
+// GET /api/sessions/:id/canvas/:itemId/content - Get one canvas item content inline
+router.get('/:id/canvas/:itemId/content', (req, res) => {
+  const session = sessions.getById(req.params.id);
+  if (!session) return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
+
+  const item = canvasItems.getById(req.params.itemId);
+  if (!item) return res.status(404).json({ error: 'Canvas item not found' });
+  if (item.sessionId !== req.params.id) {
+    return res.status(400).json({ error: 'Canvas item does not belong to this session' });
+  }
+
+  res.json({
+    content: item.content ?? null,
+    data: item.data ?? null,
+    type: item.type,
+    mimeType: item.mimeType,
+    filename: item.filename,
+  });
+});
+
 // GET /api/sessions/:id/canvas/file/:filename - Get canvas file by filename
 // Writes the file to /tmp and returns the file path for Claude's Read tool
 // Always returns the latest version

package/packages/server/src/api/index.js

@@ -11,6 +11,7 @@ import providersRouter from './providers.js';
 import commandsRouter from './commands.js';
 import metricsRouter from './metrics.js';
 import kanbanRouter from './kanban.js';
+import agentsRouter from './agents.js';
 import { getDbPath } from '../database.js';
 import { schedulerService } from '../services/schedulerService.js';
 
@@ -38,6 +39,7 @@ router.use('/git', gitRouter);
 router.use('/filesystem', filesystemRouter);
 router.use('/settings', settingsRouter);
 router.use('/providers', providersRouter);
+router.use('/agents', agentsRouter);
 router.use('/commands', commandsRouter)
 
 // Canvas routes are nested under sessions

package/packages/server/src/api/projects.js

@@ -18,6 +18,7 @@ import {
   setupAndStartSession,
 } from './projects-session-helpers.js';
 import { validateGitSettings, buildRunsBySession } from './projects-helpers.js';
+import { resolveAgentTypeFromModel } from '../services/sessionProvider.js';
 import { access, constants } from 'fs/promises';
 import { dirname, isAbsolute } from 'path';
 
@@ -243,6 +244,7 @@ function createSessionRow(projectId, config, nextTemplateId, initialStatus) {
     status: initialStatus,
     model: config.model,
     effortLevel: config.effortLevel,
+    agentType: config.agentType,
   });
 
   const postCreateUpdate = {
@@ -298,6 +300,11 @@ router.post('/:id/sessions', uploadMiddleware('files', 10), handleUploadError, a
     }
 
     const { config, nextTemplateId } = prepared;
+    // Derive the agent type from the resolved model (after template overrides
+    // have been applied inside validateAndPrepareSessionConfig). Null/unknown
+    // model IDs fall back to 'claude-code'. This is the single source of truth
+    // for which adapter the session will use; sessions.create() persists it.
+    config.agentType = resolveAgentTypeFromModel(config.model);
     const initialStatus = determineInitialStatus(config);
     session = createSessionRow(req.params.id, config, nextTemplateId, initialStatus);
     return await startSessionOrFail(req, res, { session, config, project });

package/packages/server/src/api/providers.js

@@ -139,6 +139,7 @@ router.post('/:id/test', async (req, res) => {
     // Pick the sonnet-tiered model (if any) as the test model, falling back to any first model
     const sonnetModel = provider.models?.find((m) => m.tier === 'sonnet');
     const testConfig = {
+      kind: provider.kind || 'anthropic',
       baseUrl: provider.baseUrl,
       authToken: provider.authToken,
       defaultSonnetModel: sonnetModel?.modelId,

package/packages/server/src/api/sessions-messages.js

@@ -4,6 +4,7 @@ import { continueSession } from '../services/sessionManager.js';
 import { upload as _upload, handleUploadError } from '../middleware/upload.js';
 import { requireSession, requireSessionAndProject } from '../middleware/sessionLookup.js';
 import * as slashCommandService from '../services/slashCommandService.js';
+import { checkCrossKindSwitch } from '../services/sessionAgentGuard.js';
 
 const router = Router();
 
@@ -61,6 +62,11 @@ router.post('/:id/message', _upload.array('files', 10), handleUploadError, requi
     return res.status(400).json({ error: 'Session is not waiting for input' });
   }
 
+  const crossKindError = checkCrossKindSwitch(req.session_, model);
+  if (crossKindError) {
+    return res.status(400).json(crossKindError);
+  }
+
   try {
     // Store file attachments if any - saves to disk in workingDirectory/.attachments
     const messageAttachments = attachments.createBatch(req.session_.id, null, files, req.workingDirectory);

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

@@ -2,6 +2,22 @@ import { BaseRepository } from './BaseRepository.js';
 import { databaseManager } from './DatabaseManager.js';
 import { encrypt, decrypt } from '../services/encryption.js';
 
+/**
+ * Valid values for `providers.kind`. Maps 1:1 to an agent adapter:
+ *   - 'anthropic' → 'claude-code'
+ *   - 'openai'    → 'codex'
+ */
+export const PROVIDER_KINDS = Object.freeze(['anthropic', 'openai']);
+
+/**
+ * Mapping from provider kind to the agent adapter that should drive sessions
+ * backed by that provider.
+ */
+export const AGENT_TYPE_BY_KIND = Object.freeze({
+  anthropic: 'claude-code',
+  openai: 'codex',
+});
+
 /**
  * Provider repository class (replaces ModelProviderRepository).
  *
@@ -11,6 +27,8 @@ import { encrypt, decrypt } from '../services/encryption.js';
  * - No auto-sync logic (#syncDefaultModels removed)
  * - Auth tokens are encrypted at rest (AES-256-GCM via encryption service)
  * - `getProviderByModelId` includes models (needed for buildProviderEnv)
+ * - Providers carry a `kind` (`'anthropic'` | `'openai'`) that selects the
+ *   agent adapter and env-var convention. `kind` is **immutable** after create.
  */
 export class ProviderRepository extends BaseRepository {
   constructor() {
@@ -27,6 +45,7 @@ export class ProviderRepository extends BaseRepository {
       apiTimeoutMs: row.api_timeout_ms,
       additionalEnvVars: row.additional_env_vars ? JSON.parse(row.additional_env_vars) : null,
       isBuiltIn: row.is_built_in === 1,
+      kind: row.kind || 'anthropic',
       createdAt: row.created_at,
       updatedAt: row.updated_at,
     };
@@ -64,12 +83,20 @@ export class ProviderRepository extends BaseRepository {
       authToken = null,
       apiTimeoutMs = null,
       additionalEnvVars = null,
+      kind = 'anthropic',
     } = data;
 
+    // Application-layer validation: give a clear error ahead of the DB CHECK.
+    if (!PROVIDER_KINDS.includes(kind)) {
+      throw new Error(
+        `Invalid provider kind "${kind}". Must be one of: ${PROVIDER_KINDS.join(', ')}.`
+      );
+    }
+
     this.db
       .prepare(
-        `INSERT INTO providers (id, name, base_url, auth_token, api_timeout_ms, additional_env_vars, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO providers (id, name, base_url, auth_token, api_timeout_ms, additional_env_vars, kind, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
       )
       .run(
         id,
@@ -78,6 +105,7 @@ export class ProviderRepository extends BaseRepository {
         encrypt(authToken),
         apiTimeoutMs,
         additionalEnvVars ? JSON.stringify(additionalEnvVars) : null,
+        kind,
         now,
         now
       );
@@ -115,6 +143,15 @@ export class ProviderRepository extends BaseRepository {
    * @returns {Object} Updated provider (with models array)
    */
   update(id, data) {
+    // `kind` is immutable after create. Existing models + env wiring depend on it,
+    // so changing it in place would silently corrupt sessions already attached to
+    // this provider.
+    if (data && Object.prototype.hasOwnProperty.call(data, 'kind')) {
+      throw new Error(
+        "Provider kind is immutable after create. Delete and recreate the provider to change kind."
+      );
+    }
+
     const updates = [];
     const values = [];
 
@@ -279,12 +316,15 @@ export class ProviderRepository extends BaseRepository {
       return null;
     }
 
-    // Find which provider owns this model ID
+    // Prefer custom providers over built-ins for duplicate model IDs. This
+    // preserves user-managed OpenAI providers (alternate base URLs, keys, or
+    // env vars) even when official OpenAI models are also seeded built-ins.
     const row = this.db
       .prepare(
         `SELECT p.id FROM providers p
          JOIN provider_models pm ON p.id = pm.provider_id
-         WHERE pm.model_id = ?`
+         WHERE pm.model_id = ?
+         ORDER BY p.is_built_in ASC, p.name ASC`
       )
       .get(modelId);
 
@@ -297,11 +337,27 @@ export class ProviderRepository extends BaseRepository {
     const provider = this.getById(row.id);
     if (!provider) return null;
 
-    // Built-in Anthropic provider falls through to SDK defaults
-    if (provider.isBuiltIn) {
+    // Built-in **Anthropic** provider falls through to SDK defaults (keeps
+    // historical behavior of letting @anthropic-ai/claude-agent-sdk pick its
+    // own env). Built-in OpenAI (or any future non-Anthropic built-in) still
+    // needs its env vars to flow, so we return the provider object.
+    if (provider.isBuiltIn && provider.kind === 'anthropic') {
       return null;
     }
 
     return provider;
   }
+
+  /**
+   * Resolve a provider's agent type from its id.
+   * @param {string|null|undefined} providerId
+   * @returns {string|null} 'claude-code' for anthropic-kind, 'codex' for openai-kind,
+   *   or null if the provider is unknown.
+   */
+  getAgentTypeForProvider(providerId) {
+    if (!providerId) return null;
+    const provider = this.getById(providerId);
+    if (!provider) return null;
+    return AGENT_TYPE_BY_KIND[provider.kind] || null;
+  }
 }