@hover-dev/core 0.3.1 → 0.3.3

package/dist/agents/types.d.ts

@@ -68,11 +68,22 @@ export type InvokeEvent = {
     kind: 'usage';
     costUsd?: number;
     turns?: number;
-} | {
+}
+/** End-of-session event. Three terminal states the widget renders distinctly:
+ *
+ *   - normal completion: `isError: false`, no `cancelled` flag
+ *   - agent / runtime failure: `isError: true`, no `cancelled` flag
+ *   - user-initiated stop: `cancelled: true` (and we leave `isError: false`
+ *     so downstream "did the agent fail?" predicates don't conflate
+ *     "user pressed Stop" with "agent crashed mid-run"). The widget
+ *     renders this as a neutral "Stopped" state, not a red Failed card.
+ */
+ | {
     kind: 'session_end';
     turns?: number;
     costUsd?: number;
     isError?: boolean;
+    cancelled?: boolean;
     summary?: string;
 } | {
     kind: 'raw';

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

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

package/dist/playwright/cdpStatus.js

@@ -12,7 +12,7 @@
  *                     trigger a launch.
  */
 import { chromium } from 'playwright-core';
-import { preflightCDP } from './preflight.js';
+import { getPreflight } from './preflightCache.js';
 import { findCdpPid, raiseChromeWindow } from './raiseWindow.js';
 /**
  * Parse a page URL down to its origin (protocol + host + port). We compare
@@ -33,7 +33,7 @@ export async function checkCdpStatus(cdpUrl, pageUrl) {
         // Treat unparseable page URLs as no-cdp so the UI nudges a relaunch.
         return { state: 'no-cdp', reason: `unparseable page URL: ${pageUrl}` };
     }
-    const cdp = await preflightCDP(cdpUrl);
+    const cdp = await getPreflight(cdpUrl);
     if (!cdp.ok) {
         return { state: 'no-cdp', reason: cdp.reason };
     }

package/dist/playwright/preflightCache.d.ts

@@ -0,0 +1,27 @@
+import { preflightCDP } from './preflight.js';
+/**
+ * Per-cdpUrl preflight cache.
+ *
+ * Why this exists: Hover preflights the CDP endpoint (`/json/version` +
+ * `/json/list`) before every agent command AND on every widget connect's
+ * `check-cdp` ping. Each `/json/list` round-trip is ~30–80 ms on local
+ * Chrome; doing it twice for the same request — once from the command
+ * path, once from the widget's CDP banner — adds up, and the widget pings
+ * frequently because Vite HMR cycles the WebSocket connection.
+ *
+ * The cache is shared across both paths and keyed by `cdpUrl` so multiple
+ * Hover services (one per example app in this monorepo, each with its own
+ * CDP endpoint someday) don't share entries. 30 s TTL — Chrome's tab list
+ * doesn't drift faster than that during a dev session, and any failure
+ * (Chrome killed, --remote-debugging-port closed) invalidates via
+ * `invalidatePreflight()` on the next failed agent invocation.
+ *
+ * Successful preflights are cached; failures are not (so the user gets
+ * immediate feedback the next time they fix the underlying issue —
+ * starting Chrome, fixing the wrong port).
+ */
+type Result = Awaited<ReturnType<typeof preflightCDP>>;
+export declare function getPreflight(cdpUrl: string): Promise<Result>;
+export declare function invalidatePreflight(cdpUrl: string): void;
+export {};
+//# sourceMappingURL=preflightCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preflightCache.d.ts","sourceRoot":"","sources":["../../src/playwright/preflightCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,KAAK,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC;AAMvD,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAalE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAExD"}

package/dist/playwright/preflightCache.js

@@ -0,0 +1,21 @@
+import { preflightCDP } from './preflight.js';
+const TTL_MS = 30_000;
+const cache = new Map();
+export async function getPreflight(cdpUrl) {
+    const now = Date.now();
+    const hit = cache.get(cdpUrl);
+    if (hit && hit.result.ok && now - hit.at < TTL_MS) {
+        return hit.result;
+    }
+    const result = await preflightCDP(cdpUrl);
+    if (result.ok) {
+        cache.set(cdpUrl, { result, at: now });
+    }
+    else {
+        cache.delete(cdpUrl);
+    }
+    return result;
+}
+export function invalidatePreflight(cdpUrl) {
+    cache.delete(cdpUrl);
+}

package/dist/playwright/resolveMcpConfig.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve a ready-to-use MCP config file path that points at the local
+ * `@playwright/mcp` package via an absolute Node-resolved path.
+ *
+ * Why this exists: Hover originally shipped a static `mcp.config.json`
+ * with `"command": "npx", "args": ["-y", "@playwright/mcp@latest", …]`.
+ * That meant every `claude -p` invocation kicked off a registry lookup
+ * for `@latest` plus a tarball metadata round-trip before the MCP server
+ * even started — adding 300 ms - 2 s of dead air to first-token latency
+ * on every command (verified via `time npx -y @playwright/mcp@latest`).
+ *
+ * The fix is to (a) declare `@playwright/mcp` as a real dependency of
+ * `@hover-dev/core` so npm resolves it locally at install time, and
+ * (b) write a synthetic config file pointing `node <abs-path>/cli.js`
+ * at the resolved location. No registry hit on the hot path.
+ *
+ * The config file is written to `<tmpdir>/hover/mcp-config-<port>.json`,
+ * which lets multiple Hover services (one per example app) coexist
+ * without stepping on each other's CDP endpoint.
+ */
+export declare function resolveMcpConfig(opts: {
+    /** CDP URL passed to the MCP server's `--cdp-endpoint` flag. */
+    cdpUrl: string;
+    /** Service port — used to namespace the temp config file. */
+    port: number;
+}): string;
+//# sourceMappingURL=resolveMcpConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveMcpConfig.d.ts","sourceRoot":"","sources":["../../src/playwright/resolveMcpConfig.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAsCT"}

package/dist/playwright/resolveMcpConfig.js

@@ -0,0 +1,62 @@
+import { createRequire } from 'node:module';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import process from 'node:process';
+/**
+ * Resolve a ready-to-use MCP config file path that points at the local
+ * `@playwright/mcp` package via an absolute Node-resolved path.
+ *
+ * Why this exists: Hover originally shipped a static `mcp.config.json`
+ * with `"command": "npx", "args": ["-y", "@playwright/mcp@latest", …]`.
+ * That meant every `claude -p` invocation kicked off a registry lookup
+ * for `@latest` plus a tarball metadata round-trip before the MCP server
+ * even started — adding 300 ms - 2 s of dead air to first-token latency
+ * on every command (verified via `time npx -y @playwright/mcp@latest`).
+ *
+ * The fix is to (a) declare `@playwright/mcp` as a real dependency of
+ * `@hover-dev/core` so npm resolves it locally at install time, and
+ * (b) write a synthetic config file pointing `node <abs-path>/cli.js`
+ * at the resolved location. No registry hit on the hot path.
+ *
+ * The config file is written to `<tmpdir>/hover/mcp-config-<port>.json`,
+ * which lets multiple Hover services (one per example app) coexist
+ * without stepping on each other's CDP endpoint.
+ */
+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
+    // Node.js pattern for locating an installed package's directory
+    // regardless of its main/exports map.
+    //
+    // The resolution starts from `process.cwd()`, NOT `import.meta.url`.
+    // When this module is dynamically imported through Next 16's Turbopack
+    // (via `@hover-dev/next`'s `register-node.js`), `import.meta.url` is
+    // a virtual "[project]/..." URL that doesn't resolve to a real file
+    // on disk — `createRequire` accepts the URL but the resulting
+    // `require.resolve('@playwright/mcp/...')` walks the wrong tree and
+    // emits a "[project]/..." prefix in the result, which Claude Code
+    // 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'));
+    const pkgJsonPath = require.resolve('@playwright/mcp/package.json');
+    const pkgRoot = dirname(pkgJsonPath);
+    // The package's `bin` map declares "playwright-mcp": "cli.js" — we
+    // pin to that file directly via Node so the user doesn't need the
+    // bin shim on PATH and we skip yet another resolution layer.
+    const cliPath = resolve(pkgRoot, 'cli.js');
+    const config = {
+        mcpServers: {
+            playwright: {
+                command: process.execPath, // current Node binary
+                args: [cliPath, '--cdp-endpoint', opts.cdpUrl],
+            },
+        },
+    };
+    const outDir = resolve(tmpdir(), 'hover');
+    mkdirSync(outDir, { recursive: true });
+    const outPath = resolve(outDir, `mcp-config-${opts.port}.json`);
+    writeFileSync(outPath, JSON.stringify(config, null, 2), 'utf-8');
+    return outPath;
+}

