@hover-dev/core 0.2.1 → 0.2.3

package/README.md

@@ -43,7 +43,7 @@ pnpm smoke http://localhost:5173/ "log in then add a todo named 'verify hover'"
 Environment variables:
 
 - `HOVER_CDP` — CDP URL (default `http://localhost:9222`)
-- `HOVER_AGENT` — agent id (default `claude`)
+- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` today)
 - `HOVER_MODEL` — model for the agent (default `sonnet`, much cheaper than opus)
 
 ## Sandboxing (what the smoke test enforces)

package/dist/agents/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,YAAY,CAAC;AA2E9E,eAAO,MAAM,WAAW,EAAE,eA4GzB,CAAC"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA2C,MAAM,YAAY,CAAC;AAsF3F,eAAO,MAAM,WAAW,EAAE,eAoHzB,CAAC"}

package/dist/agents/claude.js

@@ -30,20 +30,27 @@ function estimateCostUsd(modelHint, usage) {
         (usage.cache_creation_input_tokens ?? 0) * tier.cacheCreate +
         (usage.cache_read_input_tokens ?? 0) * tier.cacheRead) / 1_000_000;
 }
-/**
- * Per-session running totals. Reset on every `system/init` event (one per
- * agent invocation). Safe as module-level state because service.ts enforces
- * one in-flight invocation per Hover service via its `busy` lock, and each
- * Vite dev server spawns its own Node process with its own module instance.
- */
-let runningCost = 0;
-let runningTurns = 0;
-let runningModel;
+function claudeState(state) {
+    // First touch on this state object — seed the keys we read below.
+    if (typeof state.runningCost !== 'number') {
+        state.runningCost = 0;
+        state.runningTurns = 0;
+        state.runningModel = undefined;
+    }
+    return state;
+}
 export const claudeAgent = {
     id: 'claude',
     binName: 'claude',
     protocol: 'argv',
     streamFormat: 'stream-json',
+    sandboxStrength: 'hard',
+    display: {
+        label: 'Claude Code',
+        tagline: 'Anthropic — best-in-class browser driving, hard tool sandbox',
+        homepage: 'https://docs.claude.com/claude-code',
+        installHint: 'npm install -g @anthropic-ai/claude-code',
+    },
     buildArgs(opts) {
         const args = ['-p', opts.prompt];
         args.push('--output-format', 'stream-json', '--verbose');
@@ -71,7 +78,7 @@ export const claudeAgent = {
         }
         return args;
     },
-    parseEvent(line) {
+    parseEvent(line, state = {}) {
         if (!line.trim())
             return [];
         let ev;
@@ -81,12 +88,13 @@ export const claudeAgent = {
         catch {
             return [{ kind: 'raw', line }];
         }
+        const s = claudeState(state);
         const out = [];
         if (ev.type === 'system' && ev.subtype === 'init') {
             // Fresh session — reset the cost/turn accumulator.
-            runningCost = 0;
-            runningTurns = 0;
-            runningModel = ev.model;
+            s.runningCost = 0;
+            s.runningTurns = 0;
+            s.runningModel = ev.model;
             if (ev.session_id) {
                 out.push({ kind: 'session_start', sessionId: ev.session_id, model: ev.model });
             }
@@ -96,18 +104,18 @@ export const claudeAgent = {
             return out;
         }
         if (ev.type === 'assistant') {
-            runningTurns += 1;
+            s.runningTurns += 1;
             // Claude Code sometimes carries `total_cost_usd` on intermediate events;
             // when present it's authoritative (server-computed, includes anything
             // we'd miss). When absent, estimate from this turn's usage so the widget
             // still shows a growing $ counter on long runs.
             if (typeof ev.total_cost_usd === 'number') {
-                runningCost = ev.total_cost_usd;
+                s.runningCost = ev.total_cost_usd;
             }
             else if (ev.message?.usage) {
-                runningCost += estimateCostUsd(runningModel ?? ev.message.model, ev.message.usage);
+                s.runningCost += estimateCostUsd(s.runningModel ?? ev.message.model, ev.message.usage);
             }
-            out.push({ kind: 'usage', costUsd: runningCost, turns: runningTurns });
+            out.push({ kind: 'usage', costUsd: s.runningCost, turns: s.runningTurns });
             for (const block of ev.message?.content ?? []) {
                 if (block.type === 'tool_use') {
                     const name = block.name ?? '';

package/dist/agents/codex.d.ts

@@ -0,0 +1,19 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const codexAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches. Tests pass a state object in and get the
+ * accumulated counters back — same shape as the parser sees during a real
+ * invocation, just driven by the test instead of by invokeAgent.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningCost: number;
+        runningTurns: number;
+        runningSessionId: string | undefined;
+        lastAgentMessage: string | undefined;
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=codex.d.ts.map

package/dist/agents/codex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AAmK3F,eAAO,MAAM,UAAU,EAAE,eAyJxB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}

package/dist/agents/codex.js

@@ -0,0 +1,210 @@
+/**
+ * Pricing per million tokens. Keep in lockstep with claude.ts's table —
+ * approximate published OpenAI rates as of 2026. We are deliberately
+ * conservative (no cache-hit discount); cost shown to the user is therefore
+ * a high-water estimate, which is the right error direction for a "should
+ * I hit Stop now" UI signal.
+ */
+const PRICE_PER_M_USD = {
+    // gpt-5.5 / gpt-5.4 / gpt-5 — public per-million pricing is similar to
+    // claude opus; tune empirically when OpenAI publishes a stable price table
+    // for the Codex tier specifically.
+    'gpt-5.5': { in: 5, out: 25 },
+    'gpt-5.4': { in: 5, out: 25 },
+    'gpt-5': { in: 5, out: 25 },
+    // gpt-4.x kept for users on legacy --model
+    'gpt-4o': { in: 2.5, out: 10 },
+    'gpt-4': { in: 30, out: 60 },
+};
+function estimateCostUsd(modelHint, usage) {
+    const m = (modelHint ?? 'gpt-5.5').toLowerCase();
+    // Match by longest-prefix so 'gpt-5.5-mini' picks up the 'gpt-5.5' tier.
+    const tier = Object.entries(PRICE_PER_M_USD).find(([key]) => m.startsWith(key))?.[1] ??
+        PRICE_PER_M_USD['gpt-5.5'];
+    return ((usage.input_tokens ?? 0) * tier.in +
+        (usage.output_tokens ?? 0) * tier.out) / 1_000_000;
+}
+function codexState(state) {
+    if (typeof state.runningCost !== 'number') {
+        state.runningCost = 0;
+        state.runningTurns = 0;
+        state.runningModel = undefined;
+        state.runningSessionId = undefined;
+        state.lastAgentMessage = undefined;
+        state.sawErrorEvent = false;
+        state.itemTypeById = new Map();
+    }
+    return state;
+}
+function resetCodexCounters(s) {
+    s.runningCost = 0;
+    s.runningTurns = 0;
+    s.runningModel = undefined;
+    s.runningSessionId = undefined;
+    s.lastAgentMessage = undefined;
+    s.sawErrorEvent = false;
+    s.itemTypeById.clear();
+}
+/** Cap surfaced as a constraint in the system prompt — codex has no CLI flag. */
+const CODEX_DEVELOPER_INSTRUCTIONS = [
+    'You are operating in Hover, a browser-testing tool.',
+    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
+    'Do NOT call shell, file-edit, web-search, or any other built-in tool.',
+    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
+    'When the task is complete, emit a short agent_message summary and stop.',
+].join(' ');
+export const codexAgent = {
+    id: 'codex',
+    binName: 'codex',
+    protocol: 'argv',
+    streamFormat: 'json-lines',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'OpenAI Codex',
+        tagline: 'OpenAI — soft sandbox (no built-in tool deny-list)',
+        homepage: 'https://developers.openai.com/codex',
+        installHint: 'npm install -g @openai/codex',
+    },
+    buildArgs(opts) {
+        const args = ['exec'];
+        // Resume must come BEFORE the prompt positional. `codex exec resume <id>
+        // [prompt]` is the documented shape.
+        if (opts.sessionId) {
+            args.push('resume', opts.sessionId);
+        }
+        args.push(opts.prompt);
+        // JSONL streaming output.
+        args.push('--json');
+        // Never prompt for approval in headless mode.
+        args.push('--ask-for-approval', 'never');
+        // Soft sandbox: prevent shell side-effects on disk / network even when
+        // the agent tries to call its built-in shell. read-only is the strictest
+        // documented level.
+        args.push('--sandbox', 'read-only');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        // System-prompt injection. Codex has no --append-system-prompt; we route
+        // through `-c developer_instructions='...'`. Concatenate the standing
+        // Hover-mode instructions with whatever the caller passes (e.g. "user is
+        // already on http://localhost:5173/").
+        const sysPrompt = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${CODEX_DEVELOPER_INSTRUCTIONS} ${opts.appendSystemPrompt}`
+            : CODEX_DEVELOPER_INSTRUCTIONS;
+        args.push('-c', `developer_instructions=${JSON.stringify(sysPrompt)}`);
+        // MCP servers are configured in ~/.codex/config.toml at install time,
+        // not per-invocation. If the user passed an mcpConfig path, we don't
+        // have a way to forward it to codex — log a warning to stderr from the
+        // invoker so the user knows. (See invoke.ts wiring.)
+        // No equivalent for --max-budget-usd or --allowedTools.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        if (!line.trim())
+            return [];
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            return [{ kind: 'raw', line }];
+        }
+        const s = codexState(state);
+        const out = [];
+        if (ev.type === 'thread.started') {
+            resetCodexCounters(s);
+            if (ev.thread_id) {
+                s.runningSessionId = ev.thread_id;
+                out.push({ kind: 'session_start', sessionId: ev.thread_id, model: ev.model });
+            }
+            return out;
+        }
+        if (ev.type === 'item.started' && ev.item) {
+            const it = ev.item;
+            if (it.id && it.type)
+                s.itemTypeById.set(it.id, it.type);
+            if (it.type === 'mcp_tool_call') {
+                // The exact field names aren't published. Read defensively: prefer
+                // `name`, fall back to `tool`. Same for input.
+                const rawName = it.name ?? it.tool ?? '';
+                const tool = rawName.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
+                out.push({ kind: 'tool_use', tool, input: it.input ?? it.arguments });
+            }
+            else if (it.type === 'command_execution') {
+                // We DISCOURAGED this in developer_instructions but the agent can
+                // still try. Surface it so the user sees it happen.
+                out.push({ kind: 'tool_use', tool: 'shell', input: { command: it.command } });
+            }
+            return out;
+        }
+        if (ev.type === 'item.completed' && ev.item) {
+            const it = ev.item;
+            const recordedType = (it.id && s.itemTypeById.get(it.id)) || it.type;
+            if (recordedType === 'agent_message') {
+                const text = it.text?.trim();
+                if (text) {
+                    s.lastAgentMessage = text;
+                    out.push({ kind: 'text', text });
+                }
+            }
+            else if (recordedType === 'mcp_tool_call' || recordedType === 'command_execution') {
+                const isError = it.is_error === true ||
+                    (typeof it.status === 'string' && /error|fail/i.test(it.status));
+                out.push({ kind: 'tool_result', isError });
+            }
+            return out;
+        }
+        if (ev.type === 'turn.completed') {
+            s.runningTurns += 1;
+            if (ev.usage) {
+                s.runningCost += estimateCostUsd(s.runningModel, ev.usage);
+            }
+            out.push({ kind: 'usage', costUsd: s.runningCost, turns: s.runningTurns });
+            return out;
+        }
+        // Codex emits various error envelopes; we conservatively match anything
+        // whose `type` contains 'error' or carries a top-level message string.
+        if (ev.type && /error/i.test(ev.type)) {
+            s.sawErrorEvent = true;
+            if (ev.message) {
+                out.push({ kind: 'text', text: `[codex] ${ev.message}` });
+            }
+            return out;
+        }
+        return [];
+    },
+    /**
+     * Codex doesn't emit a `session_end` line — the child process simply
+     * exits after the final `turn.completed`. We synthesize the terminator
+     * here so the widget sees the same shape it sees from claude.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = codexState(state);
+        return {
+            kind: 'session_end',
+            turns: s.runningTurns,
+            costUsd: s.runningCost,
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: s.lastAgentMessage,
+        };
+    },
+};
+/**
+ * Test-only escape hatches. Tests pass a state object in and get the
+ * accumulated counters back — same shape as the parser sees during a real
+ * invocation, just driven by the test instead of by invokeAgent.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetCodexCounters(codexState(state)),
+    getState: (state) => {
+        const s = codexState(state);
+        return {
+            runningCost: s.runningCost,
+            runningTurns: s.runningTurns,
+            runningSessionId: s.runningSessionId,
+            lastAgentMessage: s.lastAgentMessage,
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/detect.d.ts

@@ -10,7 +10,33 @@ export interface DetectedAgent {
     binPath: string;
 }
 /**
- * Scan PATH for every agent in the registry. Returns only the ones found.
+ * Scan PATH for every agent in the registry. Returns only the ones found,
+ * in registry insertion order.
  */
 export declare function detectAgents(): Promise<DetectedAgent[]>;
+export interface AgentAvailability {
+    id: string;
+    label: string;
+    tagline?: string;
+    sandboxStrength: 'hard' | 'soft';
+    installed: boolean;
+    binPath?: string;
+    homepage?: string;
+    installHint?: string;
+}
+/**
+ * Like `detectAgents`, but also includes registered-but-not-installed agents
+ * so the widget can render them dimmed with an install hint. Order matches
+ * the registry.
+ */
+export declare function listAgentAvailability(): Promise<AgentAvailability[]>;
+/**
+ * Pick the agent we should default to when the user / Vite plugin didn't
+ * specify one. Prefer the explicit hint if it's installed; otherwise the
+ * first registered agent that's installed; finally null if nothing matches.
+ *
+ * `preferredId` is typically `process.env.HOVER_AGENT` or the value the user
+ * picked in the widget last session (persisted by the widget to localStorage).
+ */
+export declare function pickPrimaryAgent(preferredId?: string): Promise<DetectedAgent | null>;
 //# sourceMappingURL=detect.d.ts.map

package/dist/agents/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/agents/detect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAS3E;AAED,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE5F;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAO7D"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/agents/detect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAS3E;AAED,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE5F;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAO7D;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAgB1E;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAU1F"}

package/dist/agents/detect.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { AGENTS } from './registry.js';
+import { AGENTS, listAgents } from './registry.js';
 const execFileAsync = promisify(execFile);
 /**
  * Find a binary on PATH. Returns absolute path or null.
@@ -21,14 +21,57 @@ export async function resolveBinForAgent(descriptor) {
     return resolveOnPath(descriptor.binName);
 }
 /**
- * Scan PATH for every agent in the registry. Returns only the ones found.
+ * Scan PATH for every agent in the registry. Returns only the ones found,
+ * in registry insertion order.
  */
 export async function detectAgents() {
     const detected = [];
-    for (const descriptor of Object.values(AGENTS)) {
+    for (const descriptor of listAgents()) {
         const binPath = await resolveBinForAgent(descriptor);
         if (binPath)
             detected.push({ descriptor, binPath });
     }
     return detected;
 }
+/**
+ * Like `detectAgents`, but also includes registered-but-not-installed agents
+ * so the widget can render them dimmed with an install hint. Order matches
+ * the registry.
+ */
+export async function listAgentAvailability() {
+    const result = [];
+    for (const descriptor of listAgents()) {
+        const binPath = await resolveBinForAgent(descriptor);
+        result.push({
+            id: descriptor.id,
+            label: descriptor.display.label,
+            tagline: descriptor.display.tagline,
+            sandboxStrength: descriptor.sandboxStrength,
+            installed: binPath != null,
+            binPath: binPath ?? undefined,
+            homepage: descriptor.display.homepage,
+            installHint: descriptor.display.installHint,
+        });
+    }
+    return result;
+}
+/**
+ * Pick the agent we should default to when the user / Vite plugin didn't
+ * specify one. Prefer the explicit hint if it's installed; otherwise the
+ * first registered agent that's installed; finally null if nothing matches.
+ *
+ * `preferredId` is typically `process.env.HOVER_AGENT` or the value the user
+ * picked in the widget last session (persisted by the widget to localStorage).
+ */
+export async function pickPrimaryAgent(preferredId) {
+    if (preferredId) {
+        const descriptor = AGENTS[preferredId];
+        if (descriptor) {
+            const binPath = await resolveBinForAgent(descriptor);
+            if (binPath)
+                return { descriptor, binPath };
+        }
+    }
+    const detected = await detectAgents();
+    return detected[0] ?? null;
+}

package/dist/agents/invoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/agents/invoke.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;GAMG;AACH,wBAAuB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,WAAW,CAAC,CAwDlF"}
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/agents/invoke.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAuB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,WAAW,CAAC,CAuElF"}

package/dist/agents/invoke.js

@@ -50,9 +50,13 @@ export async function* invokeAgent(opts) {
     }
     const rl = createInterface({ input: child.stdout });
     const exitPromise = new Promise(res => child.on('exit', c => res(c ?? -1)));
+    // Fresh parser state per invocation. Threaded into both parseEvent and
+    // onStreamEnd so descriptors don't have to reach for module globals
+    // (which would smear across concurrent invocations).
+    const state = {};
     let sawSessionEnd = false;
     for await (const line of rl) {
-        for (const ev of descriptor.parseEvent(line)) {
+        for (const ev of descriptor.parseEvent(line, state)) {
             if (ev.kind === 'session_end')
                 sawSessionEnd = true;
             yield ev;
@@ -60,11 +64,21 @@ export async function* invokeAgent(opts) {
     }
     const code = await exitPromise;
     opts.signal?.removeEventListener('abort', onAbort);
-    if (!sawSessionEnd && code !== 0 && !opts.signal?.aborted) {
-        yield {
-            kind: 'session_end',
-            isError: true,
-            summary: `agent exited with code ${code}`,
-        };
+    if (!sawSessionEnd && !opts.signal?.aborted) {
+        // Give the descriptor a chance to synthesize its own terminator from
+        // accumulated state (codex does this — its stream never emits a
+        // session_end). Falls back to a generic error session_end if the
+        // descriptor declines and the child exited non-zero.
+        const synthetic = descriptor.onStreamEnd?.(code, state);
+        if (synthetic) {
+            yield synthetic;
+        }
+        else if (code !== 0) {
+            yield {
+                kind: 'session_end',
+                isError: true,
+                summary: `agent exited with code ${code}`,
+            };
+        }
     }
 }

package/dist/agents/registry.d.ts

@@ -1,12 +1,17 @@
 import type { AgentDescriptor } from './types.js';
 /**
- * Registry of agents Hover can drive. Currently only `claude` is fully wired.
+ * Registry of agents Hover can drive.
  *
- * To add support for another agent (e.g. codex, cursor-agent, aider, gemini,
- * cline, continue, qwen, kilo), implement its AgentDescriptor in its own
- * file and register it here. The rest of the system — detect, argv, invoke,
- * smoke — works without further changes.
+ * To add support for another agent (e.g. cursor-agent, aider, gemini, cline,
+ * continue, qwen, kilo), implement its AgentDescriptor in its own file and
+ * register it here. The rest of the system — detect, argv, invoke, service,
+ * widget — works without further changes.
+ *
+ * Insertion order is the order shown in the widget's agent dropdown, so put
+ * the recommended primary first.
  */
 export declare const AGENTS: Record<string, AgentDescriptor>;
 export declare function getAgent(id: string): AgentDescriptor | undefined;
+/** Stable, insertion-ordered list of all registered agents. */
+export declare function listAgents(): AgentDescriptor[];
 //# sourceMappingURL=registry.d.ts.map

package/dist/agents/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAElD,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAGlD,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,eAAe,EAAE,CAE9C"}

package/dist/agents/registry.js

@@ -1,15 +1,24 @@
 import { claudeAgent } from './claude.js';
+import { codexAgent } from './codex.js';
 /**
- * Registry of agents Hover can drive. Currently only `claude` is fully wired.
+ * Registry of agents Hover can drive.
  *
- * To add support for another agent (e.g. codex, cursor-agent, aider, gemini,
- * cline, continue, qwen, kilo), implement its AgentDescriptor in its own
- * file and register it here. The rest of the system — detect, argv, invoke,
- * smoke — works without further changes.
+ * To add support for another agent (e.g. cursor-agent, aider, gemini, cline,
+ * continue, qwen, kilo), implement its AgentDescriptor in its own file and
+ * register it here. The rest of the system — detect, argv, invoke, service,
+ * widget — works without further changes.
+ *
+ * Insertion order is the order shown in the widget's agent dropdown, so put
+ * the recommended primary first.
  */
 export const AGENTS = {
     [claudeAgent.id]: claudeAgent,
+    [codexAgent.id]: codexAgent,
 };
 export function getAgent(id) {
     return AGENTS[id];
 }
+/** Stable, insertion-ordered list of all registered agents. */
+export function listAgents() {
+    return Object.values(AGENTS);
+}

package/dist/agents/types.d.ts

@@ -77,12 +77,82 @@ export type InvokeEvent = {
     kind: 'raw';
     line: string;
 };
+/**
+ * How tightly the agent's tool surface can be locked down per invocation.
+ *
+ *   'hard' — the agent CLI accepts a deny-list / allow-list that effectively
+ *            removes built-in tools (shell, file edit, etc.) so the only
+ *            callable surface is whatever MCP servers we configure. Claude
+ *            Code's `--strict-mcp-config` + `--allowedTools mcp__playwright`
+ *            + `--disallowedTools <every built-in>` is the canonical example.
+ *
+ *   'soft' — the agent CLI does not expose a way to disable its built-in
+ *            tools (shell, fs). We can constrain side-effects via OS-level
+ *            sandbox flags (e.g. codex's `--sandbox read-only`) and we lean
+ *            on a strict `developer_instructions` system-prompt to nudge the
+ *            agent toward MCP-only behavior, but a determined / hallucinating
+ *            agent COULD still try a built-in shell call. The widget should
+ *            mark this agent with a warning indicator.
+ */
+export type SandboxStrength = 'hard' | 'soft';
+/**
+ * Human-facing metadata for the widget's agent picker. None of these affect
+ * agent invocation — they only shape how the agent is presented in the UI.
+ */
+export interface AgentDisplay {
+    /** Pretty name for the dropdown ("Claude Code", "OpenAI Codex"). */
+    label: string;
+    /** One-line tagline shown under the label. */
+    tagline?: string;
+    /** Vendor / source URL — clicking the agent name in the widget can open
+     *  this in a new tab when the agent isn't installed. */
+    homepage?: string;
+    /** Shell command the user can run to install (copy-paste from a tooltip
+     *  in the widget when the agent is listed but not on PATH). */
+    installHint?: string;
+}
+/**
+ * Per-invocation parser state. A fresh object is created by `invokeAgent`
+ * for each spawn and passed to both `parseEvent` and `onStreamEnd`.
+ *
+ * Descriptors that need to accumulate state across lines (cost, turn count,
+ * last agent message for synthesized session_end, etc.) read and write
+ * their own keys on this object. There is no shared shape — each agent
+ * uses whatever fields it needs.
+ *
+ * Why: module-level state in claude.ts / codex.ts worked only because the
+ * service enforces one in-flight invocation per Node process. Two concurrent
+ * agent runs (future: tests in parallel, in-process workers) would silently
+ * smear their cost accumulators together. Threading the state object per
+ * invocation removes that hazard at zero runtime cost.
+ */
+export type ParserState = Record<string, unknown>;
 export interface AgentDescriptor {
     id: string;
     binName: string;
     protocol: AgentProtocol;
     streamFormat: StreamFormat;
+    sandboxStrength: SandboxStrength;
+    display: AgentDisplay;
     buildArgs(opts: InvokeOptions): string[];
-    parseEvent(line: string): InvokeEvent[];
+    /**
+     * Parse a single line of agent stdout into normalised InvokeEvents.
+     * `state` is a per-invocation scratch pad (see ParserState). Optional
+     * for callers that don't accumulate across lines (and for unit tests
+     * that don't care about cost / turn carry-over) — descriptors that
+     * DO accumulate must check / initialise the state object themselves.
+     */
+    parseEvent(line: string, state?: ParserState): InvokeEvent[];
+    /**
+     * Optional. Called once after the agent's stream closes, with the child's
+     * exit code (or null if it was aborted). Lets agents whose protocol does
+     * NOT emit an explicit session-terminating event synthesize one from
+     * accumulated parser state. Returns `null` if the agent's own `parseEvent`
+     * already emitted a `session_end` and nothing further is needed.
+     *
+     * Used by codex.ts (no native session_end). Claude does not implement
+     * this — `result` events terminate naturally.
+     */
+    onStreamEnd?(exitCode: number | null, state?: ParserState): InvokeEvent | null;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,OAAO,GACP,KAAK,GACL,QAAQ,CAAC;AAEb,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,KAAK,GACL,YAAY,GACZ,YAAY,CAAC;AAEjB,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAI5C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;yCAGqC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;6EACyE;IACzE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChC;;;qEAGqE;GACnE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9F;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAAC;IACzC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CACzC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}