circuschief 0.8.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circuschief",
-  "version": "0.8.0",
+  "version": "1.1.0",
   "description": "Local-first web UI for managing Claude Code sessions",
   "type": "module",
   "bin": {

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

@@ -1,5 +1,6 @@
 import { ClaudeCodeAdapter } from './adapters/ClaudeCodeAdapter.js';
 import { CodexAdapter } from './adapters/CodexAdapter.js';
+import { GeminiAdapter } from './adapters/GeminiAdapter.js';
 
 /**
  * Factory/registry for agent adapters.
@@ -17,6 +18,7 @@ export class AgentGateway {
   _registerDefaultAdapters() {
     this.registerAdapter('claude-code', ClaudeCodeAdapter);
     this.registerAdapter('codex', CodexAdapter);
+    this.registerAdapter('gemini', GeminiAdapter);
   }
 
   /**

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

@@ -0,0 +1,105 @@
+import { BaseAgent } from '../BaseAgent.js';
+import { executeGeminiCli } from './geminiCliRunner.js';
+import { composeCliPrompt } from './cliUtils.js';
+import { createGeminiSpawner } from '../../services/geminiSpawnHelper.js';
+
+/**
+ * Module-level flag: once an ENOENT is observed for the Gemini CLI, remember
+ * it so subsequent calls can short-circuit.
+ */
+const geminiCliState = { unavailable: false };
+
+function markGeminiCliUnavailable() {
+  geminiCliState.unavailable = true;
+}
+
+/**
+ * Test-only: reset the module-level ENOENT cache.
+ * @private
+ */
+export function _resetGeminiCliUnavailableForTests() {
+  geminiCliState.unavailable = false;
+}
+
+/**
+ * Adapter for Google Gemini CLI.
+ *
+ * Execution path:
+ *   Spawns `gemini -p "prompt" --output-format stream-json -m <model>` and
+ *   parses its newline-delimited JSON stdout. Uses {@link createGeminiEventMapper}
+ *   to normalize events into the SDK-shaped envelope the rest of the app
+ *   already understands for Claude Code.
+ *
+ * Capabilities:
+ *   - streaming:       true  — stream-json provides real-time events
+ *   - thinking:        false — no separate thinking mode toggle
+ *   - reasoningEffort: false — no effort level mapping yet
+ *   - toolUse:         true  — Gemini CLI has built-in shell, file, and web tools
+ *   - resume:          false — no session resume support in headless mode
+ */
+export class GeminiAdapter extends BaseAgent {
+  static capabilities = Object.freeze({
+    streaming: true,
+    thinking: false,
+    reasoningEffort: false,
+    toolUse: true,
+    resume: false,
+  });
+
+  /**
+   * @param {Object} [opts]
+   * @param {Function} [opts.spawnGeminiProcess] - Optional DI for testing.
+   *   Shape matches {@link createGeminiSpawner} output.
+   * @param {Object} [opts.rest] - Passed to {@link BaseAgent}.
+   */
+  constructor({ spawnGeminiProcess, ...rest } = {}) {
+    super(rest);
+    this._spawnGemini = spawnGeminiProcess;
+  }
+
+  getCapabilities() {
+    return { ...GeminiAdapter.capabilities };
+  }
+
+  supportsResume() {
+    return false;
+  }
+
+  /**
+   * Execute a Gemini query and yield SDK-shaped events.
+   *
+   * @param {Object} queryParams
+   * @yields {Object} Normalized SDK events
+   */
+  async *execute(queryParams, _meta) {
+    const options = queryParams.options || {};
+    yield* this._executeCli(queryParams, options);
+  }
+
+  _executeCli(queryParams, options) {
+    const child = this._spawnGeminiChild(queryParams, options);
+    return executeGeminiCli(child, queryParams, options, markGeminiCliUnavailable);
+  }
+
+  _spawnGeminiChild(queryParams, options) {
+    const spawnFn = this._spawnGemini ?? createGeminiSpawner();
+    const { cwd, env, abortController, model, systemPrompt, approvalMode } = options;
+    const composedPrompt = composeCliPrompt(systemPrompt, queryParams.prompt);
+    const args = ['-p', composedPrompt, '--output-format', 'stream-json', '--skip-trust', '-m', model];
+    if (approvalMode) {
+      args.push(`--approval-mode=${approvalMode}`);
+    }
+
+    try {
+      return spawnFn({ command: 'gemini', args, cwd, env, signal: abortController?.signal });
+    } catch (err) {
+      if (err?.code === 'ENOENT') {
+        geminiCliState.unavailable = true;
+        const notFound = new Error('Gemini CLI not found');
+        notFound.code = 'GEMINI_CLI_NOT_FOUND';
+        throw notFound;
+      }
+      throw err;
+    }
+  }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Compose a CLI prompt by prepending the system prompt (if provided) to the
+ * user prompt. Used by both Codex and Gemini CLI runners.
+ *
+ * @param {string|null} systemPrompt
+ * @param {string|null} prompt
+ * @returns {string}
+ */
+export 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;
+}

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

@@ -1,5 +1,6 @@
 import readline from 'readline';
 import { createCodexEventMapper } from './codexEventMapper.js';
+import { composeCliPrompt } from './cliUtils.js';
 
 export async function *executeCodexCli(child, queryParams, options, markCliUnavailable) {
   const state = new CliState(options.model, markCliUnavailable);
@@ -76,14 +77,6 @@ function writePromptToStdin(child, 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 });

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

@@ -0,0 +1,183 @@
+import readline from 'readline';
+import { createGeminiEventMapper } from './geminiEventMapper.js';
+
+/**
+ * Execute the Gemini CLI child process and yield SDK-shaped events.
+ *
+ * Unlike Codex, the prompt is NOT passed via stdin — it's passed as the `-p`
+ * CLI argument by GeminiAdapter._spawnGeminiChild(). This runner only reads
+ * stdout/stderr and handles process lifecycle.
+ *
+ * @param {import('child_process').ChildProcess} child
+ * @param {Object} queryParams
+ * @param {Object} options
+ * @param {Function} markCliUnavailable
+ * @yields {Object} SDK-shaped events
+ */
+export async function *executeGeminiCli(child, queryParams, options, markCliUnavailable) {
+  const state = new CliState(options.model, markCliUnavailable);
+
+  attachAbortHandling(child, options.abortController, state);
+  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 = createGeminiEventMapper({ 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 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; // Ignore malformed JSON lines
+  }
+  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('Gemini CLI not found');
+  error.code = 'GEMINI_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(`Gemini CLI exited with code ${code}`);
+  error.code = 'GEMINI_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 */ }
+}

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

@@ -0,0 +1,195 @@
+/**
+ * Gemini CLI event mapper.
+ *
+ * Translates Gemini CLI `--output-format stream-json` JSONL events into the
+ * normalized SDK-shaped events that Circus Chief already understands:
+ *
+ *   - system(init)
+ *   - stream_event(content_block_delta)
+ *   - assistant
+ *   - tool_result
+ *   - result(success, usage)
+ *
+ * @param {Object} [options]
+ * @param {string} [options.model] - Model name to surface in the system(init) event.
+ * @returns {{
+ *   map: (geminiEvent: Object) => Array<Object>,
+ *   reset: () => void,
+ *   finalize: () => Array<Object>
+ * }}
+ */
+export function createGeminiEventMapper({ model } = {}) {
+  const state = new GeminiMapperState();
+  const warnedUnknownTypes = new Set();
+
+  function map(geminiEvent) {
+    if (!geminiEvent || typeof geminiEvent !== 'object') return [];
+
+    const type = geminiEvent.type;
+
+    if (type === 'init') {
+      return handleInit(geminiEvent, model);
+    }
+    if (type === 'message') {
+      return handleMessage(geminiEvent, state);
+    }
+    if (type === 'tool_use') {
+      return [...state.flushAccumulatedText(), ...handleToolUse(geminiEvent, state)];
+    }
+    if (type === 'tool_result') {
+      return [...state.flushAccumulatedText(), ...handleToolResult(geminiEvent, state)];
+    }
+    if (type === 'result') {
+      return [...state.flushAccumulatedText(), ...state.onResult(geminiEvent)];
+    }
+
+    // Unknown event type — warn once
+    if (type && !warnedUnknownTypes.has(type)) {
+      warnedUnknownTypes.add(type);
+      console.warn(`[geminiEventMapper] Unknown Gemini event type: "${type}"`);
+    }
+    return [];
+  }
+
+  return {
+    map,
+    reset: () => state.reset(),
+    finalize: () => state.finalize(),
+  };
+}
+
+// --- State class -----------------------------------------------------------
+
+class GeminiMapperState {
+  constructor() {
+    this.reset();
+  }
+
+  reset() {
+    this.lastUsage = null;
+    this.terminated = false;
+    this.pendingToolUse = new Map();
+    this.accumulatedText = '';
+  }
+
+  /**
+   * Flush any accumulated delta text as a synthetic `assistant` event.
+   * Returns an array (possibly empty) of events to prepend.
+   */
+  flushAccumulatedText() {
+    if (!this.accumulatedText) return [];
+    const text = this.accumulatedText;
+    this.accumulatedText = '';
+    return [{
+      type: 'assistant',
+      message: { content: [{ type: 'text', text }] },
+    }];
+  }
+
+  appendDeltaText(text) {
+    this.accumulatedText += text;
+  }
+
+  clearAccumulatedText() {
+    this.accumulatedText = '';
+  }
+
+  finalize() {
+    if (this.terminated) return [];
+    this.terminated = true;
+    return [...this.flushAccumulatedText(), this.buildResultEvent()];
+  }
+
+  onResult(evt) {
+    if (evt.stats) {
+      this.lastUsage = {
+        input_tokens: evt.stats.input_tokens || 0,
+        output_tokens: evt.stats.output_tokens || 0,
+      };
+    }
+    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,
+      },
+    };
+  }
+}
+
+// --- Event handlers --------------------------------------------------------
+
+function handleInit(evt, constructorModel) {
+  return [{
+    type: 'system',
+    subtype: 'init',
+    session_id: evt.session_id || `gemini-${Date.now()}`,
+    model: evt.model || constructorModel || undefined,
+  }];
+}
+
+function handleMessage(evt, state) {
+  // Ignore user message echoes
+  if (evt.role === 'user') return [];
+
+  if (evt.role === 'assistant') {
+    const text = evt.content || '';
+
+    // Delta (streaming partial) — accumulate for later persistence AND emit for live streaming
+    if (evt.delta) {
+      state.appendDeltaText(text);
+      return [{
+        type: 'stream_event',
+        event: {
+          type: 'content_block_delta',
+          delta: { type: 'text_delta', text },
+        },
+      }];
+    }
+
+    // Full message (non-delta) replaces any prior streamed delta accumulation.
+    // Some Gemini streams include both live deltas and a final full message; only
+    // the full message should be persisted in that mixed case.
+    state.clearAccumulatedText();
+    return [{
+      type: 'assistant',
+      message: { content: [{ type: 'text', text }] },
+    }];
+  }
+
+  return [];
+}
+
+function handleToolUse(evt, state) {
+  const toolName = evt.tool_name || 'unknown';
+  const toolId = evt.tool_id || `tool-${Date.now()}`;
+  const parameters = evt.parameters || {};
+
+  // Track for matching tool_result back
+  state.pendingToolUse.set(toolId, toolName);
+
+  return [{
+    type: 'tool_result',
+    tool_name: toolName,
+    content: JSON.stringify(parameters),
+  }];
+}
+
+function handleToolResult(evt, state) {
+  const toolId = evt.tool_id || '';
+  const toolName = state.pendingToolUse.get(toolId) || 'unknown';
+  const output = evt.output || '';
+
+  return [{
+    type: 'tool_result',
+    tool_name: toolName,
+    content: output,
+  }];
+}

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

