@hover-dev/core 0.14.1 → 0.16.0

package/README.md

@@ -26,6 +26,78 @@ The local Node service. Owns:
 
 To add an agent: implement an `AgentDescriptor`, register it in `registry.ts`. Done.
 
+## Spec generation (specs/)
+
+A verified session crystallizes into a standard `@playwright/test` file under
+`<devRoot>/__vibe_tests__/`. Translation is **deterministic — no LLM on the
+per-save path** (reproducible by construction):
+
+- `writeSpec.ts` walks the captured `browser_*` actions and emits one Playwright
+  call each (`getByRole` / `getByLabel` / `getByText` selectors — never XPath).
+  A few high-frequency multi-action shapes are hardcoded (popup / new-tab →
+  `Promise.all([context.waitForEvent('page'), …click()])`). An action with no
+  single-step translation (file upload, drag, …) leaves a structured
+  `// hover:optimizable: <tool>` marker rather than a `// TODO` — the draft stays
+  runnable around it. `countOptimizableMarkers()` reads the count back; `listSpecs`
+  surfaces it as `SpecSummary.optimizableCount`.
+- Alongside the `.spec.ts`, a **sidecar** is written to
+  `.hover/<slug>.json` — the structured `SpecStep[]` + observed signals. This is
+  the machine-readable behavior record the optimization pass reads (it keeps the
+  spec itself clean).
+
+### Optional optimization pass (F7)
+
+The **service** (never the sandboxed browser agent) can optionally run an LLM
+**codegen** call over a draft to polish it — chiefly to add assertions for the
+feedback the session observed. Its input is data the service already holds (the
+draft + sidecar + relevant seeds), not live page content, so it sits outside the
+agent's prompt-injection surface and needs no filesystem access. It writes an
+**optimization candidate** to `.hover/optimized/<slug>.spec.ts.draft` (never
+`*.spec.ts`, so the test runner can't collect an unreviewed candidate). A human
+promotes or discards it via diff — **the deterministic original is always
+preserved**. Off by default.
+
+### Seed library — extending translation (`.hover/rules/`)
+
+The optimization pass generalizes from **seeds**: human-written worked examples
+of "captured steps → the Playwright code they should produce." This is how
+coverage of new multi-step patterns grows **without core changes** — you (or the
+community) drop a JSON file; the pass picks it up as few-shot.
+
+A seed lives at `<projectRoot>/.hover/rules/<name>.json` and matches
+[`src/specs/seed.schema.json`](src/specs/seed.schema.json):
+
+```json
+{
+  "name": "oauth-popup",
+  "signature": ["browser_click", "browser_tabs:select"],
+  "note": "sign in through a provider popup that opens a new tab",
+  "example": {
+    "steps": [
+      { "tool": "browser_click", "element": "Sign in with Google button" },
+      { "tool": "browser_tabs", "action": "select", "idx": 1 }
+    ],
+    "code": "const [popup] = await Promise.all([\n  context.waitForEvent('page'),\n  page.getByRole('button', { name: 'Sign in with Google' }).click(),\n]);\nawait popup.getByLabel('Email').fill('user@example.com');"
+  }
+}
+```
+
+- **`signature`** is a cheap relevance filter only — `relevantSeeds()` keeps a
+  seed if any of its base tools (`browser_tabs:select` → `browser_tabs`) appears
+  in the spec being optimized. It is **not** exact-matched.
+- **`code`** must obey the same rules as generated specs: semantic selectors, no
+  XPath, no `waitForTimeout`.
+- **Built-in seeds** ship in `src/specs/seeds.ts` (`BUILTIN_SEEDS`). The bar to
+  be built-in is high — only **highly certain**, app-agnostic, deterministic
+  patterns qualify (currently just `download`). Semantic / judgement-based
+  optimizations (e.g. *which* feedback text to assert) are not seeds — they're
+  standing instructions in the prompt. Popup is hardcoded in `writeSpec.ts`, not
+  a seed. Speculative or project-specific patterns belong in your own
+  `.hover/rules/`, where the bar is your call.
+
+`readSeeds(projectRoot)` returns built-ins + your `.hover/rules/*.json`
+(malformed files are skipped, not fatal).
+
 ## Smoke test
 
 ```bash
@@ -56,7 +128,7 @@ Environment variables:
 The `claude -p` invocation is locked down so Claude can only drive the browser:
 
 - `--strict-mcp-config` — ignore any MCP servers in `~/.claude/` or `.mcp.json`
-- `--allowedTools mcp__playwright Skill` — only Playwright MCP and the Skill tool are callable
+- `--allowedTools mcp__playwright` — only Playwright MCP is callable
 - `--disallowedTools Bash Edit Write Read Grep Glob Task WebFetch WebSearch EnterWorktree CronCreate …` — every built-in tool explicitly denied (full list in `CLAUDE_DEFAULT_DISALLOWED_TOOLS` in `claude.ts`)
 - `--permission-mode dontAsk` — anything not whitelisted aborts the run
 - `--max-budget-usd <n>` — optional hard $ ceiling per session (no default; pass `maxBudgetUsd` in plugin options or via the CLI flag to enable)

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

@@ -1 +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"}
+{"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,3 +1,4 @@
+import { HOVER_PROMPT_PREFACE } from './shared.js';
 function aiderState(state) {
     if (typeof state.runningLines !== 'number') {
         state.runningLines = 0;
@@ -13,18 +14,9 @@ function resetAiderCounters(s) {
     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(' ');
+// 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.
@@ -76,8 +68,8 @@ export const aiderAgent = {
         // 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;
+            ? `${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.

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,EAA2C,MAAM,YAAY,CAAC;AA6G3F,eAAO,MAAM,WAAW,EAAE,eA0HzB,CAAC"}
+{"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

@@ -60,6 +60,19 @@ const CLAUDE_DEFAULT_DISALLOWED_TOOLS = [
     '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',
@@ -68,6 +81,7 @@ export const claudeAgent = {
     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',

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

@@ -1 +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"}
+{"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"}

package/dist/agents/codex.js

@@ -1,3 +1,4 @@
+import { stripMcpPrefix } from './shared.js';
 /**
  * Pricing per million tokens. Keep in lockstep with claude.ts's table —
  * approximate published OpenAI rates as of 2026. We are deliberately
@@ -16,6 +17,9 @@ const PRICE_PER_M_USD = {
     'gpt-4o': { in: 2.5, out: 10 },
     'gpt-4': { in: 30, out: 60 },
 };
+// `modelHint` is currently always passed as undefined — the parser can't see
+// the invocation's --model — so the default tier below is what gets used. The
+// parameter is kept so a future caller that does have the model id can pass it.
 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.
@@ -28,7 +32,6 @@ 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;
@@ -39,7 +42,6 @@ function codexState(state) {
 function resetCodexCounters(s) {
     s.runningCost = 0;
     s.runningTurns = 0;
-    s.runningModel = undefined;
     s.runningSessionId = undefined;
     s.lastAgentMessage = undefined;
     s.sawErrorEvent = false;
@@ -59,6 +61,7 @@ export const codexAgent = {
     protocol: 'argv',
     streamFormat: 'json-lines',
     sandboxStrength: 'soft',
+    apiKeyEnv: 'OPENAI_API_KEY',
     display: {
         label: 'OpenAI Codex',
         tagline: 'OpenAI — soft sandbox (no built-in tool deny-list)',
@@ -127,7 +130,7 @@ export const codexAgent = {
                 // 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__/, '');
+                const tool = stripMcpPrefix(rawName);
                 out.push({ kind: 'tool_use', tool, input: it.input ?? it.arguments, costUsdSnapshot: s.runningCost });
             }
             else if (it.type === 'command_execution') {
@@ -157,7 +160,10 @@ export const codexAgent = {
         if (ev.type === 'turn.completed') {
             s.runningTurns += 1;
             if (ev.usage) {
-                s.runningCost += estimateCostUsd(s.runningModel, ev.usage);
+                // The parser has no access to the invocation's --model, so we let
+                // estimateCostUsd fall back to its fixed default tier. Cost is a
+                // high-water "should I hit Stop now" signal, not an invoice.
+                s.runningCost += estimateCostUsd(undefined, ev.usage);
             }
             out.push({ kind: 'usage', costUsd: s.runningCost, turns: s.runningTurns });
             return out;

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

@@ -1 +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"}
+{"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;AA2K3F,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

@@ -1,3 +1,4 @@
+import { HOVER_PROMPT_PREFACE, stripMcpPrefix } from './shared.js';
 function cursorState(state) {
     if (typeof state.runningTurns !== 'number') {
         state.runningTurns = 0;
@@ -40,9 +41,7 @@ function extractToolName(tc) {
         null;
     const kindFromKey = wrapperKey ? wrapperKey.replace(/ToolCall$/, '') : 'unknown';
     const rawName = innerName || kindFromKey;
-    const tool = rawName
-        .replace(/^mcp__playwright__/, '')
-        .replace(/^mcp__hover-playwright__/, '');
+    const tool = stripMcpPrefix(rawName);
     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) ||
@@ -62,18 +61,10 @@ function detectToolError(tc) {
         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(' ');
+// The closest analogue Cursor has to claude's --append-system-prompt or
+// codex's developer_instructions is prepending the standing HOVER-mode
+// preface (HOVER_PROMPT_PREFACE, from shared.ts) to the user prompt so the
+// agent sees it as the leading instruction. There is no CLI flag for it.
 export const cursorAgent = {
     id: 'cursor',
     binName: 'cursor-agent',
@@ -92,8 +83,8 @@ export const cursorAgent = {
         // 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;
+            ? `${HOVER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : HOVER_PROMPT_PREFACE;
         const finalPrompt = `${preface}\n\n${opts.prompt}`;
         const args = ['-p', finalPrompt];
         // NDJSON streaming output.

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

@@ -1 +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"}
+{"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;AA+J3F,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

@@ -1,3 +1,4 @@
+import { HOVER_PROMPT_PREFACE, stripMcpPrefix } from './shared.js';
 function geminiState(state) {
     if (typeof state.runningTurns !== 'number') {
         state.runningTurns = 0;
@@ -17,11 +18,6 @@ function resetGeminiCounters(s) {
     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
@@ -41,13 +37,6 @@ function extractMessageText(ev) {
     }
     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',
@@ -65,8 +54,8 @@ export const geminiAgent = {
         // 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;
+            ? `${HOVER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : HOVER_PROMPT_PREFACE;
         const finalPrompt = `${preface}\n\n${opts.prompt}`;
         const args = ['-p', finalPrompt];
         // NDJSON streaming output.

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;AAE1E;;;;;;;;GAQG;AACH,wBAAuB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,WAAW,CAAC,CAsElF"}
+{"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;;;;;;;;GAQG;AACH,wBAAuB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,WAAW,CAAC,CA+ElF"}

package/dist/agents/invoke.js

@@ -31,7 +31,16 @@ export async function* invokeAgent(opts) {
         cwd: opts.cwd,
         // Clear CLAUDECODE so spawning `claude` from inside a Claude Code session
         // doesn't trip the nested-session guard. Harmless for other agents.
-        env: { ...process.env, CLAUDECODE: '' },
+        // If the caller supplied an API key and the descriptor names a key env var,
+        // inject it so the CLI runs on the key instead of a logged-in subscription.
+        // The key lives only in this child's env — never logged, never persisted.
+        env: {
+            ...process.env,
+            CLAUDECODE: '',
+            ...(opts.apiKey && descriptor.apiKeyEnv
+                ? { [descriptor.apiKeyEnv]: opts.apiKey }
+                : {}),
+        },
     });
     const onAbort = () => {
         if (!child.killed)

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

@@ -1 +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"}
+{"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;AAoJ3F,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

@@ -1,3 +1,4 @@
+import { HOVER_PROMPT_PREFACE, stripMcpPrefix } from './shared.js';
 function qwenState(state) {
     if (typeof state.runningTurns !== 'number') {
         state.runningTurns = 0;
@@ -17,18 +18,6 @@ function resetQwenCounters(s) {
     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',
@@ -62,8 +51,8 @@ export const qwenAgent = {
         // 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;
+            ? `${HOVER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : HOVER_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.

package/dist/agents/shared.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cross-agent helpers shared by the soft-sandbox descriptors
+ * (codex / cursor / gemini / qwen / aider).
+ *
+ * These agents all need the same two things:
+ *   1. A standing "HOVER-mode" instruction preface that tells the agent to
+ *      drive the browser via the Playwright MCP tools only and not to touch
+ *      its built-in shell / file-edit tools. Each agent injects it through a
+ *      different channel (cursor / gemini / aider prepend it to the prompt,
+ *      qwen passes it via --append-system-prompt, codex via
+ *      `-c developer_instructions=`), so this module owns only the *text*, not
+ *      the injection.
+ *   2. Normalising the `mcp__playwright__` / `mcp__hover-playwright__` prefix
+ *      off a raw tool name so the emitted tool names line up across agents.
+ *
+ * codex deliberately does NOT use HOVER_PROMPT_PREFACE — it keeps its own
+ * wording ("Do NOT call …", "emit a short agent_message summary …") that is
+ * tuned to codex's event vocabulary. See codex.ts.
+ */
+/**
+ * The standing HOVER-mode instruction shared by cursor / gemini / qwen / aider.
+ * codex carries a near-identical but intentionally different variant inline.
+ */
+export declare const HOVER_PROMPT_PREFACE: string;
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names every agent emits. */
+export declare function stripMcpPrefix(raw: string): string;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/agents/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAMtB,CAAC;AAEZ;0DAC0D;AAC1D,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/agents/shared.js

@@ -0,0 +1,35 @@
+/**
+ * Cross-agent helpers shared by the soft-sandbox descriptors
+ * (codex / cursor / gemini / qwen / aider).
+ *
+ * These agents all need the same two things:
+ *   1. A standing "HOVER-mode" instruction preface that tells the agent to
+ *      drive the browser via the Playwright MCP tools only and not to touch
+ *      its built-in shell / file-edit tools. Each agent injects it through a
+ *      different channel (cursor / gemini / aider prepend it to the prompt,
+ *      qwen passes it via --append-system-prompt, codex via
+ *      `-c developer_instructions=`), so this module owns only the *text*, not
+ *      the injection.
+ *   2. Normalising the `mcp__playwright__` / `mcp__hover-playwright__` prefix
+ *      off a raw tool name so the emitted tool names line up across agents.
+ *
+ * codex deliberately does NOT use HOVER_PROMPT_PREFACE — it keeps its own
+ * wording ("Do NOT call …", "emit a short agent_message summary …") that is
+ * tuned to codex's event vocabulary. See codex.ts.
+ */
+/**
+ * The standing HOVER-mode instruction shared by cursor / gemini / qwen / aider.
+ * codex carries a near-identical but intentionally different variant inline.
+ */
+export const HOVER_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(' ');
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names every agent emits. */
+export function stripMcpPrefix(raw) {
+    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
+}

package/dist/agents/types.d.ts

@@ -31,6 +31,11 @@ export interface InvokeOptions {
      *  "the user's current Chrome tab is already on http://localhost:5173/,
      *  don't browser_navigate there". */
     appendSystemPrompt?: string;
+    /** Optional model API key. Injected into the spawned CLI's environment under
+     *  the descriptor's `apiKeyEnv` var (e.g. ANTHROPIC_API_KEY) so a user without
+     *  a logged-in subscription can drive Hover with their own key. Never logged,
+     *  never persisted server-side — held only for the lifetime of the spawn. */
+    apiKey?: string;
     /** Aborts the spawned child if signaled. Used to stop an orphan run when
      *  the WebSocket caller disconnects (e.g. user reloads the dev page). */
     signal?: AbortSignal;
@@ -151,6 +156,12 @@ export interface AgentDescriptor {
      *  per-CLI deny list live alongside its descriptor instead of as a magic
      *  array in the service. Soft-sandbox agents leave this undefined. */
     defaultDisallowedTools?: readonly string[];
+    /** Environment variable this CLI reads its model API key from
+     *  (claude: ANTHROPIC_API_KEY, codex: OPENAI_API_KEY). When set and the
+     *  caller supplies `InvokeOptions.apiKey`, the key is injected into the spawn
+     *  env so the user can run on a raw key instead of a logged-in subscription.
+     *  Undefined for agents that have no API-key env path. */
+    apiKeyEnv?: string;
     buildArgs(opts: InvokeOptions): string[];
     /**
      * Parse a single line of agent stdout into normalised InvokeEvents.

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,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;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;AACrD;;;;;;;;GAQG;GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnH;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;4DACwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;mEAC+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,EAAE,YAAY,CAAC;IAC3B,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,YAAY,CAAC;IACtB;;;0EAGsE;IACtE,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAAC;IACzC;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;IAC7D;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAAC;CAChF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}

package/dist/mcp/sourceFence.d.ts

@@ -0,0 +1,23 @@
+export interface FenceOk {
+    ok: true;
+    /** Absolute, root-anchored path the server may stat/read (after realpath). */
+    abs: string;
+    /** POSIX-style path relative to the root — safe to echo back to the agent. */
+    rel: string;
+}
+export interface FenceErr {
+    ok: false;
+    reason: string;
+}
+/**
+ * Resolve `input` against `root`, refusing anything outside the root or matching
+ * a secret pattern. `input` is treated as relative to the root; an absolute
+ * input is resolved too but will fail the containment check unless it happens to
+ * live under the root (the agent should pass repo-relative paths).
+ */
+export declare function resolveSourcePath(root: string, input: string): FenceOk | FenceErr;
+/** True if a resolved-and-realpathed absolute path is still inside the root.
+ *  The server calls this AFTER realpath to defeat symlink escape (a symlink
+ *  whose lexical path passed resolveSourcePath but points outside the root). */
+export declare function isWithinRoot(root: string, realAbs: string): boolean;
+//# sourceMappingURL=sourceFence.d.ts.map

package/dist/mcp/sourceFence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceFence.d.ts","sourceRoot":"","sources":["../../src/mcp/sourceFence.ts"],"names":[],"mappings":"AAgCA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,IAAI,CAAC;IACT,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;CACb;AACD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAsBjF;AAED;;gFAEgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAInE"}

package/dist/mcp/sourceFence.js

@@ -0,0 +1,75 @@
+/**
+ * The path fence for the opt-in `read_source` capability (codeContext).
+ *
+ * Giving the agent the ability to read source is the ONE place Hover relaxes
+ * its "the agent only touches the browser" rule, so the fence is the whole
+ * security story. It must guarantee, on every call, that a caller-supplied path:
+ *   1. resolves to a location INSIDE the project root (no `..` / absolute-path
+ *      escape — symlink escape is caught by the server's realpath re-check), and
+ *   2. is not a credential / secret / VCS / dependency file.
+ * Pure + lexical so it's exhaustively unit-testable; the server layers a
+ * realpath check + a size/binary guard on top.
+ */
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+/** Files we refuse to read even inside the root — credentials, keys, VCS,
+ *  dependency trees, build caches. Matched against the POSIX-style relative
+ *  path (so `\` on Windows is normalised first). */
+const SECRET_PATTERNS = [
+    /(^|\/)\.env(\.[^/]*)?$/i, //              .env, .env.local, .env.production
+    /(^|\/)\.git(\/|$)/, //                    the git dir
+    /(^|\/)node_modules(\/|$)/, //             dependency tree
+    /(^|\/)\.(next|nuxt|svelte-kit|astro|turbo|cache|output|vercel)(\/|$)/, // build caches
+    /(^|\/)(dist|build|coverage)(\/|$)/, //    build output
+    /\.(pem|key|p12|pfx|crt|cer|der|keystore|jks)$/i, // key / cert material
+    /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.[^/]*)?$/i, // ssh keys
+    /(^|\/)\.(npmrc|netrc|pgpass)$/i, //       token-bearing rc files
+    /(^|\/)\.(ssh|aws|gnupg|gcloud|kube|docker)(\/|$)/i, // credential dirs
+    /(^|\/)secrets?(\/|\.[^/]*$|$)/i, //       a secrets dir, or a secret(s).<ext> file
+    /(^|\/)credentials?(\/|\.[^/]*$|$)/i, //   a credentials dir, or credential(s).<ext>
+    /\.(secret|secrets)$/i,
+];
+/** A path containing a NUL or C0 control char is never a legitimate source file. */
+function hasControlChar(s) {
+    for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) < 0x20)
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve `input` against `root`, refusing anything outside the root or matching
+ * a secret pattern. `input` is treated as relative to the root; an absolute
+ * input is resolved too but will fail the containment check unless it happens to
+ * live under the root (the agent should pass repo-relative paths).
+ */
+export function resolveSourcePath(root, input) {
+    if (typeof input !== 'string' || !input.trim()) {
+        return { ok: false, reason: 'path is required' };
+    }
+    if (hasControlChar(input)) {
+        return { ok: false, reason: 'path contains control characters' };
+    }
+    const rootAbs = resolve(root);
+    const abs = resolve(rootAbs, input);
+    const rel = relative(rootAbs, abs);
+    // Outside the root: relative() returns '' for the root itself, a '..'-prefixed
+    // path for an ancestor/sibling, or an absolute path when on a different drive.
+    if (rel === '' || rel === '..' || rel.startsWith('..' + sep) || rel.startsWith('../') || isAbsolute(rel)) {
+        return { ok: false, reason: 'path escapes the project root' };
+    }
+    const relPosix = rel.split(sep).join('/');
+    for (const pat of SECRET_PATTERNS) {
+        if (pat.test(relPosix)) {
+            return { ok: false, reason: `refused: "${relPosix}" matches an excluded (secret / build / VCS) pattern` };
+        }
+    }
+    return { ok: true, abs, rel: relPosix };
+}
+/** True if a resolved-and-realpathed absolute path is still inside the root.
+ *  The server calls this AFTER realpath to defeat symlink escape (a symlink
+ *  whose lexical path passed resolveSourcePath but points outside the root). */
+export function isWithinRoot(root, realAbs) {
+    const rootAbs = resolve(root);
+    const rel = relative(rootAbs, realAbs);
+    return rel !== '' && rel !== '..' && !rel.startsWith('..' + sep) && !rel.startsWith('../') && !isAbsolute(rel);
+}

package/dist/mcp/sourceServer.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=sourceServer.d.ts.map

package/dist/mcp/sourceServer.d.ts.map

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