@hover-dev/core 0.14.1 → 0.16.0

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;
@@ -40,5 +46,10 @@ export declare function resolveMcpConfig(opts: {
     /** Suffix for the output filename so multiple parallel configs from
      *  the same service (e.g. mode toggle round-trips) don't share state. */
     suffix?: string;
+    /** Project root to resolve `@playwright/mcp` from. Defaults to
+     *  `process.cwd()`. `hover run --cwd apps/web` passes the target workspace
+     *  so a monorepo that installed `@hover-dev/core` only under that app (not
+     *  the repo root the CLI was invoked from) still resolves the MCP package. */
+    cwd?: string;
 }): string;
 //# sourceMappingURL=resolveMcpConfig.d.ts.map

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;CACjB,GAAG,MAAM,CAgDT"}
+{"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"}

package/dist/playwright/resolveMcpConfig.js

@@ -3,6 +3,14 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import process from 'node:process';
+/** 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 function mcpToolPrefix(serverId) {
+    return `mcp__${serverId.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')}`;
+}
 export function resolveMcpConfig(opts) {
     // Resolve the package's main file, then walk back to its package root.
     // Using `package.json` as the resolution target is the documented
@@ -19,7 +27,8 @@ export function resolveMcpConfig(opts) {
     // can't actually load. `process.cwd()` is the user's project root,
     // and `@playwright/mcp` is always reachable from there because it's
     // a declared dependency of `@hover-dev/core`, which the user installed.
-    const require = createRequire(resolve(process.cwd(), 'package.json'));
+    // The caller may override with an explicit `cwd` (e.g. `hover run --cwd`).
+    const require = createRequire(resolve(opts.cwd ?? process.cwd(), 'package.json'));
     const pkgJsonPath = require.resolve('@playwright/mcp/package.json');
     const pkgRoot = dirname(pkgJsonPath);
     // The package's `bin` map declares "playwright-mcp": "cli.js" — we
@@ -45,8 +54,13 @@ export function resolveMcpConfig(opts) {
     const config = { mcpServers };
     const outDir = resolve(tmpdir(), 'hover');
     mkdirSync(outDir, { recursive: true });
-    const suffix = opts.suffix ? `-${opts.suffix}` : '';
-    const outPath = resolve(outDir, `mcp-config-${opts.port}${suffix}.json`);
+    // Sanitise the suffix before it lands in a filesystem path — it's derived
+    // from plugin/mode ids, so guard against path separators and other unsafe
+    // characters slipping into the filename.
+    const safeSuffix = opts.suffix
+        ? `-${opts.suffix.replace(/[^a-zA-Z0-9._-]+/g, '_')}`
+        : '';
+    const outPath = resolve(outDir, `mcp-config-${opts.port}${safeSuffix}.json`);
     writeFileSync(outPath, JSON.stringify(config, null, 2), 'utf-8');
     return outPath;
 }

package/dist/plugin-api.d.ts

@@ -40,6 +40,13 @@ export interface HoverPluginMode {
     /** Mode ids this mode cannot be active alongside. Two plugins both
      *  needing an exclusive proxy would set each other here. */
     conflictsWith?: string[];
