@hover-dev/core 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -20,37 +20,25 @@
     "claude"
   ],
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/engine.js",
+  "types": "dist/engine.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/engine.d.ts",
+      "import": "./dist/engine.js"
     },
-    "./agents": {
-      "types": "./dist/agents/index.d.ts",
-      "import": "./dist/agents/index.js"
-    },
-    "./service": {
-      "types": "./dist/service.d.ts",
-      "import": "./dist/service.js"
-    },
-    "./launch-chrome": {
-      "types": "./dist/playwright/launchChrome.d.ts",
-      "import": "./dist/playwright/launchChrome.js"
-    },
-    "./plugin-api": {
-      "types": "./dist/plugin-api.d.ts",
-      "import": "./dist/plugin-api.js"
+    "./engine": {
+      "types": "./dist/engine.d.ts",
+      "import": "./dist/engine.js"
     }
   },
   "files": [
     "dist",
+    "seeds",
     "README.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@playwright/mcp": "0.0.75",
     "cross-spawn": "^7.0.6",
     "playwright-core": "^1.50.0",
     "ts-morph": "^28.0.0",
@@ -70,14 +58,6 @@
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "smoke": "tsx src/smoke.ts",
-    "smoke:chrome": "tsx src/scripts/start-chrome.ts",
-    "detect": "tsx src/scripts/detect-cli.ts",
-    "verify-widget": "tsx src/scripts/verify-widget.ts",
-    "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"
   },

package/dist/agents/aider.d.ts

@@ -1,16 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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;AA8G3F,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

@@ -1,161 +0,0 @@
-import { HOVER_PROMPT_PREFACE } from './shared.js';
-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 the standing HOVER-mode
-// preface (HOVER_PROMPT_PREFACE, from shared.ts) to the user prompt (same
-// approach as cursor.ts). The agent treats it as the leading user-message text.
-/**
- * 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
-            ? `${HOVER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
-            : HOVER_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/argv.d.ts

@@ -1,11 +0,0 @@
-import type { AgentDescriptor, InvokeOptions } from './types.js';
-/**
- * Build argv for spawning an agent.
- *
- * Per-agent argument logic lives on the descriptor (e.g. claude.ts owns its
- * own `--mcp-config`, `--permission-mode` etc.). This dispatcher only
- * gates by protocol — `acp` and `pi-rpc` are not yet implemented because
- * they require a long-lived bidirectional channel rather than argv.
- */
-export declare function buildArgv(descriptor: AgentDescriptor, opts: InvokeOptions): string[];
-//# sourceMappingURL=argv.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"argv.d.ts","sourceRoot":"","sources":["../../src/agents/argv.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGjE;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAepF"}

package/dist/agents/argv.js

@@ -1,23 +0,0 @@
-import { UnsupportedAgentProtocolError } from './types.js';
-/**
- * Build argv for spawning an agent.
- *
- * Per-agent argument logic lives on the descriptor (e.g. claude.ts owns its
- * own `--mcp-config`, `--permission-mode` etc.). This dispatcher only
- * gates by protocol — `acp` and `pi-rpc` are not yet implemented because
- * they require a long-lived bidirectional channel rather than argv.
- */
-export function buildArgv(descriptor, opts) {
-    switch (descriptor.protocol) {
-        case 'argv':
-        case 'stdin':
-            return descriptor.buildArgs(opts);
-        case 'acp':
-        case 'pi-rpc':
-            throw new UnsupportedAgentProtocolError(`Agent protocol "${descriptor.protocol}" is not yet implemented (agent: ${descriptor.id})`);
-        default: {
-            const exhaustive = descriptor.protocol;
-            throw new UnsupportedAgentProtocolError(`Unknown protocol: ${String(exhaustive)}`);
-        }
-    }
-}

package/dist/agents/claude.d.ts

@@ -1,3 +0,0 @@
-import type { AgentDescriptor } from './types.js';
-export declare const claudeAgent: AgentDescriptor;
-//# sourceMappingURL=claude.d.ts.map

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

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

package/dist/agents/claude.js

