codehere 0.3.3 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@
 [![Tests](https://img.shields.io/badge/tests-362%2F362-brightgreen)]()
 [![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)]()
 
-codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks the right specialist (Claude Code, Codex, Aider, or OpenCode), spawns it, streams its work back to you, and hands you a plain-English Final Report with a **trust score on every file changed**. Today, Claude Code gets full pre-execution safety-hook enforcement on every tool call; other adapters are session-traced and reported, with per-tool hook parity planned for v0.4.
+codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks the right specialist (Claude Code, Codex, Aider, OpenCode, or Gemini), spawns it, streams its work back to you, and hands you a plain-English Final Report with a **trust score on every file changed**. Today, Claude Code gets full pre-execution safety-hook enforcement on every tool call; other adapters are session-traced and reported, with per-tool hook parity planned for v0.4.
 
 One manager, many specialists, every action recorded.
 
@@ -25,7 +25,7 @@ One manager, many specialists, every action recorded.
 | 1 | **Install** | `npm install -g codehere` (Node 20+) |
 | 2 | **Detect environment** | `codehere setup` — checks API key, finds your repo |
 | 3 | **Install the safety hook** | `codehere hook install` — every Claude Code tool call now audited |
-| 4 | **Install at least one specialist** | Claude Code: `npm i -g @anthropic-ai/claude-code` (Codex / Aider / OpenCode also supported) |
+| 4 | **Install at least one specialist** | Claude Code: `npm i -g @anthropic-ai/claude-code` (Codex / Aider / OpenCode / Gemini also supported · see [docs/integrations/](../docs/integrations/) for Cursor MCP setup) |
 | 5 | **Scaffold this repo** | `cd /your/repo && codehere init` — creates `.codehere/CONTEXT.md`, `HANDOVER.md`, `PROMPTS.md` |
 | 6 | **Fill in CONTEXT.md** | 5 minutes. The agent will follow what's written there. |
 
@@ -57,7 +57,7 @@ Context  +  End State  +  Constraints
 
 1. Spawns the agent with the right headless flags
 2. Streams the steps back as readable progress · *"Read src/auth.ts · Edit src/auth.ts · Run npm test"*
-3. For Claude Code tasks: routes every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live. For Codex / Aider / OpenCode tasks: emits the agent's native event stream (no per-tool blocking yet)
+3. For Claude Code tasks: routes every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live. For Codex / Aider / OpenCode / Gemini tasks: emits the agent's native event stream (no per-tool blocking yet)
 4. On completion, hands you a **Final report**: files changed with `+/-` lines, trust score per file, test pass/fail, token usage
 
 Claude Code tool calls are logged to `~/.codehere/audit/hook-events.jsonl`; spawned-task lifecycle (any adapter) is logged to `~/.codehere/sessions.jsonl`. Open-source MIT. Node 20+.
@@ -138,7 +138,7 @@ For depth beyond this README:
 
 - **Node.js 20+** (pinned in `.nvmrc` and `engines.node`)
 - **macOS or Linux** · Windows via WSL works for development; native Windows is on the v0.4 roadmap
-- **Optional but recommended:** at least one supported agent (Claude Code, Codex, Aider, or OpenCode) installed before running `codehere start`
+- **Optional but recommended:** at least one supported agent (Claude Code, Codex, Aider, OpenCode, or Gemini) installed before running `codehere start`
 
 ## License
 

package/dist/infrastructure/orchestration/gemini-adapter.js

@@ -0,0 +1,389 @@
+/**
+ * Gemini adapter — F2 fifth concrete AgentAdapter (v0.4 sprint Track 1a).
+ *
+ * Wraps the official Google `gemini` CLI (`@google/gemini-cli`) as a subprocess.
+ * Headless mode: `gemini -p "<prompt>" -o stream-json --approval-mode=yolo`.
+ *
+ * Event schema verified against the installed gemini-cli source
+ * (StreamJsonFormatter / JsonStreamEventType in @google/gemini-cli bundle):
+ *   init         — { session_id, model, timestamp }
+ *   message      — { role: "user"|"assistant", content, delta?: bool }
+ *   tool_use     — { tool_name, tool_id, parameters }
+ *   tool_result  — tool execution output (best-effort parse — schema sparse)
+ *   error        — { error: {...} }
+ *   result       — { status: "success"|"error", stats?, error?: { type, message } }
+ *
+ * Token usage from result.stats: { total_tokens, input_tokens, output_tokens, cached }.
+ *
+ * Sandbox: Gemini's --approval-mode=yolo enables sandboxing by default. codehere is
+ * the external safety layer — its PreToolUse hook (F0) is where destructive-command
+ * scanning happens. We DISABLE Gemini's sandbox via GEMINI_SANDBOX=false so file
+ * writes / shell commands aren't blocked at the wrong layer. (Note: today's hook
+ * still only wraps Claude Code; for Gemini, codehere observes via session events
+ * and audits at task-completion. Per-tool blocking parity for non-Claude adapters
+ * is v0.4+ work — see project_v04_sprint.md Track 3.)
+ *
+ * Same structural pattern as ClaudeCodeAdapter / CodexAdapter / AiderAdapter:
+ * event buffer, late-joiner replay, SIGTERM→SIGKILL escalation, known-error
+ * fingerprints. Finalizes on `close` (not `exit`) so trailing stdout flushes.
+ * Kills the process group (negative pid) so subagents under gemini exit too.
+ */
+import { spawn, execFileSync } from 'child_process';
+import { EventEmitter } from 'events';
+import { randomUUID } from 'crypto';
+import { ProgressAggregator } from './progress-aggregator.js';
+import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
+// `--approval-mode=yolo` auto-accepts every tool action without prompting (the
+// older `--yolo` flag is deprecated). codehere's safety hook is the external
+// gate, so gemini-side prompts would block headless tasks.
+//
+// `-o stream-json` — JSONL events, one per line, schema verified above.
+//
+// `--skip-trust` — skip the per-workspace trust prompt that gemini shows on
+// first run in a new directory.
+const HEADLESS_FLAGS = [
+    '--approval-mode',
+    'yolo',
+    '--skip-trust',
+    '-o',
+    'stream-json',
+];
+// Error patterns scoped to STDERR / result.error / error events only — NOT
+// every JSON-serialized event (which would false-positive on tool output).
+const ERROR_PATTERNS = [
+    {
+        code: 'auth_missing',
+        regex: /please set an auth method|GEMINI_API_KEY|GOOGLE_API_KEY|GOOGLE_GENAI_USE_VERTEXAI|GOOGLE_GENAI_USE_GCA|GOOGLE_APPLICATION_CREDENTIALS/i,
+        message: 'Gemini auth missing.',
+        recovery: 'Set GEMINI_API_KEY env var (free tier at https://aistudio.google.com/apikey) — or configure Vertex AI / Application Default Credentials per https://google-gemini.github.io/gemini-cli/docs/get-started/authentication.html',
+    },
+    {
+        code: 'auth_invalid',
+        regex: /authentication\s+failed|401\s*unauth|invalid\s+api\s+key|api\s+key\s+not\s+valid/i,
+        message: 'Gemini API key is rejected.',
+        recovery: 'Verify GEMINI_API_KEY at https://aistudio.google.com/apikey and re-export.',
+    },
+    {
+        code: 'rate_limit',
+        regex: /rate.?limit(ed)?|HTTP\s*429|too many requests/i,
+        message: 'Gemini rate-limited the request.',
+        recovery: 'Wait a minute and retry, or check your Google AI Studio quota.',
+    },
+    {
+        code: 'quota_exceeded',
+        regex: /\bRESOURCE_EXHAUSTED\b|quota[\s_]exceeded|insufficient[_\s]quota/i,
+        message: 'Google AI Studio / Vertex quota exhausted.',
+        recovery: 'Check quota at https://aistudio.google.com/ or top up your Google Cloud billing account.',
+    },
+];
+function scanForKnownError(text) {
+    for (const p of ERROR_PATTERNS) {
+        if (p.regex.test(text))
+            return { code: p.code, message: p.message, recovery: p.recovery };
+    }
+    return null;
+}
+export function spawnGemini(prompt, options = {}) {
+    const sessionId = randomUUID();
+    const startedAt = Date.now();
+    const emitter = new EventEmitter();
+    const buffer = [];
+    let statusValue = 'running';
+    let killRequested = false;
+    const cwd = options.cwd ?? process.cwd();
+    const snapshot = snapshotCwd(cwd);
+    const aggregator = new ProgressAggregator('gemini');
+    let stepsSnapshot = [];
+    let artifactsSnapshot;
+    let textAccum = '';
+    let usageSnapshot;
+    let errorEmitted = false;
+    const emit = (event) => {
+        buffer.push(event);
+        emitter.emit('event', event);
+        if (aggregator.ingest(event)) {
+            stepsSnapshot = aggregator.steps.map((s) => ({ ...s }));
+            const snapEvt = {
+                type: 'codehere:steps',
+                timestamp: Date.now(),
+                data: { steps: stepsSnapshot },
+            };
+            buffer.push(snapEvt);
+            emitter.emit('event', snapEvt);
+        }
+        // Accumulate assistant text for the test-summary parser. Real schema:
+        // { type: 'message', role: 'assistant', content: '...', delta?: bool }.
+        // Both deltas (streaming chunks) and full messages contribute.
+        if (event.type === 'message') {
+            const data = event.data;
+            if (data?.role === 'assistant' && typeof data.content === 'string') {
+                textAccum += data.content;
+                // Only add a newline at non-delta boundaries to avoid breaking up streamed words
+                if (!event.data?.delta)
+                    textAccum += '\n';
+            }
+        }
+        // tool_result event — schema sparse in source; accept common output fields.
+        if (event.type === 'tool_result') {
+            const data = event.data;
+            const t = data?.output ?? data?.result ?? data?.content;
+            if (typeof t === 'string')
+                textAccum += t + '\n';
+        }
+        // Token usage comes ONLY in the final `result` event with status:'success',
+        // shape { stats: { input_tokens, output_tokens, total_tokens, cached } }.
+        if (event.type === 'result') {
+            const data = event.data;
+            if (data?.status === 'success' && data.stats) {
+                const s = data.stats;
+                usageSnapshot = {
+                    inputTokens: Number(s.input_tokens ?? 0),
+                    outputTokens: Number(s.output_tokens ?? 0),
+                    ...(s.cached ? { cacheReadTokens: Number(s.cached) } : {}),
+                };
+            }
+        }
+        // Scoped error matching: ONLY look at stderr lines and the FAILURE form of
+        // the `result` event (status:"error"). DO NOT scan `error` stream events
+        // because gemini's headless docs explicitly classify them as "Non-fatal
+        // warnings and system errors" — e.g. loop-detection warnings emit `error`
+        // events with severity:"warning". The terminal failure signal is the final
+        // `result` event with status:"error". Treating non-fatal `error` events as
+        // a terminal codehere:error would falsely mark successful sessions as failed.
+        if (!errorEmitted) {
+            let text = '';
+            const data = event.data;
+            if (event.type === 'stderr' && data && typeof data.line === 'string') {
+                text = data.line;
+            }
+            else if (event.type === 'result') {
+                const r = data;
+                if (r?.status === 'error' && r.error) {
+                    text = `${r.error.type ?? ''} ${r.error.message ?? ''}`;
+                }
+            }
+            if (text) {
+                const hit = scanForKnownError(text);
+                if (hit) {
+                    errorEmitted = true;
+                    const errEvent = {
+                        type: 'codehere:error',
+                        timestamp: Date.now(),
+                        data: { code: hit.code, message: hit.message, recovery: hit.recovery },
+                    };
+                    buffer.push(errEvent);
+                    emitter.emit('event', errEvent);
+                }
+            }
+        }
+    };
+    // Disable Gemini's built-in sandbox — codehere is the external safety layer.
+    // GEMINI_SANDBOX=false trumps any sandbox-on default that --approval-mode=yolo
+    // would otherwise enable. (Settings precedence: env > settings.json > default.)
+    const spawnEnv = {
+        ...process.env,
+        GEMINI_SANDBOX: 'false',
+        ...(options.env ?? {}),
+    };
+    let child;
+    try {
+        child = spawn('gemini', ['-p', prompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
+            cwd,
+            env: spawnEnv,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Detach into its own process group so kill() can reap subagents.
+            detached: true,
+        });
+        // Don't keep the parent alive on this child alone.
+        child.unref();
+    }
+    catch (err) {
+        statusValue = 'error';
+        const msg = err instanceof Error ? err.message : String(err);
+        queueMicrotask(() => emit({ type: 'error', timestamp: Date.now(), data: { message: msg } }));
+        return {
+            sessionId,
+            startedAt,
+            prompt,
+            agent: 'gemini',
+            get status() {
+                return statusValue;
+            },
+            get steps() {
+                return stepsSnapshot;
+            },
+            get artifacts() {
+                return artifactsSnapshot;
+            },
+            subscribe(handler) {
+                for (const e of buffer)
+                    handler(e);
+                emitter.on('event', handler);
+                return () => emitter.off('event', handler);
+            },
+            kill() {
+                /* already not running */
+            },
+        };
+    }
+    let stdoutBuf = '';
+    child.stdout?.on('data', (chunk) => {
+        stdoutBuf += chunk.toString('utf-8');
+        let idx;
+        while ((idx = stdoutBuf.indexOf('\n')) >= 0) {
+            const line = stdoutBuf.slice(0, idx).trim();
+            stdoutBuf = stdoutBuf.slice(idx + 1);
+            if (!line)
+                continue;
+            try {
+                const data = JSON.parse(line);
+                emit({ type: data.type ?? 'gemini_event', timestamp: Date.now(), data });
+            }
+            catch {
+                emit({ type: 'stdout', timestamp: Date.now(), data: { line } });
+            }
+        }
+    });
+    child.stderr?.on('data', (chunk) => {
+        const text = chunk.toString('utf-8');
+        for (const line of text.split('\n')) {
+            if (line.trim())
+                emit({ type: 'stderr', timestamp: Date.now(), data: { line } });
+        }
+    });
+    // Use `close` (after all stdio has drained), not `exit` (which can fire while
+    // unread stdout is still in-flight). Flush any final un-newlined buffered line.
+    child.on('close', (code, signal) => {
+        if (stdoutBuf.trim()) {
+            const line = stdoutBuf.trim();
+            stdoutBuf = '';
+            try {
+                const data = JSON.parse(line);
+                emit({ type: data.type ?? 'gemini_event', timestamp: Date.now(), data });
+            }
+            catch {
+                emit({ type: 'stdout', timestamp: Date.now(), data: { line } });
+            }
+        }
+        statusValue =
+            killRequested || signal !== null
+                ? 'killed'
+                : errorEmitted
+                    ? 'error'
+                    : code === 0
+                        ? 'completed'
+                        : 'error';
+        if (aggregator.finalize(statusValue === 'completed' ? 'completed' : statusValue === 'killed' ? 'killed' : 'error')) {
+            stepsSnapshot = aggregator.steps.map((s) => ({ ...s }));
+            emit({ type: 'codehere:steps', timestamp: Date.now(), data: { steps: stepsSnapshot } });
+        }
+        if (statusValue === 'completed') {
+            try {
+                artifactsSnapshot = { ...extractArtifacts(snapshot, textAccum), usage: usageSnapshot };
+                emit({ type: 'codehere:artifacts', timestamp: Date.now(), data: artifactsSnapshot });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        emit({
+            type: 'exit',
+            timestamp: Date.now(),
+            data: { code, signal, status: statusValue, durationMs: Date.now() - startedAt },
+        });
+    });
+    child.on('error', (err) => {
+        statusValue = 'error';
+        emit({ type: 'error', timestamp: Date.now(), data: { message: err.message } });
+    });
+    return {
+        sessionId,
+        startedAt,
+        prompt,
+        agent: 'gemini',
+        get status() {
+            return statusValue;
+        },
+        get steps() {
+            return stepsSnapshot;
+        },
+        get artifacts() {
+            return artifactsSnapshot;
+        },
+        subscribe(handler) {
+            for (const e of buffer)
+                handler(e);
+            emitter.on('event', handler);
+            return () => emitter.off('event', handler);
+        },
+        kill() {
+            if (statusValue !== 'running')
+                return;
+            killRequested = true;
+            // Process-group kill via negative pid is POSIX-only — Node on Windows
+            // throws ESRCH for that. Fall back to direct child.kill on Windows.
+            const isPosix = process.platform !== 'win32';
+            const sendSignal = (sig) => {
+                if (isPosix && child.pid) {
+                    try {
+                        process.kill(-child.pid, sig);
+                        return;
+                    }
+                    catch {
+                        /* fall through to child.kill */
+                    }
+                }
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* already dead */
+                }
+            };
+            sendSignal('SIGTERM');
+            setTimeout(() => {
+                if (statusValue === 'running')
+                    sendSignal('SIGKILL');
+            }, 3000);
+        },
+    };
+}
+export const GeminiAdapter = {
+    id: 'gemini',
+    label: 'Gemini',
+    // Match `gemini`, `node /path/.../gemini`, and `./gemini` invocations.
+    processPattern: /(?:^|\/)gemini(?:\s|$)|node\s+\S*gemini/,
+    isInstalled() {
+        try {
+            const out = execFileSync('which', ['gemini'], { encoding: 'utf-8', timeout: 2000 });
+            return out.trim().length > 0;
+        }
+        catch {
+            return false;
+        }
+    },
+    spawn(prompt, options) {
+        return spawnGemini(prompt, options);
+    },
+    checkReadiness() {
+        const installed = this.isInstalled();
+        if (!installed) {
+            return {
+                id: this.id,
+                label: this.label,
+                state: 'needs_install',
+                installed: false,
+                installHint: {
+                    command: 'npm install -g @google/gemini-cli',
+                    url: 'https://github.com/google-gemini/gemini-cli',
+                },
+            };
+        }
+        // Gemini supports GEMINI_API_KEY (free tier at aistudio.google.com), GOOGLE_API_KEY,
+        // Vertex AI (GOOGLE_GENAI_USE_VERTEXAI=true), GCA (GOOGLE_GENAI_USE_GCA=true), or
+        // cached Google login. Can't verify without a roundtrip — let runtime catch
+        // real failures via ERROR_PATTERNS.auth_missing on the result.error event.
+        return { id: this.id, label: this.label, state: 'ready', installed: true };
+    },
+};
+//# sourceMappingURL=gemini-adapter.js.map

package/dist/infrastructure/orchestration/progress-aggregator.js

@@ -99,6 +99,8 @@ export class ProgressAggregator {
             return this.ingestClaude(type, data);
         if (this.agentId === 'codex')
             return this.ingestCodex(type, data);
+        if (this.agentId === 'gemini')
+            return this.ingestGemini(type, data);
         return false;
     }
     /** Flush: mark every still-active step as failed (called on abnormal exit). */
@@ -157,6 +159,42 @@ export class ProgressAggregator {
         }
         return false;
     }
+    /**
+     * Gemini's stream-json schema (verified against @google/gemini-cli source):
+     *   tool_use:    { tool_name, tool_id, parameters }       — adds an active step
+     *   tool_result: { tool_id, ...output }                   — closes by tool_id
+     *
+     * We reuse the Claude-shaped tool labelling as a best-effort default — Gemini's
+     * tool surface (Read, Edit, Write, Shell, Grep, Glob, etc.) overlaps heavily
+     * with the Claude SDK tool naming since both emerged from the same agent
+     * lineage. If a specific Gemini tool name doesn't match, the default branch in
+     * `labelForClaudeToolUse` falls back to the raw tool name.
+     */
+    ingestGemini(type, data) {
+        if (type === 'tool_use') {
+            const id = String(data.tool_id ?? '');
+            const name = String(data.tool_name ?? 'tool');
+            const label = labelForClaudeToolUse(name, data.parameters);
+            const idx = this.addStep(label, 'active');
+            if (id)
+                this.toolUseIndex.set(id, idx);
+            return true;
+        }
+        if (type === 'tool_result') {
+            const id = String(data.tool_id ?? '');
+            const idx = id ? this.toolUseIndex.get(id) : undefined;
+            if (idx !== undefined) {
+                const step = this._steps[idx];
+                // Gemini's tool_result may carry an `error` field on failure; treat any
+                // non-undefined `error` as failed. Otherwise mark done.
+                const isError = data.error !== undefined && data.error !== null;
+                step.state = isError ? 'failed' : 'done';
+                step.completedAt = Date.now();
+                return true;
+            }
+        }
+        return false;
+    }
     ingestCodex(type, data) {
         if (type !== 'item.completed')
             return false;

package/dist/infrastructure/orchestration/session-manager.js

@@ -17,6 +17,7 @@ import { ClaudeCodeAdapter } from './claude-code-adapter.js';
 import { CodexAdapter } from './codex-adapter.js';
 import { AiderAdapter } from './aider-adapter.js';
 import { OpenCodeAdapter } from './opencode-adapter.js';
+import { GeminiAdapter } from './gemini-adapter.js';
 import { buildGenericAdapter, loadAgentsConfig } from './generic-cli-adapter.js';
 import { buildConductorAdapter } from './conductor-adapter.js';
 import { seedAgentsConfig } from './agents-config-seed.js';
@@ -27,7 +28,7 @@ import { appendSpawned, appendCompleted, loadRecent } from './session-persistenc
 // order. Built-in adapters first; user-config-driven ones appended from
 // ~/.codehere/agents.yaml (generic-cli-adapter). isInstalled() gates visibility
 // so an adapter registering for an un-installed CLI is harmless.
-const BUILTIN_REGISTRY = [ClaudeCodeAdapter, CodexAdapter, AiderAdapter, OpenCodeAdapter];
+const BUILTIN_REGISTRY = [ClaudeCodeAdapter, CodexAdapter, AiderAdapter, OpenCodeAdapter, GeminiAdapter];
 // Seed the default agents.yaml if this user has never configured one, so Gemini
 // / Cursor / Pi / Antigravity / Goose appear in the registry pre-wired. They
 // stay hidden in the UI until isInstalled() flips to true. Idempotent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "A PM for your AI coding agents. Delegate, orchestrate, and audit Claude Code, Codex, Aider, and OpenCode from one local web UI — every AI action traced, every file scored.",
   "main": "dist/index.js",
   "type": "module",