circuschief 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circuschief",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Local-first web UI for managing Claude Code sessions",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "liquidjs": "^10.24.0",
     "multer": "^1.4.5-lts.1",
     "nanoid": "^3.3.0",
+    "openai": "^4.104.0",
     "ws": "^8.18.0",
     "yaml": "^2.8.2"
   }

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

@@ -1,4 +1,5 @@
 import { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter.js';
+import { CodexAdapter } from './adapters/CodexAdapter.js';
 
 /**
  * Factory/registry for agent adapters.
@@ -8,11 +9,14 @@ export class AgentGateway {
   constructor() {
     /** @type {Map<string, typeof import('./BaseAgent.js').BaseAgent>} */
     this.adapters = new Map();
+    /** @type {Map<string, Object>} */
+    this._capabilitiesCache = new Map();
     this._registerDefaultAdapters();
   }
 
   _registerDefaultAdapters() {
     this.registerAdapter('claude-code', ClaudeCodeAdapter);
+    this.registerAdapter('codex', CodexAdapter);
   }
 
   /**
@@ -22,6 +26,8 @@ export class AgentGateway {
    */
   registerAdapter(agentType, AdapterClass) {
     this.adapters.set(agentType, AdapterClass);
+    // Invalidate any cached capabilities for this type.
+    this._capabilitiesCache.delete(agentType);
   }
 
   /**
@@ -48,15 +54,42 @@ export class AgentGateway {
   }
 
   /**
-   * Get capabilities for an agent type (uses a static check, no instantiation).
+   * Get capabilities for an agent type.
+   *
+   * Prefers the adapter's static `capabilities` field (no instantiation),
+   * falling back to constructing an empty instance and calling
+   * `getCapabilities()` for backward compatibility with adapters that
+   * haven't migrated yet.
+   *
    * @param {string} agentType
    * @returns {Object|null}
    */
   getAgentCapabilities(agentType) {
+    const cached = this._capabilitiesCache.get(agentType);
+    if (cached) return cached;
+
     const AdapterClass = this.adapters.get(agentType);
     if (!AdapterClass) return null;
-    // Capabilities are static per adapter class
-    return new AdapterClass({}).getCapabilities();
+
+    let caps;
+    if (AdapterClass.capabilities) {
+      caps = { ...AdapterClass.capabilities };
+    } else {
+      caps = new AdapterClass({}).getCapabilities();
+    }
+    this._capabilitiesCache.set(agentType, caps);
+    return caps;
+  }
+
+  /**
+   * Get capabilities for every registered adapter.
+   * @returns {Array<{ agentType: string, capabilities: Object }>}
+   */
+  getAllAgentCapabilities() {
+    return this.getAvailableAgents().map((agentType) => ({
+      agentType,
+      capabilities: this.getAgentCapabilities(agentType),
+    }));
   }
 }
 

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

@@ -26,14 +26,28 @@ export class BaseAgent {
     return false;
   }
 
+  /**
+   * Whether the adapter needs conversation history explicitly prepended
+   * to the prompt on continuation. Adapters that support resume (like
+   * Claude Code) maintain their own server-side context and return false.
+   * Adapters without resume capability return true — the execution layer
+   * must inject history as text so the model has context.
+   *
+   * @returns {boolean}
+   */
+  needsConversationContext() {
+    return !this.supportsResume();
+  }
+
   /**
    * Get agent capabilities
-   * @returns {{ streaming: boolean, thinking: boolean, toolUse: boolean, resume: boolean }}
+   * @returns {{ streaming: boolean, thinking: boolean, reasoningEffort: boolean, toolUse: boolean, resume: boolean }}
    */
   getCapabilities() {
     return {
       streaming: false,
       thinking: false,
+      reasoningEffort: false,
       toolUse: false,
       resume: false,
     };

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

@@ -67,6 +67,10 @@ export class LoggingAgentWrapper {
     return this.agent.supportsResume();
   }
 
+  needsConversationContext() {
+    return this.agent.needsConversationContext();
+  }
+
   getCapabilities() {
     return this.agent.getCapabilities();
   }

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

@@ -9,6 +9,14 @@ import { BaseAgent } from '../BaseAgent.js';
  * Event handling remains in sessionManager's handleStreamEvent().
  */
 export class ClaudeCodeAdapter extends BaseAgent {
+  static capabilities = Object.freeze({
+    streaming: true,
+    thinking: true,
+    reasoningEffort: true,
+    toolUse: true,
+    resume: true,
+  });
+
   /**
    * Execute a query against the Claude Code SDK.
    * @param {import('../types.js').AgentQueryParams} queryParams - { prompt, options? }
@@ -23,11 +31,6 @@ export class ClaudeCodeAdapter extends BaseAgent {
   }
 
   getCapabilities() {
-    return {
-      streaming: true,
-      thinking: true,
-      toolUse: true,
-      resume: true,
-    };
+    return { ...ClaudeCodeAdapter.capabilities };
   }
 }

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

@@ -1,26 +1,274 @@
 import { BaseAgent } from '../BaseAgent.js';
+import { executeCodexCli } from './codexCliRunner.js';
+import { createCodexSpawner } from '../../services/codexSpawnHelper.js';
 
 /**
- * Stub adapter for OpenAI Codex / future agents.
- * When implemented, this would:
- * 1. Transform AgentQueryParams into Codex API format
- * 2. Call the Codex API
- * 3. Yield events normalized to the SDK event format (system, assistant, tool_result, stream_event, result)
+ * Module-level flag: once an ENOENT is observed for the Codex CLI, remember
+ * it so subsequent calls skip the spawn attempt and can short-circuit the
+ * direct-API path selection.
+ */
+let codexCliUnavailable = false;
+
+/**
+ * Adapter for OpenAI Codex / any OpenAI-Chat-Completions-compatible model.
+ *
+ * Two execution paths:
  *
- * Phase 7 note: A NormalizedEvent format should be introduced at this point,
- * along with refactoring handleStreamEvent to consume normalized events.
+ *   1. CLI path (default) — spawns the `codex --json ...` CLI and parses its
+ *      line-delimited JSON stdout. Uses {@link createCodexEventMapper} to
+ *      normalize events into the SDK-shaped envelope the rest of the app
+ *      already understands.
+ *
+ *   2. Direct-API path — activated by {@code USE_CODEX_DIRECT_API=1}. Uses
+ *      the official {@code openai} SDK with Chat Completions streaming
+ *      against the provider's configured baseURL/apiKey. Intended for
+ *      environments where the Codex CLI isn't installable and for the
+ *      Step-0 contingency path in the implementation plan.
+ *
+ * Capabilities in v1:
+ *   - streaming:   true
+ *   - thinking:    false
+ *   - reasoningEffort: true
+ *   - toolUse:     true
+ *   - resume:      false  (Codex CLI v0.124.0 supports `codex resume` and
+ *                          `codex exec resume`, but Circus Chief defers
+ *                          wiring to a later phase — see
+ *                          docs/plans/openai-codex-agent.md §Phase 4.5)
  */
 export class CodexAdapter extends BaseAgent {
-  async *execute(_queryParams) { // eslint-disable-line require-yield
-    throw new Error('CodexAdapter is not yet implemented');
+  static capabilities = Object.freeze({
+    streaming: true,
+    thinking: false,
+    reasoningEffort: true,
+    toolUse: true,
+    resume: false,
+  });
+
+  /**
+   * @param {Object} [opts]
+   * @param {Function} [opts.spawnCodexProcess] - Optional DI for testing the
+   *   CLI path. Shape matches {@link createCodexSpawner} output.
+   * @param {Function} [opts.openaiClientFactory] - Optional DI for testing
+   *   the direct-API path: {@code ({ baseURL, apiKey, timeout }) => client}
+   *   where {@code client.chat.completions.create} is OpenAI-SDK-compatible.
+   * @param {Object} [opts.rest] - Passed to {@link BaseAgent}.
+   */
+  constructor({ spawnCodexProcess, openaiClientFactory, ...rest } = {}) {
+    super(rest);
+    this._spawnCodex = spawnCodexProcess;
+    this._openaiClientFactory = openaiClientFactory;
   }
 
   getCapabilities() {
-    return {
-      streaming: true,
-      thinking: false, // Codex doesn't have explicit thinking
-      toolUse: true,
-      resume: false, // Codex may not support session resume
+    return { ...CodexAdapter.capabilities };
+  }
+
+  supportsResume() {
+    return false;
+  }
+
+  /**
+   * Execute a Codex query and yield SDK-shaped events.
+   *
+   * @param {import('../types.js').AgentQueryParams} queryParams
+   * @yields {Object} Normalized SDK events
+   */
+  async *execute(queryParams, _meta) {
+    const options = queryParams.options || {};
+    if (this._shouldUseDirectApi()) {
+      yield* this._executeDirectApi(queryParams, options);
+      return;
+    }
+    yield* this._executeCli(queryParams, options);
+  }
+
+  _shouldUseDirectApi() {
+    if (process.env.USE_CODEX_DIRECT_API === '1') return true;
+    if (this._spawnCodex === null) return true;
+    if (codexCliUnavailable) return true;
+    return false;
+  }
+
+  /**
+   * CLI path — spawn the Codex CLI and stream JSON events.
+   *
+   * Real invocation (v0.124.0):
+   *   codex exec --json --skip-git-repo-check --sandbox <mode> -m <model>
+   *
+   * Notes:
+   *   - The `exec` subcommand is required (bare `codex --json` does not work).
+   *   - There is no `--system` flag; system prompts are prepended to the
+   *     stdin prompt via {@link composeCliPrompt}.
+   *   - Sandbox mode is driven by {@code options.sandboxMode} (defaults to
+   *     `workspace-write`) which is set by
+   *     {@code buildCodexQueryParams} from {@code session.mode}.
+   */
+  async *_executeCli(queryParams, options) {
+    const child = this._spawnCodexChild(queryParams, options);
+    yield* executeCodexCli(child, queryParams, options, markCodexCliUnavailable);
+  }
+
+  _spawnCodexChild(queryParams, options) {
+    const spawnFn = this._spawnCodex ?? createCodexSpawner();
+    const { cwd, env, abortController, model, sandboxMode, effortLevel } = options;
+    const effectiveSandbox = sandboxMode || 'workspace-write';
+    const codexReasoningEffort = resolveCodexReasoningEffort(effortLevel);
+    const args = [
+      'exec',
+      '--json',
+      '--skip-git-repo-check',
+      '--sandbox', effectiveSandbox,
+      '-m', model,
+    ];
+
+    if (codexReasoningEffort) {
+      args.push(
+        '-c', `model_reasoning_effort=${codexReasoningEffort}`,
+        '-c', `plan_mode_reasoning_effort=${codexReasoningEffort}`
+      );
+    }
+
+    // Defense in depth: when no API key is in the env, force ChatGPT auth
+    // so the CLI uses its own OAuth flow even if some env var leaks through.
+    if (!env?.OPENAI_API_KEY) {
+      args.push('-c', 'preferred_auth_method=chatgpt');
+    }
+
+    console.log('[CodexAdapter] auth_mode_hint =', env?.OPENAI_API_KEY ? 'apikey' : 'chatgpt');
+
+    try {
+      return spawnFn({
+        command: 'codex',
+        args,
+        cwd,
+        env,
+        signal: abortController?.signal,
+      });
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        codexCliUnavailable = true;
+        const notFound = new Error('Codex CLI not found');
+        notFound.code = 'CODEX_CLI_NOT_FOUND';
+        throw notFound;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Direct-API path — stream Chat Completions via the OpenAI SDK.
+   */
+  async *_executeDirectApi(queryParams, options) {
+    const { model, systemPrompt, abortController } = resolveDirectApiInputs(options);
+    const client = await this._resolveOpenAiClient(options);
+
+    yield {
+      type: 'system',
+      subtype: 'init',
+      session_id: `codex-${Date.now()}`,
+      model,
+    };
+
+    const stream = await client.chat.completions.create({
+      model,
+      messages: buildChatMessages(queryParams.prompt, systemPrompt),
+      stream: true,
+    });
+
+    const onAbort = () => {
+      try { stream?.controller?.abort?.(); } catch { /* ignore */ }
+    };
+    abortController?.signal?.addEventListener('abort', onAbort);
+
+    let accumulated = '';
+    let finalUsage = null;
+
+    try {
+      for await (const chunk of stream) {
+        const text = chunk?.choices?.[0]?.delta?.content;
+        if (text) {
+          accumulated += text;
+          yield makeTextDeltaEvent(text);
+        }
+        if (chunk?.usage) finalUsage = chunk.usage;
+      }
+    } finally {
+      abortController?.signal?.removeEventListener('abort', onAbort);
+    }
+
+    yield { type: 'assistant', message: { content: [{ type: 'text', text: accumulated }] } };
+    yield {
+      type: 'result',
+      subtype: 'success',
+      usage: {
+        input_tokens: finalUsage?.prompt_tokens ?? 0,
+        output_tokens: finalUsage?.completion_tokens ?? 0,
+      },
     };
   }
+
+  async _resolveOpenAiClient(options) {
+    const env = options.env || process.env;
+    const baseURL = env.OPENAI_BASE_URL || env.OPENAI_API_BASE;
+    const apiKey = env.OPENAI_API_KEY;
+    const timeout = env.API_TIMEOUT_MS ? Number(env.API_TIMEOUT_MS) : undefined;
+
+    if (this._openaiClientFactory) {
+      return this._openaiClientFactory({ baseURL, apiKey, timeout });
+    }
+    if (!apiKey) {
+      const err = new Error('OPENAI_API_KEY not set — cannot use Codex direct-API path');
+      err.code = 'OPENAI_API_KEY_MISSING';
+      throw err;
+    }
+    const { default: OpenAI } = await import('openai');
+    return new OpenAI({ baseURL, apiKey, timeout });
+  }
+}
+
+/**
+ * Test-only: reset the module-level ENOENT cache so each test case starts
+ * from a known state.
+ * @private
+ */
+export function _resetCodexCliUnavailableForTests() {
+  codexCliUnavailable = false;
+}
+
+// --- Direct-API helpers ----------------------------------------------------
+
+function markCodexCliUnavailable() {
+  codexCliUnavailable = true;
+}
+
+function resolveDirectApiInputs(options) {
+  return {
+    model: options.model || 'gpt-4o-mini',
+    systemPrompt: typeof options.systemPrompt === 'string' ? options.systemPrompt : null,
+    abortController: options.abortController,
+  };
+}
+
+function resolveCodexReasoningEffort(effortLevel) {
+  if (!effortLevel || effortLevel === 'auto') return null;
+  if (effortLevel === 'max') return 'xhigh';
+  if (['low', 'medium', 'high'].includes(effortLevel)) return effortLevel;
+  return null;
+}
+
+function buildChatMessages(prompt, systemPrompt) {
+  const messages = [];
+  if (systemPrompt) messages.push({ role: 'system', content: systemPrompt });
+  messages.push({ role: 'user', content: prompt ?? '' });
+  return messages;
+}
+
+function makeTextDeltaEvent(text) {
+  return {
+    type: 'stream_event',
+    event: {
+      type: 'content_block_delta',
+      delta: { type: 'text_delta', text },
+    },
+  };
 }

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

@@ -0,0 +1,185 @@
+import readline from 'readline';
+import { createCodexEventMapper } from './codexEventMapper.js';
+
+export async function *executeCodexCli(child, queryParams, options, markCliUnavailable) {
+  const state = new CliState(options.model, markCliUnavailable);
+
+  attachAbortHandling(child, options.abortController, state);
+  writePromptToStdin(child, composeCliPrompt(options.systemPrompt, queryParams.prompt));
+  attachStdoutReader(child, state);
+  attachStderrReader(child, state);
+  attachProcessLifecycleHandlers(child, state);
+
+  try {
+    yield* drainCliEvents(state);
+  } finally {
+    cleanupCli(options.abortController, state);
+  }
+}
+
+class CliState {
+  constructor(model, markCliUnavailable) {
+    this.pending = [];
+    this.error = null;
+    this.ended = false;
+    this.resolveNext = null;
+    this.rejectAll = null;
+    this.mapper = createCodexEventMapper({ model });
+    this.rl = null;
+    this.killTimer = null;
+    this.onAbort = null;
+    this.stderrBuffer = '';
+    this.markCliUnavailable = markCliUnavailable;
+  }
+
+  assign(patch) {
+    Object.assign(this, patch);
+  }
+
+  pushEvents(events) {
+    for (const event of events) this.pending.push(event);
+    this.tickWaiter();
+  }
+
+  tickWaiter() {
+    if (!this.resolveNext) return;
+    const resolve = this.resolveNext;
+    this.resolveNext = null;
+    resolve();
+  }
+
+  failWith(error) {
+    this.error = error;
+    if (this.rejectAll) this.rejectAll(error);
+  }
+
+  markEnded() {
+    this.ended = true;
+  }
+}
+
+function attachAbortHandling(child, abortController, state) {
+  const onAbort = () => {
+    try { child.kill('SIGTERM'); } catch { /* ignore */ }
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch { /* ignore */ }
+    }, 2000);
+    state.assign({ killTimer: timer });
+  };
+  state.assign({ onAbort });
+  abortController?.signal?.addEventListener('abort', onAbort);
+}
+
+function writePromptToStdin(child, prompt) {
+  try {
+    if (child.stdin) child.stdin.end(prompt ?? '');
+  } catch { /* ignore */ }
+}
+
+function composeCliPrompt(systemPrompt, prompt) {
+  const user = prompt ?? '';
+  if (typeof systemPrompt === 'string' && systemPrompt.length > 0) {
+    return `SYSTEM PROMPT:\n${systemPrompt}\n\nUSER:\n${user}`;
+  }
+  return user;
+}
+
+function attachStdoutReader(child, state) {
+  const rl = readline.createInterface({ input: child.stdout });
+  state.assign({ rl });
+  rl.on('line', (line) => handleCliStdoutLine(line, state));
+}
+
+function handleCliStdoutLine(line, state) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return;
+  }
+  try {
+    const mapped = state.mapper.map(parsed);
+    if (mapped.length > 0) state.pushEvents(mapped);
+  } catch (error) {
+    state.failWith(error);
+  }
+}
+
+function attachStderrReader(child, state) {
+  if (!child.stderr) return;
+  child.stderr.on('data', (chunk) => {
+    if (state.error || state.ended) return;
+    state.assign({ stderrBuffer: state.stderrBuffer + chunk.toString() });
+  });
+}
+
+function attachProcessLifecycleHandlers(child, state) {
+  child.on('error', (error) => {
+    if (error?.code === 'ENOENT') {
+      state.markCliUnavailable?.();
+      state.failWith(makeCliNotFoundError());
+      return;
+    }
+    state.failWith(error);
+  });
+
+  child.on('exit', (code) => handleChildExit(code, state));
+}
+
+function makeCliNotFoundError() {
+  const error = new Error('Codex CLI not found');
+  error.code = 'CODEX_CLI_NOT_FOUND';
+  return error;
+}
+
+function handleChildExit(code, state) {
+  state.markEnded();
+  if (code !== 0 && !state.error) {
+    state.failWith(makeCliExitError(code, state.stderrBuffer));
+  } else if (!state.error) {
+    finalizeMappedEvents(state);
+  }
+  state.tickWaiter();
+}
+
+function makeCliExitError(code, stderrBuffer) {
+  const stderrTrimmed = stderrBuffer.trim();
+  const error = stderrTrimmed.length > 0
+    ? new Error(stderrTrimmed)
+    : new Error(`Codex CLI exited with code ${code}`);
+  error.code = 'CODEX_CLI_EXIT';
+  error.exitCode = code;
+  return error;
+}
+
+function finalizeMappedEvents(state) {
+  try {
+    const events = state.mapper.finalize();
+    if (events.length > 0) state.pushEvents(events);
+  } catch { /* ignore */ }
+}
+
+async function *drainCliEvents(state) {
+  while (true) {
+    if (state.error) throw state.error;
+    if (state.pending.length > 0) {
+      yield state.pending.shift();
+      continue;
+    }
+    if (state.ended) break;
+    await new Promise((resolve, reject) => {
+      state.assign({ resolveNext: resolve, rejectAll: reject });
+    });
+  }
+  if (state.error) throw state.error;
+}
+
+function cleanupCli(abortController, state) {
+  if (state.onAbort) {
+    abortController?.signal?.removeEventListener('abort', state.onAbort);
+  }
+  if (state.killTimer) clearTimeout(state.killTimer);
+  try { state.rl?.close(); } catch { /* ignore */ }
+}