@hover-dev/core 0.15.0 → 0.16.0

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/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,eA0JxB,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;
@@ -128,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') {
@@ -158,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/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/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":""}

package/dist/mcp/sourceServer.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Hover source-reader MCP server — the runtime behind the opt-in `codeContext`
+ * switch. Spawned by the agent (Claude Code / Codex) as a stdio subprocess when
+ * codeContext is enabled, in addition to Playwright MCP. It gives the agent
+ * READ-ONLY, fenced access to the project's source so it can author smarter
+ * tests and do white-box security/pentest work (read the actual query / authz
+ * check, not just the rendered DOM).
+ *
+ * This is the ONE place Hover relaxes "the agent only touches the browser", so
+ * the safety is all in the fence (src/mcp/sourceFence.ts) + the guards here:
+ *   - every path is resolved INSIDE the project root (no `..` / absolute escape)
+ *   - a realpath re-check defeats symlink escape
+ *   - secret / VCS / dependency / build files are refused (.env, keys, .git, …)
+ *   - read-only: there is no write / exec / delete tool here
+ *   - a size cap + a binary guard keep it to actual source
+ *
+ * The project root comes in via env:
+ *   HOVER_PROJECT_ROOT   absolute path to the dev project root (devRoot)
+ *
+ * Tools exposed:
+ *   read_source({ path })            → the file's text (fenced, ≤256 KB, text-only)
+ *   list_source({ subdir? })         → a shallow dir listing (secrets filtered out)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readFileSync, realpathSync, statSync, readdirSync } from 'node:fs';
+import { resolveSourcePath, isWithinRoot } from './sourceFence.js';
+const root = process.env.HOVER_PROJECT_ROOT;
+if (!root) {
+    process.stderr.write('[hover-source-mcp] HOVER_PROJECT_ROOT must be set by the host.\n');
+    process.exit(1);
+}
+const ROOT = root;
+const MAX_BYTES = 256 * 1024;
+function md(text) {
+    return { content: [{ type: 'text', text }] };
+}
+const server = new McpServer({ name: 'hover-source', version: '0.0.0' });
+server.registerTool('read_source', {
+    description: "Read a source file from THIS project (read-only). Pass a repo-relative path (e.g. the one in an element's data-hover-source, `src/app/login.tsx:42` → path `src/app/login.tsx`). Fenced to the project root: paths that escape it, or that name secrets / keys / .env / .git / node_modules / build output, are refused. Use this to write tests against the real selectors & routes, or — in security/pentest mode — to confirm a finding against the actual server code (the SQL query, the authz check). You cannot write, run, or delete anything.",
+    inputSchema: {
+        path: z.string().describe('Repo-relative path to a source file, e.g. "src/api/orders.ts".'),
+    },
+}, async ({ path }) => {
+    const f = resolveSourcePath(ROOT, path);
+    if (!f.ok)
+        return md(`✗ ${f.reason}`);
+    let real;
+    try {
+        real = realpathSync(f.abs);
+    }
+    catch {
+        return md(`✗ not found: ${f.rel}`);
+    }
+    if (!isWithinRoot(ROOT, real))
+        return md(`✗ refused: "${f.rel}" resolves (via a symlink) outside the project root`);
+    let st;
+    try {
+        st = statSync(real);
+    }
+    catch {
+        return md(`✗ not found: ${f.rel}`);
+    }
+    if (st.isDirectory())
+        return md(`✗ "${f.rel}" is a directory — use list_source`);
+    if (st.size > MAX_BYTES)
+        return md(`✗ "${f.rel}" is ${Math.round(st.size / 1024)} KB — too large to read (cap ${MAX_BYTES / 1024} KB)`);
+    let buf;
+    try {
+        buf = readFileSync(real);
+    }
+    catch (e) {
+        return md(`✗ could not read ${f.rel}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Binary guard — a NUL byte in the first 8 KB means it isn't source text.
+    if (buf.subarray(0, 8192).includes(0))
+        return md(`✗ "${f.rel}" looks binary — refused`);
+    return md(`\`\`\`\n// ${f.rel}\n${buf.toString('utf-8')}\n\`\`\``);
+});
+server.registerTool('list_source', {
+    description: 'List the entries of a directory in THIS project (shallow, read-only). Omit `subdir` for the project root. Secret / VCS / dependency / build entries are filtered out. Use it to discover what source exists before reading a file.',
+    inputSchema: {
+        subdir: z.string().optional().describe('Repo-relative directory, e.g. "src/api". Omit for the root.'),
+    },
+}, async ({ subdir }) => {
+    let dirAbs = ROOT;
+    let base = '';
+    if (subdir && subdir.trim() && subdir.trim() !== '.') {
+        const d = resolveSourcePath(ROOT, subdir);
+        if (!d.ok)
+            return md(`✗ ${d.reason}`);
+        dirAbs = d.abs;
+        base = d.rel;
+    }
+    let entries;
+    try {
+        entries = readdirSync(dirAbs, { withFileTypes: true });
+    }
+    catch {
+        return md(`✗ not a readable directory: ${base || '.'}`);
+    }
+    const rows = [];
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const rel = base ? `${base}/${e.name}` : e.name;
+        // Filter via the same fence so secrets/build/VCS never even show up.
+        if (!resolveSourcePath(ROOT, rel).ok)
+            continue;
+        rows.push(e.isDirectory() ? `${rel}/` : rel);
+    }
+    if (rows.length === 0)
+        return md(`(empty or fully filtered) ${base || '.'}`);
+    return md(`${base || '.'} —\n${rows.join('\n')}`);
+});
+await server.connect(new StdioServerTransport());