+    /** CSS colour the widget tints to while this mode is engaged — the mode
+     *  bar, launcher, and panel chrome all retint to it. Any CSS colour the
+     *  user's Chrome accepts (the widget derives the dim/hover/ink/tint shades
+     *  from it via `color-mix`). Defaults to security orange (`#fb923c`) when
+     *  omitted, so a plugin only sets this to stand apart — e.g. pentest's
+     *  `#ef4444` red signalling "offensive mode". */
+    accent?: string;
 }
 export interface HoverPluginMcpServer {
     /** Stable, namespaced id (`@hover-dev/security:flows`). Host enforces

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

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

package/dist/runSession.d.ts

@@ -0,0 +1,42 @@
+import type { InvokeEvent } from './agents/types.js';
+import type { SkillStep } from './skills/writeSkill.js';
+export interface RunSessionOptions {
+    prompt: string;
+    agentId: string;
+    /** CDP URL of the debug Chrome the agent drives. Required unless `mcpConfig`
+     *  is supplied (the service passes a pre-built config; the CLI passes this). */
+    cdpUrl?: string;
+    model?: string;
+    maxBudgetUsd?: number;
+    /** Optional model API key, injected into the spawned CLI's env. */
+    apiKey?: string;
+    /** Agent cwd (project root) — where Claude Code reads CLAUDE.md and where a
+     *  `--save` / re-record writes the spec. Defaults to the process cwd. */
+    cwd?: string;
+    /** Namespaces the temp MCP config filename. Defaults to 51789. */
+    port?: number;
+    signal?: AbortSignal;
+    /** Pre-built MCP config path. The service supplies one (with plugin servers);
+     *  when omitted, runSession builds a plugin-free Playwright config from
+     *  `cdpUrl` via resolveMcpConfig. */
+    mcpConfig?: string;
+    /** Extra hard-sandbox allow-list prefixes — e.g. active-mode plugin MCP
+     *  server ids the service contributes. Appended to ['mcp__playwright']. */
+    allowedToolsExtra?: string[];
+    /** Appended to the agent's system prompt (the service folds in cdpHint +
+     *  conventions + plugin additions + a language directive; the CLI omits it). */
+    appendSystemPrompt?: string;
+    /** Resume an existing agent session (a follow-up turn). */
+    sessionId?: string;
+}
+export interface RunSessionResult {
+    /** Captured session as SpecStep[] (`user` → `step`* → `done`), ready to hand
+     *  straight to `writeSpec`. */
+    steps: SkillStep[];
+    /** The agent's final summary, if any. */
+    summary: string;
+    /** True if the run ended in error or was aborted. */
+    isError: boolean;
+}
+export declare function runSession(opts: RunSessionOptions, onEvent: (ev: InvokeEvent) => void): Promise<RunSessionResult>;
+//# sourceMappingURL=runSession.d.ts.map

package/dist/runSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runSession.d.ts","sourceRoot":"","sources":["../src/runSession.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;oFACgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;6EACyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;yCAEqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+EAC2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;oFACgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;mCAC+B;IAC/B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,GACjC,OAAO,CAAC,gBAAgB,CAAC,CA4D3B"}

package/dist/runSession.js

@@ -0,0 +1,81 @@
+/**
+ * Headless session runner — the invoke + crystallize engine shared by every
+ * frontend. The widget reaches it through the WebSocket service; `smoke.ts`
+ * and (future) `hover run` call it in-process, no WS server. It spawns the
+ * agent against the user's debug Chrome over CDP, streams normalized events to
+ * `onEvent`, and accumulates the captured tool calls into a `SpecStep[]` the
+ * caller can hand to `writeSpec` — `user` seed → `step` per tool_use → `done`
+ * with the final summary (the exact shape the spec pipeline consumes).
+ *
+ * No WebSocket, no DOM. It drives an *already-running* debug Chrome over CDP;
+ * launching Chrome / CDP preflight is the caller's call (the service does it
+ * with autoLaunch; the CLI will too). The sandbox (allow/deny tools) mirrors
+ * the service exactly, gated on the agent's `sandboxStrength`.
+ *
+ * The full surface (mcpConfig override, allowedToolsExtra, appendSystemPrompt,
+ * sessionId) lets the service delegate to this instead of duplicating the
+ * invoke loop; the CLI uses only the small subset (prompt + cdpUrl + model).
+ */
+import { invokeAgent } from './agents/invoke.js';
+import { getAgent } from './agents/registry.js';
+import { resolveMcpConfig } from './playwright/resolveMcpConfig.js';
+export async function runSession(opts, onEvent) {
+    const descriptor = getAgent(opts.agentId);
+    const isHardSandbox = descriptor?.sandboxStrength === 'hard';
+    // Seed with a synthetic `user` step so writeSpec's JSDoc `Original prompt:`
+    // line carries the prompt the agent was given (mirrors the service path).
+    const steps = [{ kind: 'user', text: opts.prompt }];
+    let summary = '';
+    let isError = false;
+    const mcpConfig = opts.mcpConfig ??
+        resolveMcpConfig({
+            cdpUrl: opts.cdpUrl ?? 'http://localhost:9222',
+            port: opts.port ?? 51789,
+            // Resolve @playwright/mcp from the run's cwd, not the dir the CLI was
+            // invoked from — `hover run --cwd apps/web` must find the MCP package
+            // under the target workspace in a monorepo.
+            cwd: opts.cwd,
+        });
+    for await (const ev of invokeAgent({
+        agentId: opts.agentId,
+        prompt: opts.prompt,
+        sessionId: opts.sessionId,
+        mcpConfig,
+        cwd: opts.cwd,
+        appendSystemPrompt: opts.appendSystemPrompt,
+        // Hard sandbox: only Playwright MCP (+ any active-mode plugin servers) is
+        // callable, every built-in tool denied — a hijacked prompt can't reach the
+        // shell or filesystem. Soft agents (codex, …) enforce their own sandbox via
+        // buildArgs, so the lists stay undefined for them — exactly what the
+        // service does.
+        allowedTools: isHardSandbox
+            ? ['mcp__playwright', ...(opts.allowedToolsExtra ?? [])]
+            : undefined,
+        disallowedTools: isHardSandbox
+            ? (descriptor?.defaultDisallowedTools ? [...descriptor.defaultDisallowedTools] : undefined)
+            : undefined,
+        maxBudgetUsd: opts.maxBudgetUsd,
+        model: opts.model,
+        apiKey: opts.apiKey,
+        signal: opts.signal,
+    })) {
+        onEvent(ev);
+        if (ev.kind === 'tool_use') {
+            steps.push({ kind: 'step', tool: ev.tool, input: ev.input });
+        }
+        else if (ev.kind === 'session_end') {
+            if (ev.summary)
+                summary = ev.summary;
+            if (ev.isError)
+                isError = true;
+        }
+    }
+    // On abort (opts.signal), invokeAgent SIGTERMs the child and no session_end
+    // arrives, so the error flag above never gets set. Honour the doc contract
+    // ("True if the run ended in error or was aborted") by flipping it here.
+    if (opts.signal?.aborted)
+        isError = true;
+    if (summary)
+        steps.push({ kind: 'done', summary });
+    return { steps, summary, isError };
+}