package/dist/scripts/bench-ttfb.d.ts

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

package/dist/scripts/bench-ttfb.d.ts.map

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

package/dist/scripts/bench-ttfb.js

@@ -0,0 +1,127 @@
+/**
+ * Benchmark "time to first tool_use" for the LLM-driven loop.
+ *
+ * Assumes:
+ *  - A debug Chrome is running on :9222 (start with `pnpm smoke:chrome`).
+ *  - A dev server is running so the agent has something to drive
+ *    (`pnpm dev:example:basic-app`).
+ *
+ * Per iteration:
+ *  - Start a fresh Hover service (cold — kills any prior service to avoid
+ *    cached MCP process state across iterations).
+ *  - WS-connect, send a fixed command, mark t0 right before send().
+ *  - Mark t1 on the first tool_use event from the agent.
+ *  - Report (t1 - t0) in milliseconds. Close service + WS.
+ *
+ *   pnpm --filter @hover-dev/core exec tsx src/scripts/bench-ttfb.ts <n>
+ *
+ * `n` defaults to 5. Prints individual timings + median + min/max.
+ */
+import { WebSocket } from 'ws';
+import { startService } from '../service.js';
+const PROMPT = process.env.HOVER_BENCH_PROMPT ?? 'Take a snapshot of the page.';
+const ITERATIONS = Number(process.argv[2] ?? 5);
+async function singleRun() {
+    const service = await startService({
+        // Use 0 to let the kernel pick — avoids cross-iter EADDRINUSE races.
+        port: 0,
+        agentId: 'claude',
+        model: 'sonnet',
+        cdpUrl: 'http://localhost:9222',
+        devRoot: process.cwd(),
+    });
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${service.port}`);
+        let t0 = 0;
+        let resolved = false;
+        const timeout = setTimeout(() => {
+            if (!resolved) {
+                ws.close(1000);
+                service.close();
+                reject(new Error('timed out waiting for first tool_use after 60s'));
+            }
+        }, 60_000);
+        ws.on('open', () => {
+            t0 = performance.now();
+            ws.send(JSON.stringify({ type: 'command', payload: { text: PROMPT } }));
+        });
+        ws.on('message', raw => {
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            if (process.env.HOVER_BENCH_VERBOSE === '1') {
+                process.stderr.write(`    [event] ${raw.toString().slice(0, 200)}\n`);
+            }
+            if (msg.type !== 'event')
+                return;
+            const ev = msg.payload;
+            if (ev.kind === 'tool_use' && !resolved) {
+                const t1 = performance.now();
+                const ms = t1 - t0;
+                resolved = true;
+                clearTimeout(timeout);
+                ws.close(1000);
+                service.close().finally(() => resolve(ms));
+            }
+            if (ev.kind === 'session_end' && !resolved) {
+                // Ran without any tool_use — agent went text-only or errored.
+                // Reject so the bench surfaces the issue instead of recording
+                // a misleadingly tiny "first tool_use" timing.
+                resolved = true;
+                clearTimeout(timeout);
+                const evAny = ev;
+                const reason = evAny.isError ? 'session_end (error)' : 'session_end without tool_use';
+                ws.close(1000);
+                service.close().finally(() => reject(new Error(reason)));
+            }
+        });
+        ws.on('error', err => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timeout);
+            service.close().finally(() => reject(err));
+        });
+    });
+}
+function median(xs) {
+    const sorted = [...xs].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+async function main() {
+    console.log(`prompt: ${JSON.stringify(PROMPT)}`);
+    console.log(`iterations: ${ITERATIONS}`);
+    console.log('');
+    const results = [];
+    for (let i = 1; i <= ITERATIONS; i++) {
+        try {
+            const ms = await singleRun();
+            results.push(ms);
+            console.log(`  run ${i}: ${ms.toFixed(0).padStart(5)} ms`);
+        }
+        catch (err) {
+            console.error(`  run ${i}: FAILED — ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Small gap between runs so any process-cleanup tail can flush.
+        await new Promise(r => setTimeout(r, 500));
+    }
+    if (results.length === 0) {
+        console.error('\nNo successful runs.');
+        process.exit(1);
+    }
+    console.log('');
+    console.log(`min:    ${Math.min(...results).toFixed(0)} ms`);
+    console.log(`median: ${median(results).toFixed(0)} ms`);
+    console.log(`max:    ${Math.max(...results).toFixed(0)} ms`);
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/service/cdpHint.d.ts