@@ -8,6 +8,7 @@ import { databaseManager } from '../db/DatabaseManager.js';
 
 // Error message constants
 const ERR_SESSION_NOT_FOUND = 'Session not found';
+const ERR_BUTTON_NOT_FOUND = 'Circus Command not found';
 
 const router = Router({ mergeParams: true });
 
@@ -64,14 +65,14 @@ function broadcastCommandRunError({ sessionId, projectId, runId, buttonId, error
   });
 }
 
-// GET /api/projects/:projectId/command-buttons - List all command buttons for project
+// GET /api/projects/:projectId/circus-commands - List all command buttons for project
 router.get('/', (req, res) => {
   const { projectId } = req.params;
   const buttons = commandButtons.getByProjectId(projectId);
   res.json(buttons);
 });
 
-// GET /api/projects/:projectId/command-buttons/latest-runs - Get latest run for each button per session in project
+// GET /api/projects/:projectId/circus-commands/latest-runs - Get latest run for each button per session in project
 router.get('/latest-runs', (req, res) => {
   const { projectId } = req.params;
 
@@ -85,7 +86,7 @@ router.get('/latest-runs', (req, res) => {
   res.json(latestRuns);
 });
 
-// POST /api/projects/:projectId/command-buttons - Create new command button
+// POST /api/projects/:projectId/circus-commands - Create new command button
 router.post('/', (req, res) => {
   const result = CreateCommandButtonRequest.safeParse(req.body);
   if (!result.success) {
@@ -103,20 +104,20 @@ router.post('/', (req, res) => {
   res.status(201).json(button);
 });
 
-// GET /api/projects/:projectId/command-buttons/:id - Get single button
+// GET /api/projects/:projectId/circus-commands/:id - Get single button
 router.get('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
   res.json(button);
 });
 
-// PATCH /api/projects/:projectId/command-buttons/:id - Update button
+// PATCH /api/projects/:projectId/circus-commands/:id - Update button
 router.patch('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   const result = UpdateCommandButtonRequest.safeParse(req.body);
@@ -135,18 +136,18 @@ router.patch('/:id', (req, res) => {
   res.json(updated);
 });
 
-// DELETE /api/projects/:projectId/command-buttons/:id - Delete button
+// DELETE /api/projects/:projectId/circus-commands/:id - Delete button
 router.delete('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   commandButtons.delete(req.params.id);
   res.status(204).send();
 });
 
-// POST /api/sessions/:sessionId/command-buttons/:buttonId/run - Execute button command
+// POST /api/sessions/:sessionId/circus-commands/:buttonId/run - Execute button command
 router.post('/run/:buttonId', (req, res) => {
   const { sessionId, buttonId } = req.params;
 
@@ -157,7 +158,7 @@ router.post('/run/:buttonId', (req, res) => {
 
   const button = commandButtons.getById(buttonId);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   const workingDirectory = session.gitWorktree || session.project?.workingDirectory || process.cwd();
@@ -181,7 +182,7 @@ router.post('/run/:buttonId', (req, res) => {
   })();
 });
 
-// GET /api/sessions/:sessionId/command-buttons/runs - Get active runs for session
+// GET /api/sessions/:sessionId/circus-commands/runs - Get active runs for session
 router.get('/runs', (req, res) => {
   const { sessionId } = req.params;
 
@@ -221,7 +222,7 @@ router.get('/runs', (req, res) => {
   res.json(Array.from(runMap.values()));
 });
 
-// GET /api/sessions/:sessionId/command-buttons/runs/:runId - Get single run by ID
+// GET /api/sessions/:sessionId/circus-commands/runs/:runId - Get single run by ID
 router.get('/runs/:runId', (req, res) => {
   const { sessionId, runId } = req.params;
 
@@ -256,7 +257,7 @@ router.get('/runs/:runId', (req, res) => {
   });
 });
 
-// DELETE /api/sessions/:sessionId/command-buttons/runs/:runId - Delete a command run record
+// DELETE /api/sessions/:sessionId/circus-commands/runs/:runId - Delete a command run record
 router.delete('/runs/:runId', (req, res) => {
   const { sessionId, runId } = req.params;
 
@@ -292,7 +293,7 @@ router.delete('/runs/:runId', (req, res) => {
   res.status(204).send();
 });
 
-// POST /api/sessions/:sessionId/command-buttons/runs/:runId/kill - Kill running command
+// POST /api/sessions/:sessionId/circus-commands/runs/:runId/kill - Kill running command
 router.post('/runs/:runId/kill', (req, res) => {
   const { sessionId, runId } = req.params;