package/dist/playwright/preflight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/playwright/preflight.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ1E;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,EAAE,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,SAAS,SAAO,GACf,OAAO,CAAC,kBAAkB,CAAC,CAiD7B"}
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/playwright/preflight.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ1E;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,EAAE,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,SAAS,SAAO,GACf,OAAO,CAAC,kBAAkB,CAAC,CAsD7B"}

package/dist/playwright/preflight.js

@@ -32,12 +32,15 @@ export async function preflightCDP(cdpUrl, timeoutMs = 2000) {
         });
     }
     catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
         return {
             ok: false,
-            reason: `Chrome debug session not detected at ${cdpUrl}. Click the ✨ launcher in the widget to start it, or run \`pnpm exec hover-chrome\` (npx hover-chrome).`,
+            reason: `Chrome debug session not detected at ${cdpUrl} (${msg}). Click the ✨ launcher in the widget to start it, or run \`pnpm exec hover-chrome\` (npx hover-chrome).`,
         };
     }
     if (!versionRes.ok) {
+        // Drain the keep-alive socket — we won't read the body on the error path.
+        await versionRes.body?.cancel();
         return { ok: false, reason: `CDP returned HTTP ${versionRes.status}` };
     }
     let versionJson;
@@ -62,6 +65,8 @@ export async function preflightCDP(cdpUrl, timeoutMs = 2000) {
         else {
             // /json/version was healthy but /json/list wasn't — surface it so the
             // agent's system prompt isn't silently built from an empty tab list.
+            // Drain the keep-alive socket since we won't read the body here.
+            await listRes.body?.cancel();
             console.warn(`[hover] CDP /json/list returned HTTP ${listRes.status}; agent tab hint will be empty`);
         }
     }

package/dist/playwright/raiseWindow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raiseWindow.d.ts","sourceRoot":"","sources":["../../src/playwright/raiseWindow.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8BrE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwClE"}
+{"version":3,"file":"raiseWindow.d.ts","sourceRoot":"","sources":["../../src/playwright/raiseWindow.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8BrE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDlE"}

package/dist/playwright/raiseWindow.js

@@ -77,9 +77,28 @@ export async function raiseChromeWindow(pid) {
         if (os === 'linux') {
             // wmctrl is the most common helper for X11; not always installed,
             // but the alternative (xdotool) needs the same dependency story.
-            // We try wmctrl with the PID match; if it isn't installed the
-            // outer try/catch swallows the ENOENT and we degrade gracefully.
-            await runDetached('wmctrl', ['-ia', String(pid)]);
+            // If it isn't installed the runCapture/runDetached calls swallow the
+            // ENOENT and we degrade gracefully.
+            //
+            // `wmctrl -i` expects an X11 WINDOW id, NOT a unix PID, so we first
+            // map PID → window id. `wmctrl -l -p` lists windows with their owning
+            // PID in the third column:
+            //   0x03c00007  0 12345  hostname  Title…
+            const listing = await runCapture('wmctrl', ['-l', '-p']);
+            if (!listing)
+                return;
+            let windowId = null;
+            for (const line of listing.split('\n')) {
+                // columns: <window-id> <desktop> <pid> <host> <title…>
+                const m = line.match(/^(0x[0-9a-fA-F]+)\s+\S+\s+(\d+)\s/);
+                if (m && Number(m[2]) === pid) {
+                    windowId = m[1];
+                    break;
+                }
+            }
+            if (!windowId)
+                return; // no matching window — no-op gracefully
+            await runDetached('wmctrl', ['-ia', windowId]);
             return;
         }
         if (os === 'win32') {

package/dist/playwright/resolveMcpConfig.d.ts

@@ -26,6 +26,12 @@ export interface ExtraMcpServer {
     args?: string[];
     env?: Record<string, string>;
 }
+/** The `mcp__<id>` tool-name prefix Claude Code exposes a plugin MCP server's
+ *  tools under: non-alphanumerics collapse to `_` and edges are trimmed (e.g.
+ *  `@hover-dev/security:flows` → `mcp__hover_dev_security_flows`). Used to build
+ *  the hard-sandbox allow-list. Single source so the service and the CLI scan
+ *  command can't drift on how the prefix is derived. */
+export declare function mcpToolPrefix(serverId: string): string;
 export declare function resolveMcpConfig(opts: {
     /** CDP URL passed to the MCP server's `--cdp-endpoint` flag. */
     cdpUrl: string;

package/dist/playwright/resolveMcpConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveMcpConfig.d.ts","sourceRoot":"","sources":["../../src/playwright/resolveMcpConfig.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B;2EACuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;2CAIuC;IACvC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;kFAG8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAiDT"}
+{"version":3,"file":"resolveMcpConfig.d.ts","sourceRoot":"","sources":["../../src/playwright/resolveMcpConfig.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B;2EACuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;wDAIwD;AACxD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;2CAIuC;IACvC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;kFAG8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAsDT"}