@@ -12,9 +12,37 @@
  *
  * Lives in its own file because this string is the most-tuned text in the
  * repo and the easiest to break with a typo. Tests can import directly.
+ *
+ * Two-tier split (since v0.4.x perf pass):
+ *   - `buildCdpHint(tabs)` returns the full rules + narration block.
+ *     Used on the *first* turn of a session (no `--resume`).
+ *   - `buildCdpHintResume(tabs)` returns ONLY the volatile tab list +
+ *     active-origin guard. Used on subsequent turns once `--resume`
+ *     re-anchors the agent to the prior turn's full system prompt —
+ *     the stable rules are already in context, so re-sending them
+ *     fragments Anthropic's prompt cache and bills ~500 extra input
+ *     tokens per turn for zero behavioural change.
  */
-export declare function buildCdpHint(tabs: {
+interface Tab {
     url: string;
     title?: string;
-}[]): string;
+}
+export declare function buildCdpHint(tabs: Tab[]): string;
+/**
+ * Volatile-only hint for `--resume` turns: just the tab list snapshot.
+ * Empty string when the tab list is empty (nothing to refresh).
+ *
+ * The rules and narration format from `buildCdpHint` are already
+ * established in the prior turn's context; re-sending them here would
+ * fragment Anthropic's prompt-cache fingerprint (cache hits require the
+ * system prompt to match byte-for-byte across turns) and bill ~500
+ * extra input tokens per follow-up turn for no behaviour change.
+ *
+ * We DO re-send the tab list because it can drift between turns (user
+ * opens a second tab, switches focus). The active-origin nav-guard is
+ * not repeated — the agent has it from turn 1 and the tab-list update
+ * keeps it grounded in the current URL.
+ */
+export declare function buildCdpHintResume(tabs: Tab[]): string;
+export {};
 //# sourceMappingURL=cdpHint.d.ts.map

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

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

package/dist/service/cdpHint.js

@@ -12,10 +12,20 @@
  *
  * Lives in its own file because this string is the most-tuned text in the
  * repo and the easiest to break with a typo. Tests can import directly.
+ *
+ * Two-tier split (since v0.4.x perf pass):
+ *   - `buildCdpHint(tabs)` returns the full rules + narration block.
+ *     Used on the *first* turn of a session (no `--resume`).
+ *   - `buildCdpHintResume(tabs)` returns ONLY the volatile tab list +
+ *     active-origin guard. Used on subsequent turns once `--resume`
+ *     re-anchors the agent to the prior turn's full system prompt —
+ *     the stable rules are already in context, so re-sending them
+ *     fragments Anthropic's prompt cache and bills ~500 extra input
+ *     tokens per turn for zero behavioural change.
  */
-export function buildCdpHint(tabs) {
+function resolveActiveOrigin(tabs) {
     if (tabs.length === 0)
-        return '';
+        return null;
     // Prefer the localhost tab if we have multiple — that's almost always the
     // dev server the user is testing against.
     const localhost = tabs.find(t => /localhost|127\.0\.0\.1/.test(t.url));
@@ -25,7 +35,43 @@ export function buildCdpHint(tabs) {
         activeOrigin = new URL(active.url).origin;
     }
     catch { /* malformed url — fall back to no-origin guard */ }
+    return { active, activeOrigin };
+}
+export function buildCdpHint(tabs) {
+    const resolved = resolveActiveOrigin(tabs);
+    if (!resolved)
+        return '';
+    const { active, activeOrigin } = resolved;
     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:`,
+        ``,
+        `    1. browser_snapshot to learn the app's structure.`,
+        `    2. Identify the main interactive surfaces (forms, buttons, links,`,
+        `       inputs, navigation). Plan 2–5 distinct user flows to exercise.`,
+        `    3. Drive each flow end-to-end. Submit forms with real-ish input,`,
+        `       click through navigation, exercise lists / counters / toggles.`,
+        `       Try a couple of edge cases — empty submissions, invalid input,`,
+        `       boundary values — and observe the response.`,
+        `    4. Note anything that looks broken, inconsistent, slow, or`,
+        `       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.`,
+        ``,
         `The user's Chrome currently has these tabs open:`,
         ...tabs.map(t => `  - ${t.url}${t.title ? `  (${t.title})` : ''}`),
         ``,
@@ -84,3 +130,32 @@ export function buildCdpHint(tabs) {
         `  final summary so they group cleanly. Mid-run, just narrate the next step.`,
     ].join('\n');
 }
+/**
+ * Volatile-only hint for `--resume` turns: just the tab list snapshot.
+ * Empty string when the tab list is empty (nothing to refresh).
+ *
+ * The rules and narration format from `buildCdpHint` are already
+ * established in the prior turn's context; re-sending them here would
+ * fragment Anthropic's prompt-cache fingerprint (cache hits require the
+ * system prompt to match byte-for-byte across turns) and bill ~500
+ * extra input tokens per follow-up turn for no behaviour change.
+ *
+ * We DO re-send the tab list because it can drift between turns (user
+ * opens a second tab, switches focus). The active-origin nav-guard is
+ * not repeated — the agent has it from turn 1 and the tab-list update
+ * keeps it grounded in the current URL.
+ */
+export function buildCdpHintResume(tabs) {
+    const resolved = resolveActiveOrigin(tabs);
+    if (!resolved)
+        return '';
+    const { active } = resolved;
+    return [
+        `(Resumed session — full nav + narration rules already in context.)`,
+        ``,
+        `Current Chrome tabs:`,
+        ...tabs.map(t => `  - ${t.url}${t.title ? `  (${t.title})` : ''}`),
+        ``,
+        `Likely active dev tab: ${active.url}`,
+    ].join('\n');
+}

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAmEA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAwV/E"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA+DA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAiV/E"}

package/dist/service.js

@@ -35,20 +35,17 @@
  *   server → client (in addition to those documented in the file body):
  *     { type: 'agents',        payload: { current: string, available: AgentAvailability[] } }
  */
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { WebSocketServer, WebSocket } from 'ws';
 import { invokeAgent } from './agents/invoke.js';
 import { listAgentAvailability, pickPrimaryAgent, } from './agents/detect.js';
 import { getAgent } from './agents/registry.js';
-import { preflightCDP } from './playwright/preflight.js';
+import { getPreflight, invalidatePreflight } from './playwright/preflightCache.js';
+import { resolveMcpConfig } from './playwright/resolveMcpConfig.js';
 import { listSkills } from './skills/writeSkill.js';
 import { send } from './service/types.js';
-import { buildCdpHint } from './service/cdpHint.js';
+import { buildCdpHint, buildCdpHintResume } from './service/cdpHint.js';
 import { handleCheckCdp, handleLaunchChrome, handleFocusDebug, } from './service/cdpHandlers.js';
 import { handleSaveArtifact, SKILL_CONFIG, SPEC_CONFIG, CASE_CSV_CONFIG, } from './service/saveHandlers.js';
-const HERE = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_MCP_CONFIG = resolve(HERE, '..', 'mcp.config.json');
 // ClientMessage + send moved to ./service/types.ts so the cdp + save
 // handler modules can share them. See those files for the wire shape.
 const PROTOCOL_VERSION = 1;
@@ -121,11 +118,15 @@ export async function startService(opts) {
     // so the user can hit Stop when they've seen enough. Pass maxBudgetUsd
     // explicitly (or via the Vite plugin option) if a hard ceiling is needed.
     const maxBudgetUsd = opts.maxBudgetUsd;
-    const mcpConfig = opts.mcpConfig ?? DEFAULT_MCP_CONFIG;
     const cdpUrl = opts.cdpUrl ?? 'http://localhost:9222';
     const devRoot = opts.devRoot ?? process.cwd();
     const wss = await pickAndBind('127.0.0.1', requestedPort, PORT_RETRIES);
     const port = wss.address().port;
+    // Resolve a CDP-pinned MCP config pointing at our local
+    // `@playwright/mcp` install. See resolveMcpConfig.ts for the rationale
+    // (avoids `npx -y @playwright/mcp@latest`'s registry round-trip on
+    // every command — 300 ms - 2 s of hot-path latency).
+    const mcpConfig = opts.mcpConfig ?? resolveMcpConfig({ cdpUrl, port });
     // Surface post-listen errors instead of crashing the host process.
     wss.on('error', err => {
         process.stderr.write(`[hover] WebSocketServer error: ${err.message}\n`);
@@ -141,38 +142,10 @@ export async function startService(opts) {
         }
         return agentAvailabilityCache;
     };
-    // Cache the CDP preflight result for a short window. preflightCDP() does
-    // two HTTP roundtrips to Chrome's debug endpoint (/json/version +
-    // /json/list); on a multi-turn session that's 100-300ms of latency before
-    // every follow-up — directly observable as a pause between hitting send
-    // and the agent starting work. A 5s TTL is comfortably shorter than the
-    // time it takes a user to type+send another message, but long enough that
-    // back-to-back commands skip the roundtrip. Failures are NOT cached so
-    // the user gets immediate feedback when they fix the underlying issue
-    // (e.g. start Chrome). Cache is invalidated whenever an invocation fails
-    // (defensive: if MCP somehow spawned its own Chromium we want the next
-    // preflight to re-probe).
-    const PREFLIGHT_TTL_MS = 5000;
-    let cachedPreflight = null;
-    let cachedPreflightAt = 0;
-    const getPreflight = async () => {
-        const now = Date.now();
-        if (cachedPreflight?.ok && now - cachedPreflightAt < PREFLIGHT_TTL_MS) {
-            return cachedPreflight;
-        }
-        const result = await preflightCDP(cdpUrl);
-        if (result.ok) {
-            cachedPreflight = result;
-            cachedPreflightAt = now;
-        }
-        else {
-            cachedPreflight = null;
-        }
-        return result;
-    };
-    const invalidatePreflight = () => {
-        cachedPreflight = null;
-    };
+    // The CDP preflight cache (shared between this service's command path
+    // and the widget's `check-cdp` ping via `cdpStatus.checkCdpStatus`)
+    // lives in ./playwright/preflightCache.ts. 30-second TTL, keyed by
+    // cdpUrl. See that file for the rationale.
     const broadcastAgents = async () => {
         const available = await getAvailability(false);
         const payload = { current: currentAgentId, available };
@@ -209,11 +182,18 @@ export async function startService(opts) {
             // Send a synthetic session_end so the widget resets to idle immediately.
             // The for-await loop below short-circuits on `cancelled`, so no events
             // from the dying child will arrive after this.
+            //
+            // `cancelled: true` is the load-bearing field — it lets the widget
+            // distinguish "user pressed Stop" from "agent crashed". `isError`
+            // stays false because the agent didn't fail: the user chose to
+            // end the run. The widget renders this as a neutral "Stopped"
+            // state rather than a red Failed card.
             send(ws, {
                 type: 'event',
                 payload: {
                     kind: 'session_end',
-                    isError: true,
+                    isError: false,
+                    cancelled: true,
                     summary: 'cancelled by user',
                 },
             });
@@ -324,7 +304,7 @@ export async function startService(opts) {
                 // Playwright MCP server would silently launch its own Chromium —
                 // and Hover's premise is to drive the user's existing Chrome (with
                 // their dev state, cookies, devtools open), never spawn a fresh one.
-                const cdp = await getPreflight();
+                const cdp = await getPreflight(cdpUrl);
                 if (!cdp.ok) {
                     send(ws, {
                         type: 'event',
@@ -342,7 +322,15 @@ export async function startService(opts) {
                 // a wasteful full-page reload that also destroys the Hover widget
                 // momentarily (the widget re-injects + recovers, but the agent's
                 // own session sometimes gets confused).
-                const appendSystemPrompt = buildCdpHint(cdp.tabs);
+                // First turn pays the full rules + narration block; follow-up
+                // turns (`resumeSessionId` set) get only the volatile tab list.
+                // The static rules are already in the prior turn's context, and
+                // re-sending them fragments Anthropic's prompt-cache fingerprint
+                // (cache hits require byte-identical system prompts across turns).
+                // See cdpHint.ts for the why.
+                const appendSystemPrompt = resumeSessionId
+                    ? buildCdpHintResume(cdp.tabs)
+                    : buildCdpHint(cdp.tabs);
                 // Snapshot the agent id so a switch-agent message during the run
                 // can't smear two agents across one invocation. (We also gate
                 // switch-agent on `busy`, but defense in depth.)
@@ -411,7 +399,7 @@ export async function startService(opts) {
                 // Chrome dying, MCP spawning a stray Chromium, the user closing
                 // their debug window — anything that would make a cached "all
                 // healthy" result lie.
-                invalidatePreflight();
+                invalidatePreflight(cdpUrl);
             }
             finally {
                 busy = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -42,10 +42,10 @@
   },
   "files": [
     "dist",
-    "mcp.config.json",
     "README.md"
   ],
   "dependencies": {
+    "@playwright/mcp": "0.0.75",
     "cross-spawn": "^7.0.6",
     "playwright-core": "^1.50.0",
     "ws": "^8.20.1"
@@ -70,6 +70,7 @@
     "verify-skill": "tsx src/scripts/verify-skill.ts",
     "verify-spec": "tsx src/scripts/verify-spec.ts",
     "ws-smoke": "tsx src/scripts/ws-smoke.ts",
+    "bench-ttfb": "tsx src/scripts/bench-ttfb.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },

package/mcp.config.json

@@ -1,12 +0,0 @@
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@playwright/mcp@latest",
-        "--cdp-endpoint", "http://localhost:9222"
-      ]
-    }
-  }
-}