@hover-dev/core 0.8.0 → 0.10.0

package/README.md

@@ -17,7 +17,9 @@ The local Node service. Owns:
 | `detect.ts` | `detectAgents()`, `resolveBinForAgent()`, `resolveOnPath()` — PATH scanning |
 | `argv.ts` | `buildArgv()` — protocol-aware argv construction, throws `UnsupportedAgentProtocolError` for `acp` / `pi-rpc` |
 | `invoke.ts` | `invokeAgent()` — async-iterable spawning + stdout streaming |
-| `claude.ts` | Claude Code descriptor: `claude -p`, stream-json parser, sandbox flags |
+| `claude.ts` | Claude Code descriptor: `claude -p`, stream-json parser, hard sandbox flags |
+| `codex.ts` | OpenAI Codex CLI descriptor: `codex exec --json`, JSONL parser, soft sandbox (`--sandbox read-only`) |
+| `cursor.ts` | Cursor CLI descriptor (v0.9): stream-JSON / NDJSON parser, soft sandbox |
 
 To add an agent: implement an `AgentDescriptor`, register it in `registry.ts`. Done.
 
@@ -43,7 +45,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 (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` today)
+- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` → `cursor-agent` today)
 - `HOVER_MODEL` — model for the agent (default `sonnet`, much cheaper than opus)
 
 ## Sandboxing (what the smoke test enforces)

package/dist/agents/aider.d.ts

@@ -0,0 +1,16 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const aiderAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningLines: number;
+        runningSessionId: string | undefined;
+        collectedText: string[];
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=aider.d.ts.map

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

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

package/dist/agents/aider.js