package/dist/service/cdpHandlers.d.ts

@@ -14,13 +14,9 @@ import type { WebSocket } from 'ws';
 import { type LaunchOptions } from '../playwright/launchChrome.js';
 import { type ClientMessage } from './types.js';
 /** Extra launch options surfaced from the active mode (security plugin
- *  needs proxy + spki + separate profile + non-default CDP port). When
- *  none are set, behaviour is identical to pre-v0.7 normal-mode launch. */
-export type LaunchExtras = Pick<LaunchOptions, 'userDataDir' | 'proxy'> & {
-    /** Override CDP port (mode-specific, e.g. 9333 for security). When set,
-     *  this also wins over the `port` parsed from cdpUrl. */
-    cdpPort?: number;
-};
+ *  needs a resident proxy + spki). When none are set, behaviour is identical
+ *  to pre-v0.7 normal-mode launch. */
+export type LaunchExtras = Pick<LaunchOptions, 'proxy'>;
 /**
  * "Is this widget running inside the debug Chrome?" The widget asks this on
  * connect (and after every status-changing event) so it can render itself as

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

@@ -1 +1 @@
-{"version":3,"file":"cdpHandlers.d.ts","sourceRoot":"","sources":["../../src/service/cdpHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD;;2EAE2E;AAC3E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG;IACxE;6DACyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAaf"}
+{"version":3,"file":"cdpHandlers.d.ts","sourceRoot":"","sources":["../../src/service/cdpHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD;;sCAEsC;AACtC,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/service/cdpHandlers.js

@@ -27,10 +27,7 @@ export async function handleCheckCdp(ws, msg, cdpUrl, extras) {
         send(ws, { type: 'error', payload: { message: 'check-cdp: pageUrl is required' } });
         return;
     }
-    const effectiveCdpUrl = extras?.cdpPort
-        ? `http://localhost:${extras.cdpPort}`
-        : cdpUrl;
-    const status = await checkCdpStatus(effectiveCdpUrl, pageUrl);
+    const status = await checkCdpStatus(cdpUrl, pageUrl);
     send(ws, { type: 'cdp-status', payload: status });
 }
 /**
@@ -48,7 +45,7 @@ export async function handleLaunchChrome(ws, msg, cdpUrl, extras) {
     // Tell the widget we're launching so it can render a spinner immediately —
     // findChromeBinary + spawn + ready-poll can take a few seconds.
     send(ws, { type: 'cdp-status', payload: { state: 'no-cdp', launching: true } });
-    const port = extras?.cdpPort ?? (() => {
+    const port = (() => {
         try {
             return Number(new URL(cdpUrl).port) || 9222;
         }
@@ -59,19 +56,13 @@ export async function handleLaunchChrome(ws, msg, cdpUrl, extras) {
     const result = await launchDebugChrome({
         url: pageUrl,
         port,
-        userDataDir: extras?.userDataDir,
         proxy: extras?.proxy,
     });
     if (!result.ok) {
         send(ws, { type: 'cdp-status', payload: { state: 'no-cdp', reason: result.reason } });
         return;
     }
-    // Re-check status against the port we actually launched on, so a mode-
-    // specific port (9333 for security) doesn't get probed at 9222.
-    const effectiveCdpUrl = extras?.cdpPort
-        ? `http://localhost:${extras.cdpPort}`
-        : cdpUrl;
-    const status = await checkCdpStatus(effectiveCdpUrl, pageUrl);
+    const status = await checkCdpStatus(cdpUrl, pageUrl);
     send(ws, { type: 'cdp-status', payload: status });
 }
 /**
@@ -87,10 +78,7 @@ export async function handleFocusDebug(ws, msg, cdpUrl, extras) {
         send(ws, { type: 'error', payload: { message: 'focus-debug: pageUrl is required' } });
         return;
     }
-    const effectiveCdpUrl = extras?.cdpPort
-        ? `http://localhost:${extras.cdpPort}`
-        : cdpUrl;
-    const result = await focusDebugTab(effectiveCdpUrl, pageUrl);
+    const result = await focusDebugTab(cdpUrl, pageUrl);
     if (!result.ok) {
         send(ws, { type: 'error', payload: { message: `focus-debug: ${result.reason}` } });
     }

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

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

package/dist/service/cdpHint.js

@@ -45,17 +45,24 @@ export function buildCdpHint(tabs) {
     return [
         `Your job — read this first:`,
         ``,
-        `  You are an end-to-end testing agent. Your standing mission is to drive`,
-        `  the user's web app through the browser, EXERCISE its interactive`,
-        `  surface, and report bugs or unexpected behaviour.`,
-        ``,
-        `  If the user's prompt is specific ("log in as alice and add a todo"),`,
-        `  do that and verify the outcome.`,
-        ``,
-        `  If the user's prompt is vague or short ("test", "check", "see if it`,
-        `  works", "find bugs", or a single word), DO NOT ask for clarification`,
-        `  and DO NOT just take a snapshot and call it done. Run a real`,
-        `  exploratory test pass:`,
+        `  You are an end-to-end testing agent. Match the scope of your run to how`,
+        `  specific the user's prompt is — do NOT over-test.`,
+        ``,
+        `  SPECIFIC prompt — it names a flow or action ("log in as alice and add a`,
+        `  todo", "test the login flow", "只测试登录"): do EXACTLY that flow and`,
+        `  verify its outcome, then STOP. Stay inside the named scope. Do NOT wander`,
+        `  into adjacent flows, extra edge cases (empty/invalid input, boundary`,
+        `  values), logout, or bug-hunting unless the prompt explicitly asks. A`,
+        `  focused run that does what was asked and asserts the result is the goal,`,
+        `  not breadth — one clean verified flow is a complete, successful result.`,
+        `  But if you DO hit a real problem while doing the asked flow — a broken`,
+        `  button, a wrong message, a console error, a failed verification — still`,
+        `  report it under ## Findings. Don't go hunting for more; just don't swallow`,
+        `  what you ran into.`,
+        ``,
+        `  VAGUE or short prompt ("test", "check", "see if it works", "find bugs",`,
+        `  or a single word): DO NOT ask for clarification and DO NOT just take a`,
+        `  snapshot and call it done. Run a real exploratory test pass:`,
         ``,
         `    1. browser_snapshot to learn the app's structure.`,
         `    2. Identify the main interactive surfaces (forms, buttons, links,`,
@@ -68,9 +75,8 @@ export function buildCdpHint(tabs) {
         `       confusing in the final summary's "## Findings" section.`,
         ``,
         `  A short "App is running fine" reply after one snapshot is NOT an`,
-        `  acceptable result. Either the app actually works and you ran several`,
-        `  flows to confirm it, or you found something interesting — those are`,
-        `  the only two valid outcomes of a vague prompt.`,
+        `  acceptable result for a vague prompt — either the app works and you ran`,
+        `  several flows to confirm it, or you found something interesting.`,
         ``,
         `The user's Chrome currently has these tabs open:`,
         ...tabs.map(t => `  - ${t.url}${t.title ? `  (${t.title})` : ''}`),
@@ -140,6 +146,16 @@ export function buildCdpHint(tabs) {
         `     postMessage listener or auth refresh"); do NOT browser_navigate to`,
         `     same-origin to force a refresh (rule #2 still applies).`,
         ``,
+        `Tool usage — operate and verify through the structured Playwright tools:`,
+        ``,
+        `  8. Drive the page only with click / fill / select / snapshot / wait. Do`,
+        `     NOT use browser_run_code_unsafe or browser_evaluate to run JavaScript`,
+        `     — they are disabled, and any action taken in raw JS cannot be`,
+        `     crystallized into a deterministic Playwright spec (it is dropped as a`,
+        `     TODO). To VERIFY an outcome, assert on what browser_snapshot shows —`,
+        `     a heading, an error message, a counter value; the accessibility tree`,
+        `     already exposes the text and roles you need.`,
+        ``,
         `Narration format — affects how the widget renders your run for the user:`,
         ``,
         `  Before each LOGICAL STEP (a coherent unit of work like "Open the login`,

package/dist/service/conventions.d.ts

@@ -0,0 +1,8 @@
+/** Max characters of the conventions file folded into the prompt. */
+export declare const CONVENTIONS_MAX_CHARS = 4000;
+/**
+ * Read `<projectRoot>/.hover/conventions.md` and return it wrapped as a
+ * system-prompt block, or null when the file is absent or empty.
+ */
+export declare function readConventions(projectRoot: string, maxChars?: number): Promise<string | null>;
+//# sourceMappingURL=conventions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../../src/service/conventions.ts"],"names":[],"mappings":"AAgBA,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;GAGG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,SAAwB,GAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqBxB"}

package/dist/service/conventions.js

@@ -0,0 +1,42 @@
+/**
+ * Knowledge layer (F5): the project's testing conventions, injected into the
+ * agent's system prompt so the developer can steer *how it explores* — which
+ * flows matter, where login lives, the preferred selector attribute.
+ *
+ * Read by the SERVICE (not the agent) from `<projectRoot>/.hover/conventions.md`
+ * and folded into the system prompt — the agent never gains a file-read tool
+ * (D2). This shapes exploration only; it does NOT change how the saved spec is
+ * generated (that's the translator's job — D9).
+ *
+ * Capped to avoid prompt bloat, and injected on the FIRST turn only (it's
+ * static, like cdpHint's rules) so it doesn't fragment the prompt cache.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Max characters of the conventions file folded into the prompt. */
+export const CONVENTIONS_MAX_CHARS = 4000;
+/**
+ * Read `<projectRoot>/.hover/conventions.md` and return it wrapped as a
+ * system-prompt block, or null when the file is absent or empty.
+ */
+export async function readConventions(projectRoot, maxChars = CONVENTIONS_MAX_CHARS) {
+    let raw;
+    try {
+        raw = await readFile(join(projectRoot, '.hover', 'conventions.md'), 'utf-8');
+    }
+    catch {
+        return null; // no conventions file — nothing to inject
+    }
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const body = trimmed.length > maxChars ? `${trimmed.slice(0, maxChars)}\n…(truncated)` : trimmed;
+    return [
+        `Project testing conventions — the developer's house rules for this app,`,
+        `from .hover/conventions.md. Use them while EXPLORING (which flows matter,`,
+        `where login lives, preferred selectors, test data). They guide exploration`,
+        `only — they do not change how the saved spec is generated.`,
+        ``,
+        body,
+    ].join('\n');
+}