@@ -1,195 +0,0 @@
-/**
- * Running-cost accumulator across one parser lifecycle. Claude Code's
- * stream-json sometimes carries `total_cost_usd` on intermediate events; when
- * it does we just forward it. When it doesn't, we estimate from token usage
- * using public per-million pricing. Hardcoded rates because they change
- * rarely and we'd rather not network-fetch a price table from a sandbox.
- *
- * The estimate is empirically about 1.5–2× the authoritative
- * `total_cost_usd` that arrives on the final `result` event (overhead from
- * tool-definition tokens we don't see + Claude's actual cache hit ratios
- * vs. our pessimistic accounting). That's fine for the widget's purpose:
- * give the user a signal of cost direction and order-of-magnitude so they
- * know when to hit Stop. The done card displays the final authoritative
- * number from `total_cost_usd`, so the user always sees the ground truth.
- */
-const PRICE_PER_M_USD = {
-    // claude-sonnet-4 / 4.5 / 4.6 / 4.7 — all priced the same as of 2026
-    sonnet: { in: 3, out: 15, cacheCreate: 3.75, cacheRead: 0.3 },
-    opus: { in: 15, out: 75, cacheCreate: 18.75, cacheRead: 1.5 },
-    haiku: { in: 1, out: 5, cacheCreate: 1.25, cacheRead: 0.1 },
-};
-function estimateCostUsd(modelHint, usage) {
-    // Match the most specific tier by substring. e.g. 'claude-sonnet-4-6' → sonnet.
-    const m = (modelHint ?? 'sonnet').toLowerCase();
-    const tier = m.includes('opus') ? PRICE_PER_M_USD.opus :
-        m.includes('haiku') ? PRICE_PER_M_USD.haiku :
-            PRICE_PER_M_USD.sonnet;
-    return ((usage.input_tokens ?? 0) * tier.in +
-        (usage.output_tokens ?? 0) * tier.out +
-        (usage.cache_creation_input_tokens ?? 0) * tier.cacheCreate +
-        (usage.cache_read_input_tokens ?? 0) * tier.cacheRead) / 1_000_000;
-}
-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;
-}
-/** Every built-in claude-code tool that has nothing to do with driving a
- *  browser. Combined with `--strict-mcp-config` + an allow-list of mcp__*
- *  ids, this leaves Claude with only the Playwright MCP (plus any
- *  plugin-contributed MCPs) as a usable tool surface. */
-const CLAUDE_DEFAULT_DISALLOWED_TOOLS = [
-    // file / shell / data access — never appropriate for browser driving
-    'Bash', 'BashOutput', 'KillBash',
-    'Edit', 'MultiEdit', 'Write', 'Read', 'NotebookEdit',
-    'Grep', 'Glob', 'Task', 'TodoWrite',
-    'WebFetch', 'WebSearch',
-    // plan / worktree / cron / notification — irrelevant in -p mode
-    'EnterPlanMode', 'ExitPlanMode',
-    'EnterWorktree', 'ExitWorktree',
-    'CronCreate', 'CronDelete', 'CronList',
-    'PushNotification', 'RemoteTrigger',
-    // task & tool introspection added in claude 2.1.x — let through and
-    // the agent will burn turns exploring instead of executing
-    'ToolSearch',
-    'Monitor', 'TaskOutput', 'TaskStop',
-    'AskUserQuestion',
-    'ShareOnboardingGuide',
-    // Skills are loaded independently of the --allowedTools allow-list, so an
-    // allow-list of `mcp__playwright` does NOT block the `Skill` tool. Left
-    // through, the agent burns a turn "checking for a project skill first" and
-    // pollutes the crystallized spec with a junk `When · Skill` step. Deny it.
-    'Skill',
-    // Playwright MCP's arbitrary-JS tools. browser_run_code_unsafe /
-    // browser_evaluate run any JS in the page — a real prompt-injection exfil
-    // path (fetch a token out, read localStorage) that punches through the
-    // "Playwright MCP only" sandbox, and their output can't be translated into
-    // a deterministic Playwright spec anyway (it lands as a `// TODO`). Agents
-    // drive via click/fill/select and read state via snapshot instead.
-    'mcp__playwright__browser_run_code_unsafe',
-    'mcp__playwright__browser_evaluate',
-];
-export const claudeAgent = {
-    id: 'claude',
-    binName: 'claude',
-    protocol: 'argv',
-    streamFormat: 'stream-json',
-    sandboxStrength: 'hard',
-    defaultDisallowedTools: CLAUDE_DEFAULT_DISALLOWED_TOOLS,
-    apiKeyEnv: 'ANTHROPIC_API_KEY',
-    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');
-        args.push('--permission-mode', 'dontAsk');
-        if (opts.mcpConfig) {
-            args.push('--mcp-config', opts.mcpConfig, '--strict-mcp-config');
-        }
-        if (opts.allowedTools?.length) {
-            args.push('--allowedTools', ...opts.allowedTools);
-        }
-        if (opts.disallowedTools?.length) {
-            args.push('--disallowedTools', ...opts.disallowedTools);
-        }
-        if (opts.maxBudgetUsd != null) {
-            args.push('--max-budget-usd', String(opts.maxBudgetUsd));
-        }
-        if (opts.model) {
-            args.push('--model', opts.model);
-        }
-        if (opts.sessionId) {
-            args.push('--resume', opts.sessionId);
-        }
-        if (opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0) {
-            args.push('--append-system-prompt', opts.appendSystemPrompt);
-        }
-        return args;
-    },
-    parseEvent(line, state = {}) {
-        if (!line.trim())
-            return [];
-        let ev;
-        try {
-            ev = JSON.parse(line);
-        }
-        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.
-            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 });
-            }
-            for (const server of ev.mcp_servers ?? []) {
-                out.push({ kind: 'mcp_status', server: server.name, status: server.status });
-            }
-            return out;
-        }
-        if (ev.type === 'assistant') {
-            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') {
-                s.runningCost = ev.total_cost_usd;
-            }
-            else if (ev.message?.usage) {
-                s.runningCost += estimateCostUsd(s.runningModel ?? ev.message.model, ev.message.usage);
-            }
-            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 ?? '';
-                    const tool = name.replace(/^mcp__playwright__/, '');
-                    out.push({
-                        kind: 'tool_use',
-                        tool,
-                        input: block.input,
-                        costUsdSnapshot: s.runningCost,
-                    });
-                }
-                else if (block.type === 'text') {
-                    const text = block.text?.trim();
-                    if (text)
-                        out.push({ kind: 'text', text });
-                }
-            }
-            return out;
-        }
-        if (ev.type === 'user') {
-            for (const block of ev.message?.content ?? []) {
-                if (block.type === 'tool_result') {
-                    out.push({ kind: 'tool_result', isError: block.is_error });
-                }
-            }
-            return out;
-        }
-        if (ev.type === 'result') {
-            out.push({
-                kind: 'session_end',
-                turns: ev.num_turns,
-                costUsd: ev.total_cost_usd,
-                isError: ev.is_error,
-                summary: ev.result,
-            });
-            return out;
-        }
-        return [];
-    },
-};

package/dist/agents/codex.d.ts

@@ -1,19 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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;AAoK3F,eAAO,MAAM,UAAU,EAAE,eA6JxB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}