@@ -0,0 +1,169 @@
+function aiderState(state) {
+    if (typeof state.runningLines !== 'number') {
+        state.runningLines = 0;
+        state.collectedText = [];
+        state.sawErrorEvent = false;
+        state.runningSessionId = undefined;
+    }
+    return state;
+}
+function resetAiderCounters(s) {
+    s.runningLines = 0;
+    s.collectedText = [];
+    s.sawErrorEvent = false;
+    s.runningSessionId = undefined;
+}
+/**
+ * Aider has no system-prompt flag, so we prepend this preface to the user
+ * prompt (same approach as cursor.ts). The agent treats it as the leading
+ * user-message text.
+ */
+const AIDER_PROMPT_PREFACE = [
+    '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 use 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 summary and stop.',
+].join(' ');
+/**
+ * Lines we treat as noise and drop instead of surfacing as text events.
+ * Aider chatters with status lines that would clutter the widget panel.
+ * Conservative list — anything we don't explicitly skip falls through.
+ */
+function isNoiseLine(line) {
+    const t = line.trim();
+    if (!t)
+        return true;
+    // Common aider boilerplate / banner lines.
+    if (/^Aider v\d/i.test(t))
+        return true;
+    if (/^Main model:/i.test(t))
+        return true;
+    if (/^Weak model:/i.test(t))
+        return true;
+    if (/^Git repo:/i.test(t))
+        return true;
+    if (/^Repo-map:/i.test(t))
+        return true;
+    if (/^VSCode terminal detected/i.test(t))
+        return true;
+    if (/^Use \/help/i.test(t))
+        return true;
+    if (/^Tokens:.*sent.*received/i.test(t))
+        return true;
+    if (/^─{3,}$/.test(t))
+        return true; // horizontal rule
+    return false;
+}
+function detectErrorLine(line) {
+    // Aider prints errors / API failures with a leading marker.
+    return /^(error|fatal|api error|litellm.*error)/i.test(line.trim());
+}
+export const aiderAgent = {
+    id: 'aider',
+    binName: 'aider',
+    protocol: 'argv',
+    streamFormat: 'plain-text',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'Aider',
+        tagline: 'Aider — soft sandbox, plain-text stream, no MCP support',
+        homepage: 'https://aider.chat',
+        installHint: 'pipx install aider-chat',
+    },
+    buildArgs(opts) {
+        // Prepend HOVER-mode preface plus any caller-supplied appendSystemPrompt
+        // to the prompt. Aider has no --append-system-prompt flag, so this is
+        // the closest functional analogue (same trick as cursor.ts).
+        const preface = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${AIDER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : AIDER_PROMPT_PREFACE;
+        const finalPrompt = `${preface}\n\n${opts.prompt}`;
+        const args = ['--message', finalPrompt];
+        // Auto-confirm every prompt so the run doesn't hang.
+        args.push('--yes-always');
+        // Make stdout line-buffered instead of character-streamed; friendlier
+        // for our per-line parseEvent loop.
+        args.push('--no-stream');
+        // Defang git side-effects. Aider's default behaviour is to auto-commit
+        // every edit it makes; for a browser-driving agent that should never
+        // edit files this is still a hazard if cwd is a stale repo.
+        args.push('--no-auto-commits');
+        args.push('--no-git');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        // Aider's `--restore-chat-history` is a boolean (no session-id form);
+        // we deliberately do NOT pass it. `opts.sessionId` is ignored because
+        // there is no way to select a specific past session by ID.
+        // No equivalents for --max-budget-usd / --allowedTools / --mcp-config /
+        // --append-system-prompt — all four are absent from aider.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        const s = aiderState(state);
+        const out = [];
+        // Emit a synthetic session_start on the very first non-empty line so
+        // the widget gets the same shape it expects from JSON-based agents.
+        if (!s.runningSessionId) {
+            // Cheap unique id; aider has no real session_id we can echo. The
+            // Math.random() suffix is load-bearing — two states created in the
+            // same millisecond would otherwise collide and break per-invocation
+            // session tracking.
+            const rand = Math.random().toString(36).slice(2, 8);
+            s.runningSessionId = `aider-${Date.now().toString(36)}-${rand}`;
+            out.push({ kind: 'session_start', sessionId: s.runningSessionId });
+        }
+        if (isNoiseLine(line))
+            return out;
+        if (detectErrorLine(line)) {
+            s.sawErrorEvent = true;
+            out.push({ kind: 'text', text: line.trim() });
+            return out;
+        }
+        // Treat everything else as assistant text. Aider has no per-tool events
+        // so we cannot emit tool_use / tool_result — see file-header doc comment.
+        s.runningLines += 1;
+        s.collectedText.push(line.trim());
+        out.push({ kind: 'text', text: line.trim() });
+        return out;
+    },
+    /**
+     * Aider doesn't emit a terminal event — the child process simply exits
+     * after the final printed line. Synthesize session_end from accumulated
+     * state, same pattern as codex.ts.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = aiderState(state);
+        // The "summary" is the last non-empty text line, which is typically
+        // aider's final answer. If we collected nothing, leave it undefined
+        // rather than fabricating.
+        const lastText = s.collectedText.length > 0
+            ? s.collectedText[s.collectedText.length - 1]
+            : undefined;
+        return {
+            kind: 'session_end',
+            turns: s.runningLines,
+            // costUsd intentionally undefined — aider's "Tokens:" status line is
+            // ad-hoc text, not a stable API. We don't fabricate a number.
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: lastText,
+        };
+    },
+};
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetAiderCounters(aiderState(state)),
+    getState: (state) => {
+        const s = aiderState(state);
+        return {
+            runningLines: s.runningLines,
+            runningSessionId: s.runningSessionId,
+            collectedText: [...s.collectedText],
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/cursor.d.ts

@@ -0,0 +1,18 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const cursorAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches. Same pattern as codex.ts so the tests can drive
+ * the parser without going through invokeAgent.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningTurns: number;
+        runningSessionId: string | undefined;
+        runningModel: string | undefined;
+        lastAssistantText: string | undefined;
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=cursor.d.ts.map

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

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

package/dist/agents/cursor.js

@@ -0,0 +1,229 @@
+function cursorState(state) {
+    if (typeof state.runningTurns !== 'number') {
+        state.runningTurns = 0;
+        state.runningSessionId = undefined;
+        state.runningModel = undefined;
+        state.lastAssistantText = undefined;
+        state.sawErrorEvent = false;
+        state.toolNameByCallId = new Map();
+    }
+    return state;
+}
+function resetCursorCounters(s) {
+    s.runningTurns = 0;
+    s.runningSessionId = undefined;
+    s.runningModel = undefined;
+    s.lastAssistantText = undefined;
+    s.sawErrorEvent = false;
+    s.toolNameByCallId.clear();
+}
+/**
+ * Best-effort extraction of a tool's name from the `tool_call` envelope.
+ * Cursor's stream-json wraps each kind in a sub-object keyed by name
+ * (`shellToolCall`, `mcpToolCall`, etc.) but doesn't publish a stable
+ * `name` field at the top level. We:
+ *   1. Look for the first key that ends in `ToolCall` → strip the suffix.
+ *      `shellToolCall` → `shell`, `mcpToolCall` → `mcp`.
+ *   2. If the sub-object carries a `tool` / `name` field, prefer that
+ *      (mcp calls embed the playwright tool name there).
+ *   3. Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix to
+ *      match the normalised tool names claude / codex emit.
+ */
+function extractToolName(tc) {
+    if (!tc)
+        return { tool: 'unknown', input: undefined };
+    const wrapperKey = Object.keys(tc).find(k => k.endsWith('ToolCall'));
+    const inner = (wrapperKey ? tc[wrapperKey] : undefined) ?? undefined;
+    // Prefer the inner sub-tool name if it exists (MCP case).
+    const innerName = (inner && typeof inner === 'object' && 'tool' in inner && typeof inner.tool === 'string' && inner.tool) ||
+        (inner && typeof inner === 'object' && 'name' in inner && typeof inner.name === 'string' && inner.name) ||
+        null;
+    const kindFromKey = wrapperKey ? wrapperKey.replace(/ToolCall$/, '') : 'unknown';
+    const rawName = innerName || kindFromKey;
+    const tool = rawName
+        .replace(/^mcp__playwright__/, '')
+        .replace(/^mcp__hover-playwright__/, '');
+    const input = (inner && typeof inner === 'object' && 'input' in inner && inner.input) ||
+        (inner && typeof inner === 'object' && 'arguments' in inner && inner.arguments) ||
+        (inner && typeof inner === 'object' && 'args' in inner && inner.args) ||
+        inner;
+    return { tool, input };
+}
+function detectToolError(tc) {
+    if (!tc || typeof tc !== 'object')
+        return false;
+    const wrapperKey = Object.keys(tc).find(k => k.endsWith('ToolCall'));
+    const inner = wrapperKey ? tc[wrapperKey] : undefined;
+    if (!inner)
+        return false;
+    if (inner.is_error === true)
+        return true;
+    if (typeof inner.status === 'string' && /error|fail/i.test(inner.status))
+        return true;
+    return false;
+}
+/**
+ * The closest analogue Cursor has to claude's --append-system-prompt or
+ * codex's developer_instructions. Since there is no CLI flag, we prepend
+ * this to the user prompt so the agent sees it as the leading instruction.
+ */
+const CURSOR_PROMPT_PREFACE = [
+    '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 use 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 summary and stop.',
+].join(' ');
+export const cursorAgent = {
+    id: 'cursor',
+    binName: 'cursor-agent',
+    protocol: 'argv',
+    streamFormat: 'json-lines',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'Cursor',
+        tagline: 'Cursor — soft sandbox (no built-in tool deny-list)',
+        homepage: 'https://cursor.com/docs/cli/overview',
+        installHint: 'curl https://cursor.com/install -fsS | bash',
+    },
+    buildArgs(opts) {
+        // The HOVER-mode preface plus any caller-supplied appendSystemPrompt
+        // gets prepended to the prompt. This is the closest functional analogue
+        // Cursor has to claude's --append-system-prompt / codex's
+        // developer_instructions, because Cursor exposes no CLI flag for it.
+        const preface = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${CURSOR_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : CURSOR_PROMPT_PREFACE;
+        const finalPrompt = `${preface}\n\n${opts.prompt}`;
+        const args = ['-p', finalPrompt];
+        // NDJSON streaming output.
+        args.push('--output-format', 'stream-json');
+        // Non-interactive: auto-approve commands and MCP tools so the run doesn't
+        // hang waiting for permission. Cursor calls this --force / --yolo.
+        args.push('--force');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        if (opts.sessionId) {
+            // Cursor's --resume accepts the chat_id. Empty / no-arg --resume
+            // resumes the latest, which is NOT what we want here.
+            args.push('--resume', opts.sessionId);
+        }
+        // MCP servers are configured in ~/.cursor/mcp.json (or repo-local
+        // .cursor/mcp.json) at install time, not per-invocation. Cursor has no
+        // equivalent of claude's --mcp-config. If the caller passed opts.mcpConfig
+        // we don't have a way to forward it; service.ts logs a one-time warning.
+        // No equivalent for --max-budget-usd or --allowedTools / --disallowedTools.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        if (!line.trim())
+            return [];
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            return [{ kind: 'raw', line }];
+        }
+        const s = cursorState(state);
+        const out = [];
+        if (ev.type === 'system' && ev.subtype === 'init') {
+            resetCursorCounters(s);
+            s.runningModel = ev.model;
+            if (ev.session_id) {
+                s.runningSessionId = ev.session_id;
+                out.push({ kind: 'session_start', sessionId: ev.session_id, model: ev.model });
+            }
+            return out;
+        }
+        if (ev.type === 'tool_call' && ev.subtype === 'started') {
+            const { tool, input } = extractToolName(ev.tool_call);
+            if (ev.call_id)
+                s.toolNameByCallId.set(ev.call_id, tool);
+            out.push({ kind: 'tool_use', tool, input });
+            return out;
+        }
+        if (ev.type === 'tool_call' && ev.subtype === 'completed') {
+            const isError = detectToolError(ev.tool_call);
+            out.push({ kind: 'tool_result', isError });
+            return out;
+        }
+        if (ev.type === 'assistant') {
+            s.runningTurns += 1;
+            // Emit a usage event so the widget can advance its turn counter even
+            // though Cursor gives us no token / $ data. costUsd intentionally
+            // omitted — we don't fabricate a number.
+            out.push({ kind: 'usage', turns: s.runningTurns });
+            for (const block of ev.message?.content ?? []) {
+                if (block.type === 'text') {
+                    const text = block.text?.trim();
+                    if (text) {
+                        s.lastAssistantText = text;
+                        out.push({ kind: 'text', text });
+                    }
+                }
+            }
+            return out;
+        }
+        if (ev.type === 'result') {
+            // Cursor's result event IS the session_end. We forward it directly so
+            // onStreamEnd doesn't need to synthesize.
+            const isError = ev.is_error === true ||
+                (typeof ev.subtype === 'string' && /error|fail/i.test(ev.subtype));
+            if (isError)
+                s.sawErrorEvent = true;
+            out.push({
+                kind: 'session_end',
+                turns: s.runningTurns,
+                // costUsd intentionally undefined — Cursor doesn't publish $ or tokens.
+                isError,
+                summary: ev.result ?? s.lastAssistantText,
+            });
+            return out;
+        }
+        // Cursor sometimes emits error envelopes mid-stream; surface them as
+        // text so the widget shows the problem instead of silently hanging.
+        if (ev.type && /error/i.test(ev.type)) {
+            s.sawErrorEvent = true;
+            // No documented `message` field on these — best-effort.
+            const msg = ev.result ?? `[cursor] ${ev.type}`;
+            out.push({ kind: 'text', text: msg });
+            return out;
+        }
+        return [];
+    },
+    /**
+     * Cursor's `result` event already produces a session_end via parseEvent;
+     * this fallback is for the case where the child exits without emitting a
+     * `result` (e.g. crash, signal). Mirrors codex.ts's shape.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = cursorState(state);
+        return {
+            kind: 'session_end',
+            turns: s.runningTurns,
+            // costUsd intentionally undefined — see parseEvent note.
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: s.lastAssistantText,
+        };
+    },
+};
+/**
+ * Test-only escape hatches. Same pattern as codex.ts so the tests can drive
+ * the parser without going through invokeAgent.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetCursorCounters(cursorState(state)),
+    getState: (state) => {
+        const s = cursorState(state);
+        return {
+            runningTurns: s.runningTurns,
+            runningSessionId: s.runningSessionId,
+            runningModel: s.runningModel,
+            lastAssistantText: s.lastAssistantText,
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/gemini.d.ts

@@ -0,0 +1,17 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const geminiAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningTurns: number;
+        runningSessionId: string | undefined;
+        runningModel: string | undefined;
+        lastAssistantText: string | undefined;
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=gemini.d.ts.map

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

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

package/dist/agents/gemini.js

@@ -0,0 +1,197 @@
+function geminiState(state) {
+    if (typeof state.runningTurns !== 'number') {
+        state.runningTurns = 0;
+        state.runningSessionId = undefined;
+        state.runningModel = undefined;
+        state.lastAssistantText = undefined;
+        state.sawErrorEvent = false;
+        state.toolNameByUseId = new Map();
+    }
+    return state;
+}
+function resetGeminiCounters(s) {
+    s.runningTurns = 0;
+    s.runningSessionId = undefined;
+    s.runningModel = undefined;
+    s.lastAssistantText = undefined;
+    s.sawErrorEvent = false;
+    s.toolNameByUseId.clear();
+}
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names claude / codex / cursor / qwen emit. */
+function stripMcpPrefix(raw) {
+    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
+}
+/**
+ * Extract assistant text from a `message` event whose `content` may be a
+ * plain string OR an array of `{type:'text', text}` content blocks. Gemini's
+ * docs aren't explicit on which shape ships per build, so we handle both.
+ */
+function extractMessageText(ev) {
+    if (typeof ev.content === 'string') {
+        const t = ev.content.trim();
+        return t.length > 0 ? t : undefined;
+    }
+    if (Array.isArray(ev.content)) {
+        const parts = ev.content
+            .filter(b => b.type === 'text' && typeof b.text === 'string')
+            .map(b => b.text.trim())
+            .filter(t => t.length > 0);
+        return parts.length > 0 ? parts.join('\n') : undefined;
+    }
+    return undefined;
+}
+const GEMINI_PROMPT_PREFACE = [
+    '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 use 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 summary and stop.',
+].join(' ');
+export const geminiAgent = {
+    id: 'gemini',
+    binName: 'gemini',
+    protocol: 'argv',
+    streamFormat: 'json-lines',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'Gemini',
+        tagline: 'Google Gemini — soft sandbox (no built-in tool deny-list)',
+        homepage: 'https://github.com/google-gemini/gemini-cli',
+        installHint: 'npm install -g @google/gemini-cli',
+    },
+    buildArgs(opts) {
+        // Gemini has no --append-system-prompt CLI flag (only the
+        // GEMINI_SYSTEM_MD env var which writes a file). Prepend the HOVER-mode
+        // preface to the prompt instead — same pattern as cursor.ts / aider.ts.
+        const preface = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${GEMINI_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : GEMINI_PROMPT_PREFACE;
+        const finalPrompt = `${preface}\n\n${opts.prompt}`;
+        const args = ['-p', finalPrompt];
+        // NDJSON streaming output.
+        args.push('--output-format', 'stream-json');
+        // Auto-approve all tool calls so the run doesn't hang. The newer
+        // canonical form is --approval-mode=yolo; --yolo is deprecated but
+        // still accepted in 2026-05. We use the modern form.
+        args.push('--approval-mode', 'yolo');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        if (opts.sessionId) {
+            // --resume <id> is the documented form. -r is the alias. The single
+            // string 'latest' picks the most recent session; we only pass an
+            // explicit id, never the literal 'latest'.
+            args.push('--resume', opts.sessionId);
+        }
+        // MCP servers configured via `gemini mcp add` at install time — no
+        // per-invocation --mcp-config equivalent.
+        // No equivalent for --max-budget-usd or --allowedTools / --disallowedTools
+        // in the disable-built-ins sense.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        if (!line.trim())
+            return [];
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            return [{ kind: 'raw', line }];
+        }
+        const s = geminiState(state);
+        const out = [];
+        if (ev.type === 'init') {
+            resetGeminiCounters(s);
+            s.runningModel = ev.model;
+            if (ev.session_id) {
+                s.runningSessionId = ev.session_id;
+                out.push({ kind: 'session_start', sessionId: ev.session_id, model: ev.model });
+            }
+            return out;
+        }
+        if (ev.type === 'message') {
+            // Only count and surface assistant messages — user echoes (the
+            // role:'user' message events) don't count as turns from our POV.
+            if (ev.role === 'assistant' || ev.role === undefined) {
+                s.runningTurns += 1;
+                out.push({ kind: 'usage', turns: s.runningTurns });
+                const text = extractMessageText(ev);
+                if (text) {
+                    s.lastAssistantText = text;
+                    out.push({ kind: 'text', text });
+                }
+            }
+            return out;
+        }
+        if (ev.type === 'tool_use') {
+            const rawName = ev.name ?? '';
+            const tool = stripMcpPrefix(rawName);
+            if (ev.id)
+                s.toolNameByUseId.set(ev.id, tool);
+            out.push({ kind: 'tool_use', tool, input: ev.input });
+            return out;
+        }
+        if (ev.type === 'tool_result') {
+            const isError = ev.is_error === true;
+            out.push({ kind: 'tool_result', isError });
+            return out;
+        }
+        if (ev.type === 'result') {
+            // result.stats may carry turns; prefer it over our running count.
+            const turns = ev.stats?.turns ?? ev.stats?.model?.turns ?? s.runningTurns;
+            const isError = ev.is_error === true || ev.error !== undefined && ev.error !== null;
+            if (isError)
+                s.sawErrorEvent = true;
+            out.push({
+                kind: 'session_end',
+                turns,
+                // costUsd intentionally undefined — gemini's stats block does not
+                // include $ figures.
+                isError,
+                summary: ev.response ?? s.lastAssistantText,
+            });
+            return out;
+        }
+        if (ev.type === 'error') {
+            s.sawErrorEvent = true;
+            const msg = ev.message ?? ev.error?.message ?? `[gemini] error`;
+            out.push({ kind: 'text', text: msg });
+            return out;
+        }
+        return [];
+    },
+    /**
+     * Gemini's `result` event already produces a session_end via parseEvent;
+     * this fallback is for the case where the child exits without emitting a
+     * `result` (e.g. crash, signal). Same shape as cursor.ts / qwen.ts.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = geminiState(state);
+        return {
+            kind: 'session_end',
+            turns: s.runningTurns,
+            // costUsd intentionally undefined — see parseEvent note.
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: s.lastAssistantText,
+        };
+    },
+};
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetGeminiCounters(geminiState(state)),
+    getState: (state) => {
+        const s = geminiState(state);
+        return {
+            runningTurns: s.runningTurns,
+            runningSessionId: s.runningSessionId,
+            runningModel: s.runningModel,
+            lastAssistantText: s.lastAssistantText,
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/qwen.d.ts

@@ -0,0 +1,17 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const qwenAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningTurns: number;
+        runningSessionId: string | undefined;
+        runningModel: string | undefined;
+        lastAssistantText: string | undefined;
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=qwen.d.ts.map

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

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

package/dist/agents/qwen.js

@@ -0,0 +1,183 @@
+function qwenState(state) {
+    if (typeof state.runningTurns !== 'number') {
+        state.runningTurns = 0;
+        state.runningSessionId = undefined;
+        state.runningModel = undefined;
+        state.lastAssistantText = undefined;
+        state.sawErrorEvent = false;
+        state.toolNameByUseId = new Map();
+    }
+    return state;
+}
+function resetQwenCounters(s) {
+    s.runningTurns = 0;
+    s.runningSessionId = undefined;
+    s.runningModel = undefined;
+    s.lastAssistantText = undefined;
+    s.sawErrorEvent = false;
+    s.toolNameByUseId.clear();
+}
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names claude / codex / cursor emit. */
+function stripMcpPrefix(raw) {
+    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
+}
+const QWEN_PROMPT_PREFACE = [
+    '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 use 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 summary and stop.',
+].join(' ');
+export const qwenAgent = {
+    id: 'qwen',
+    binName: 'qwen',
+    protocol: 'argv',
+    streamFormat: 'json-lines',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'Qwen Code',
+        tagline: 'Qwen Code — soft sandbox (no built-in tool deny-list)',
+        homepage: 'https://github.com/QwenLM/qwen-code',
+        installHint: 'npm install -g @qwen-code/qwen-code@latest',
+    },
+    buildArgs(opts) {
+        const args = ['-p', opts.prompt];
+        // NDJSON streaming output.
+        args.push('--output-format', 'stream-json');
+        // Auto-approve all tool calls so the run doesn't hang. The newer
+        // canonical form is --approval-mode=yolo; --yolo is deprecated but
+        // still works in 2026-05. We use the modern form.
+        args.push('--approval-mode', 'yolo');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        if (opts.sessionId) {
+            // --resume <sessionId> is the documented headless form. --continue
+            // (no arg) picks the most recent — NOT what we want when a specific
+            // session was passed.
+            args.push('--resume', opts.sessionId);
+        }
+        // Qwen has a real --append-system-prompt flag — use it instead of
+        // prepending to the user prompt. Concatenate the standing Hover-mode
+        // preface with whatever the caller appended.
+        const sysPrompt = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${QWEN_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : QWEN_PROMPT_PREFACE;
+        args.push('--append-system-prompt', sysPrompt);
+        // MCP servers configured in ~/.qwen/settings.json — no per-invocation
+        // --mcp-config equivalent. Same constraint as cursor / codex.
+        // No equivalent for --max-budget-usd or --allowedTools / --disallowedTools.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        if (!line.trim())
+            return [];
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            return [{ kind: 'raw', line }];
+        }
+        const s = qwenState(state);
+        const out = [];
+        if (ev.type === 'system' && ev.subtype === 'session_start') {
+            resetQwenCounters(s);
+            s.runningModel = ev.model;
+            if (ev.session_id) {
+                s.runningSessionId = ev.session_id;
+                out.push({ kind: 'session_start', sessionId: ev.session_id, model: ev.model });
+            }
+            return out;
+        }
+        if (ev.type === 'assistant' && ev.message) {
+            s.runningTurns += 1;
+            // Emit a usage event so the widget can advance its turn counter.
+            // costUsd intentionally omitted — qwen doesn't publish $ in stream.
+            out.push({ kind: 'usage', turns: s.runningTurns });
+            for (const block of ev.message.content ?? []) {
+                if (block.type === 'text') {
+                    const text = block.text?.trim();
+                    if (text) {
+                        s.lastAssistantText = text;
+                        out.push({ kind: 'text', text });
+                    }
+                }
+                else if (block.type === 'tool_use') {
+                    const rawName = block.name ?? '';
+                    const tool = stripMcpPrefix(rawName);
+                    if (block.id)
+                        s.toolNameByUseId.set(block.id, tool);
+                    out.push({ kind: 'tool_use', tool, input: block.input });
+                }
+            }
+            return out;
+        }
+        // tool_result blocks are wrapped in `user` messages (Anthropic Messages
+        // convention). We surface them as tool_result events.
+        if (ev.type === 'user' && ev.message) {
+            for (const block of ev.message.content ?? []) {
+                if (block.type === 'tool_result') {
+                    const isError = block.is_error === true;
+                    out.push({ kind: 'tool_result', isError });
+                }
+            }
+            return out;
+        }
+        if (ev.type === 'result') {
+            const isError = ev.is_error === true ||
+                (typeof ev.subtype === 'string' && /error|fail/i.test(ev.subtype));
+            if (isError)
+                s.sawErrorEvent = true;
+            out.push({
+                kind: 'session_end',
+                turns: s.runningTurns,
+                // costUsd intentionally undefined — qwen doesn't publish $.
+                isError,
+                summary: ev.result ?? s.lastAssistantText,
+            });
+            return out;
+        }
+        // Qwen emits various error envelopes mid-stream; surface them as text.
+        if (ev.type && /error/i.test(ev.type)) {
+            s.sawErrorEvent = true;
+            const msg = ev.error?.message ?? ev.text ?? ev.result ?? `[qwen] ${ev.type}`;
+            out.push({ kind: 'text', text: msg });
+            return out;
+        }
+        return [];
+    },
+    /**
+     * Qwen's `result` event already produces a session_end via parseEvent;
+     * this fallback is for the case where the child exits without emitting a
+     * `result` (e.g. crash, signal). Mirrors codex.ts / cursor.ts shape.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = qwenState(state);
+        return {
+            kind: 'session_end',
+            turns: s.runningTurns,
+            // costUsd intentionally undefined — see parseEvent note.
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: s.lastAssistantText,
+        };
+    },
+};
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetQwenCounters(qwenState(state)),
+    getState: (state) => {
+        const s = qwenState(state);
+        return {
+            runningTurns: s.runningTurns,
+            runningSessionId: s.runningSessionId,
+            runningModel: s.runningModel,
+            lastAssistantText: s.lastAssistantText,
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/registry.d.ts

@@ -2,13 +2,15 @@ import type { AgentDescriptor } from './types.js';
 /**
  * Registry of agents Hover can drive.
  *
- * 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.
+ * To add support for another agent (e.g. cline, continue, 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.
+ * the recommended primary first. The two hard-sandbox / first-party agents
+ * (claude, codex) lead; the soft-sandbox third-party agents follow in the
+ * order they were added.
  */
 export declare const AGENTS: Record<string, AgentDescriptor>;
 export declare function getAgent(id: string): AgentDescriptor | undefined;

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;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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAQlD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAOlD,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,19 +1,29 @@
 import { claudeAgent } from './claude.js';
 import { codexAgent } from './codex.js';
+import { cursorAgent } from './cursor.js';
+import { aiderAgent } from './aider.js';
+import { geminiAgent } from './gemini.js';
+import { qwenAgent } from './qwen.js';
 /**
  * Registry of agents Hover can drive.
  *
- * 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.
+ * To add support for another agent (e.g. cline, continue, 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.
+ * the recommended primary first. The two hard-sandbox / first-party agents
+ * (claude, codex) lead; the soft-sandbox third-party agents follow in the
+ * order they were added.
  */
 export const AGENTS = {
     [claudeAgent.id]: claudeAgent,
     [codexAgent.id]: codexAgent,
+    [cursorAgent.id]: cursorAgent,
+    [aiderAgent.id]: aiderAgent,
+    [geminiAgent.id]: geminiAgent,
+    [qwenAgent.id]: qwenAgent,
 };
 export function getAgent(id) {
     return AGENTS[id];

package/dist/plugin-api.d.ts

@@ -139,6 +139,16 @@ export interface HoverPluginManifest {
      *  here so the widget side can be tree-shaken to skip handlers for
      *  events that no loaded plugin will ever produce. */
     widgetEventTypes?: string[];
+    /** Absolute path to a JS module that runs inside the widget's Shadow
+     *  DOM. The host reads this file at bundle-assembly time, inlines it
+     *  as a `<script type="module">` after the widget core, and exposes
+     *  `window.__HOVER_WIDGET__` for the module to register itself.
+     *
+     *  Plugin authors typically resolve this via `import.meta` or
+     *  `fileURLToPath(new URL('./widget.js', import.meta.url))` from
+     *  inside their server-side entry. If absent, the plugin contributes
+     *  no widget code (server-side-only plugin). */
+    widgetEntry?: string;
     hooks?: HoverHooks;
 }
 /**

package/dist/plugin-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-api.d.ts","sourceRoot":"","sources":["../src/plugin-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin-api.d.ts","sourceRoot":"","sources":["../src/plugin-api.ts"],"names":[],"mappings":"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"}

package/dist/scripts/bench-multi-tab.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bench-multi-tab.d.ts.map

package/dist/scripts/bench-multi-tab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench-multi-tab.d.ts","sourceRoot":"","sources":["../../src/scripts/bench-multi-tab.ts"],"names":[],"mappings":""}

package/dist/scripts/bench-multi-tab.js

@@ -0,0 +1,192 @@
+/**
+ * Benchmark agent success rate on the multi-tab "Pay with PayHover" flow.
+ *
+ * Why this exists — v0.10's central theme is "agent can drive cross-tab
+ * flows in the wild." The system-prompt addendum (cdpHint.ts rule 5/6/7)
+ * is the lever we're tuning. This script gives us a number to tune
+ * against: across N iterations, how often does the agent get from
+ * "browse the store" to "Order placed"?
+ *
+ * Per iteration the agent has to:
+ *   1. Browse the e-commerce store, add 1+ items to cart, go to checkout.
+ *   2. Fill the shipping form.
+ *   3. Pick "Pay with PayHover" (opens a new tab at localhost:5177).
+ *   4. Switch to the new tab, fill card number + CVV, click Continue.
+ *   5. Wait ~600ms for the simulated 3DS pre-check.
+ *   6. Fill the 6-digit OTP (always 123456 in the sandbox).
+ *   7. Click Confirm. The provider tab closes itself.
+ *   8. Switch back to the original tab, observe the "Order placed" view.
+ *
+ * Steps 3, 4, 7, 8 are the failure-prone ones.
+ *
+ * Assumes:
+ *   - Debug Chrome on :9222 (run `pnpm smoke:chrome`).
+ *   - e-commerce on :5174 AND payment-provider on :5177 both running
+ *     (run `pnpm dev:example:e-commerce` and `pnpm dev:example:payment-provider`
+ *     in two terminals before invoking this).
+ *
+ * Usage:
+ *   pnpm --filter @hover-dev/core exec tsx src/scripts/bench-multi-tab.ts [n]
+ *   pnpm bench-multi-tab [n]
+ *
+ * `n` defaults to 5. Per-iteration timeout is 5 minutes — multi-tab flows
+ * are slow because the agent does a lot of browser_snapshot calls.
+ *
+ * Output: per-run pass/fail + final summary (success rate, median wall
+ * time, median turns, median cost in $). A/B prompt changes by running
+ * once on each branch and comparing.
+ */
+import { WebSocket } from 'ws';
+import { startService } from '../service.js';
+const PROMPT = process.env.HOVER_BENCH_PROMPT ??
+    [
+        'Open http://localhost:5174 (Hover Store).',
+        'Add any item to the cart, go to checkout, fill the shipping form with',
+        'realistic values, then choose "Pay with PayHover". A new tab opens at',
+        'the payment provider — switch to it, fill in card 4242 4242 4242 4242',
+        'with CVV 123, click Continue, wait for the OTP step, enter 123456,',
+        'click Confirm. The popup will close. Switch back to the original tab',
+        'and verify the order shows as placed.',
+    ].join(' ');
+const ITERATIONS = Number(process.argv[2] ?? 5);
+const PER_RUN_TIMEOUT_MS = 5 * 60 * 1000;
+async function singleRun(idx) {
+    process.stderr.write(`\n[bench-multi-tab] run ${idx + 1}/${ITERATIONS}\n`);
+    const service = await startService({
+        port: 0,
+        agentId: 'claude',
+        model: 'sonnet',
+        cdpUrl: 'http://localhost:9222',
+        devRoot: process.cwd(),
+    });
+    return new Promise((resolve) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${service.port}`);
+        const t0 = performance.now();
+        let turns = 0;
+        let costUsd = null;
+        let resolved = false;
+        const finish = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            try {
+                ws.close(1000);
+            }
+            catch { /* already closed */ }
+            service.close().finally(() => resolve(result));
+        };
+        const timeout = setTimeout(() => {
+            finish({
+                ok: false,
+                wallMs: performance.now() - t0,
+                turns,
+                costUsd,
+                reason: `timed out after ${PER_RUN_TIMEOUT_MS / 1000}s`,
+            });
+        }, PER_RUN_TIMEOUT_MS);
+        ws.on('open', () => {
+            ws.send(JSON.stringify({ type: 'command', payload: { text: PROMPT } }));
+        });
+        ws.on('message', (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            if (msg.type !== 'event')
+                return;
+            const ev = msg.payload;
+            if (ev.kind === 'tool_use') {
+                turns += 1;
+                if (process.env.HOVER_BENCH_VERBOSE === '1') {
+                    const ev2 = ev;
+                    process.stderr.write(`    [turn ${turns}] ${ev2.name ?? '<tool>'}\n`);
+                }
+            }
+            if (ev.kind === 'session_end') {
+                clearTimeout(timeout);
+                const evAny = ev;
+                if (typeof evAny.costUsd === 'number')
+                    costUsd = evAny.costUsd;
+                finish({
+                    ok: !evAny.isError,
+                    wallMs: performance.now() - t0,
+                    turns,
+                    costUsd,
+                    reason: evAny.isError ? 'agent reported error' : undefined,
+                });
+            }
+        });
+        ws.on('error', (err) => {
+            clearTimeout(timeout);
+            finish({
+                ok: false,
+                wallMs: performance.now() - t0,
+                turns,
+                costUsd,
+                reason: `WS error: ${err.message}`,
+            });
+        });
+    });
+}
+function median(xs) {
+    if (xs.length === 0)
+        return 0;
+    const sorted = [...xs].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+function fmtMs(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function fmtUsd(usd) {
+    return usd == null ? '–' : `$${usd.toFixed(4)}`;
+}
+async function main() {
+    process.stderr.write(`[bench-multi-tab] ${ITERATIONS} iterations, per-run timeout ${PER_RUN_TIMEOUT_MS / 1000}s\n`);
+    process.stderr.write(`[bench-multi-tab] prompt: ${PROMPT.slice(0, 80)}…\n`);
+    const results = [];
+    for (let i = 0; i < ITERATIONS; i++) {
+        try {
+            const r = await singleRun(i);
+            results.push(r);
+            const status = r.ok ? '✓ PASS' : '✗ FAIL';
+            process.stderr.write(`[bench-multi-tab] run ${i + 1}: ${status} · ${fmtMs(r.wallMs)} · ${r.turns} turns · ${fmtUsd(r.costUsd)}${r.reason ? ` · ${r.reason}` : ''}\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            results.push({ ok: false, wallMs: 0, turns: 0, costUsd: null, reason: msg });
+            process.stderr.write(`[bench-multi-tab] run ${i + 1}: ✗ FAIL · setup error · ${msg}\n`);
+        }
+    }
+    const passes = results.filter((r) => r.ok);
+    const successRate = passes.length / results.length;
+    process.stderr.write('\n[bench-multi-tab] summary\n');
+    process.stderr.write(`  success rate: ${(successRate * 100).toFixed(0)}% (${passes.length}/${results.length})\n`);
+    if (passes.length > 0) {
+        process.stderr.write(`  median wall:  ${fmtMs(median(passes.map((r) => r.wallMs)))}\n`);
+        process.stderr.write(`  median turns: ${median(passes.map((r) => r.turns)).toFixed(0)}\n`);
+        const costs = passes.map((r) => r.costUsd).filter((c) => c != null);
+        if (costs.length > 0) {
+            process.stderr.write(`  median cost:  ${fmtUsd(median(costs))}\n`);
+        }
+    }
+    if (passes.length < results.length) {
+        process.stderr.write(`\n  failures:\n`);
+        results.forEach((r, i) => {
+            if (!r.ok)
+                process.stderr.write(`    run ${i + 1}: ${r.reason ?? 'unknown'}\n`);
+        });
+    }
+    // Exit non-zero if EVERY run failed — useful for CI plumbing later. A
+    // partial-pass run still exits 0 so we collect signal across branches.
+    process.exit(passes.length === 0 ? 1 : 0);
+}
+main().catch((err) => {
+    process.stderr.write(`[bench-multi-tab] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/service/cdpHint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cdpHint.d.ts","sourceRoot":"","sources":["../../src/service/cdpHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,UAAU,GAAG;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAa7C,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CA4FhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAYtD"}
+{"version":3,"file":"cdpHint.d.ts","sourceRoot":"","sources":["../../src/service/cdpHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,UAAU,GAAG;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAa7C,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAmIhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAYtD"}

package/dist/service/cdpHint.js

@@ -101,6 +101,45 @@ export function buildCdpHint(tabs) {
         `  4. To see the current page state, call browser_snapshot first. Only`,
         `     navigate if you actually need a different URL.`,
         ``,
+        `Multi-tab + cross-origin flows (Stripe Checkout, OAuth login, "Pay with X" popups):`,
+        ``,
+        `  5. When you click something that may open a new tab (target=_blank, a`,
+        `     window.open trigger, a "Pay with …" / "Sign in with …" button), the`,
+        `     popup tab is where the next user-visible step happens — but your tools`,
+        `     stay anchored to the prior tab until you switch. After such a click:`,
+        ``,
+        `       a) Call browser_tabs(action='list') to see if a new tab appeared.`,
+        `          A new entry at a different origin is the popup.`,
+        `       b) Call browser_tabs(action='select', idx=<popup idx>) to focus it,`,
+        `          then browser_snapshot the new tab and proceed.`,
+        `       c) When the popup closes (it usually does so on success/cancel —`,
+        `          window.close() or after a redirect chain), browser_tabs(list)`,
+        `          will no longer show it. The current page may be invalid; call`,
+        `          browser_tabs(action='select', idx=0) to refocus the original tab,`,
+        `          then browser_snapshot it. The original tab's DOM may have updated`,
+        `          via a postMessage handler (e.g. it should now show a "Success" or`,
+        `          "Payment complete" state).`,
+        `       d) If the original tab's snapshot looks unchanged (still showing the`,
+        `          checkout form / login button), the postMessage handler may not`,
+        `          have fired yet or may not exist. Wait once with`,
+        `          browser_wait_for_text("<expected success copy>", timeout=3000)`,
+        `          before concluding the flow is broken.`,
+        ``,
+        `  6. OAuth-style redirect chains: when a tab redirects through several`,
+        `     origins (myapp → identity provider → /callback?code=… → myapp), watch`,
+        `     browser_tabs after each browser_snapshot — the same tab idx can switch`,
+        `     origin underneath you. The URL in browser_tabs(list) is authoritative.`,
+        ``,
+        `  7. Cross-origin cookie/session updates: after the popup closes and you're`,
+        `     back on the original tab, the server-set session cookie may be present`,
+        `     in the browser but the React state hasn't yet picked it up. The most`,
+        `     likely cause is a missing or slow postMessage handler — NOT a real`,
+        `     bug yet. Try browser_wait_for_text once for the expected logged-in`,
+        `     copy with a 3s timeout. If nothing shows, report it as a Finding`,
+        `     ("Original tab did not update after popup closed — likely missing`,
+        `     postMessage listener or auth refresh"); do NOT browser_navigate to`,
+        `     same-origin to force a refresh (rule #2 still applies).`,
+        ``,
         `Narration format — affects how the widget renders your run for the user:`,
         ``,
         `  Before each LOGICAL STEP (a coherent unit of work like "Open the login`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -75,6 +75,7 @@
     "verify-spec": "tsx src/scripts/verify-spec.ts",
     "ws-smoke": "tsx src/scripts/ws-smoke.ts",
     "bench-ttfb": "tsx src/scripts/bench-ttfb.ts",
+    "bench-multi-tab": "tsx src/scripts/bench-multi-tab.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },