@hover-dev/core 0.15.0 → 0.17.0

package/dist/mcp/sourceFence.js

@@ -0,0 +1,79 @@
+/**
+ * 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
+    /\.env$/i, //                             any *.env dotenv file (prod.env, local.env)
+    /(^|\/)\.envrc$/i, //                      direnv (holds exported env / secrets)
+    /\.tfvars(\.json)?$/i, //                  terraform variable files (often secrets)
+    /(^|\/)\.htpasswd$/i, //                   http basic-auth credentials
+    /(^|\/)\.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,191 @@
+#!/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 { WebSocket } from 'ws';
+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 }] };
+}
+// ── Read-approval gate ──────────────────────────────────────────────────────
+// When the host runs us with HOVER_SOURCE_GATE=ask, every read/list first asks
+// the editor (over the Hover service WS at HOVER_APPROVAL_PORT) for the user's
+// one-click approval. The reader is fenced + read-only, so the gate is consent
+// UX, not a security boundary: if the editor can't be reached or doesn't answer
+// within 30s we FAIL OPEN (allow) rather than stall the agent's run.
+const GATE = process.env.HOVER_SOURCE_GATE;
+const APPROVAL_PORT = process.env.HOVER_APPROVAL_PORT;
+let approvalWs = null;
+let approvalSeq = 0;
+const pendingApprovals = new Map();
+function ensureApprovalWs() {
+    if (GATE !== 'ask' || !APPROVAL_PORT)
+        return null;
+    if (approvalWs && (approvalWs.readyState === WebSocket.OPEN || approvalWs.readyState === WebSocket.CONNECTING))
+        return approvalWs;
+    try {
+        const sock = new WebSocket(`ws://127.0.0.1:${APPROVAL_PORT}`);
+        sock.on('message', (data) => {
+            try {
+                const m = JSON.parse(data.toString());
+                if (m?.type === 'source-approval-response' && m.payload?.approvalId) {
+                    const settle = pendingApprovals.get(m.payload.approvalId);
+                    if (settle)
+                        settle(m.payload.allow === true);
+                }
+            }
+            catch { /* ignore malformed */ }
+        });
+        // Channel lost → fail OPEN for every waiting read (the reader is fenced +
+        // read-only; the gate is consent UX, not a security boundary, so never hang
+        // a run on a dead channel). The user taking their time is NOT a loss — only
+        // a closed/errored socket settles here.
+        const drain = () => { for (const s of [...pendingApprovals.values()])
+            s(true); };
+        sock.on('error', () => { drain(); });
+        sock.on('close', () => { if (approvalWs === sock)
+            approvalWs = null; drain(); });
+        approvalWs = sock;
+    }
+    catch {
+        approvalWs = null;
+    }
+    return approvalWs;
+}
+async function approve(path, kind) {
+    if (GATE !== 'ask' || !APPROVAL_PORT)
+        return true; // not gated → allow
+    const sock = ensureApprovalWs();
+    if (!sock)
+        return true; // no channel → fail open
+    const id = `a${++approvalSeq}`;
+    return new Promise((resolve) => {
+        // NO timeout: the consent prompt waits for the user (they may not see it for
+        // a while — that must never auto-allow). It settles only on their answer, or
+        // when the channel drops (drain() above → fail open), or run cancel.
+        const settle = (allow) => {
+            if (!pendingApprovals.has(id))
+                return;
+            pendingApprovals.delete(id);
+            resolve(allow);
+        };
+        pendingApprovals.set(id, settle);
+        const req = () => sock.send(JSON.stringify({ type: 'source-approval-request', payload: { approvalId: id, sourcePath: path, sourceKind: kind } }));
+        if (sock.readyState === WebSocket.OPEN)
+            req();
+        else
+            sock.once('open', req);
+    });
+}
+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 }) => {
+    if (!(await approve(path, 'read')))
+        return md(`✗ source read declined by the user — continue from what's visible on the page.`);
+    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 }) => {
+    if (!(await approve(subdir || '.', 'list')))
+        return md(`✗ source listing declined by the user.`);
+    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/memory/businessMemory.d.ts

@@ -0,0 +1,29 @@
+/** A learned business fact about the app under test. */
+export interface BusinessFact {
+    /** kebab-case slug; also the filename stem. */
+    name: string;
+    /** One-line summary used for recall relevance + the index hook. */
+    description: string;
+    /** What kind of knowledge this is. */
+    type: 'business-rule' | 'expected-behavior' | 'validation' | 'access-policy';
+    /** The fact itself (markdown). */
+    body: string;
+}
+export declare function memoryDir(devRoot: string): string;
+/** kebab-case a title into a safe filename stem. */
+export declare function slugify(s: string): string;
+/** Load every fact under `.hover/memory/` (excluding the MEMORY.md index).
+ *  Pure + total: a missing dir / unreadable file just yields fewer facts. */
+export declare function loadMemory(devRoot: string): Promise<BusinessFact[]>;
+/** Format loaded facts as a system-prompt block, or '' when there are none (so
+ *  the caller appends nothing). Grouped nothing-fancy: one bullet per fact. */
+export declare function formatMemoryForPrompt(facts: BusinessFact[]): string;
+/** Write (or overwrite) a fact file + refresh the MEMORY.md index line. NEVER
+ *  throws — returns the path or an error string for the caller to log. Business
+ *  RULES only; the caller must never pass secrets / PII / credentials. */
+export declare function writeFact(devRoot: string, fact: BusinessFact): Promise<{
+    path: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=businessMemory.d.ts.map

package/dist/memory/businessMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"businessMemory.d.ts","sourceRoot":"","sources":["../../src/memory/businessMemory.ts"],"names":[],"mappings":"AAwBA,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,IAAI,EAAE,eAAe,GAAG,mBAAmB,GAAG,YAAY,GAAG,eAAe,CAAC;IAC7E,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzC;AAsBD;6EAC6E;AAC7E,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAkBzE;AAED;+EAC+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAQnE;AAED;;0EAE0E;AAC1E,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAc/C"}

package/dist/memory/businessMemory.js

@@ -0,0 +1,125 @@
+/**
+ * Business memory — the per-app knowledge QA / API modes accumulate so they stop
+ * re-asking the same business questions every run. Lives at `<devRoot>/.hover/
+ * memory/`, mirroring Claude's own memory layout (an index + one fact per file):
+ *
+ *   .hover/memory/
+ *     MEMORY.md        ← index: one `- [title](file.md) — hook` line per fact
+ *     checkout-tax.md  ← frontmatter (name / description / type) + the fact body
+ *     ...
+ *
+ * Loop: load at run start → inject as agent context ("Known business rules…");
+ * after the user answers a business clarification (trigger-B, a later QA stage),
+ * write the learned fact. The more an app is tested, the fewer popups — see the
+ * QA-tester-mode design + project-moat-strategy.
+ *
+ * CONTRACT: business RULES only, NEVER secrets / PII / credentials (extends the
+ * standing "never read env / secrets" rule). Writes are best-effort — a memory
+ * failure must NEVER break a run (same rule as the session ledger). Used by QA +
+ * API modes only; Flow / Pentest don't read or write it.
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hoverDir } from '../specs/sidecar.js';
+export function memoryDir(devRoot) {
+    return join(hoverDir(devRoot), 'memory');
+}
+/** kebab-case a title into a safe filename stem. */
+export function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'fact';
+}
+/** Parse a fact file's `---` frontmatter + body. Minimal + total — a malformed
+ *  file yields nulls and is skipped by the caller. Only the three known keys are
+ *  read; everything after the closing `---` is the body. */
+function parseFact(slug, raw) {
+    const m = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!m)
+        return null;
+    const fm = m[1];
+    const body = m[2].trim();
+    const field = (k) => {
+        const f = fm.match(new RegExp(`^${k}\\s*:\\s*(.+)$`, 'm'));
+        return f ? f[1].trim().replace(/^["']|["']$/g, '') : '';
+    };
+    const description = field('description');
+    const rawType = field('type');
+    const types = ['business-rule', 'expected-behavior', 'validation', 'access-policy'];
+    const type = types.includes(rawType) ? rawType : 'business-rule';
+    if (!body)
+        return null;
+    return { name: field('name') || slug, description, type, body };
+}
+/** Load every fact under `.hover/memory/` (excluding the MEMORY.md index).
+ *  Pure + total: a missing dir / unreadable file just yields fewer facts. */
+export async function loadMemory(devRoot) {
+    try {
+        const dir = memoryDir(devRoot);
+        const entries = (await readdir(dir)).filter((e) => e.endsWith('.md') && e.toLowerCase() !== 'memory.md');
+        const facts = [];
+        for (const entry of entries.sort()) {
+            try {
+                const raw = await readFile(join(dir, entry), 'utf-8');
+                const fact = parseFact(entry.replace(/\.md$/, ''), raw);
+                if (fact)
+                    facts.push(fact);
+            }
+            catch {
+                /* skip unreadable */
+            }
+        }
+        return facts;
+    }
+    catch {
+        return [];
+    }
+}
+/** Format loaded facts as a system-prompt block, or '' when there are none (so
+ *  the caller appends nothing). Grouped nothing-fancy: one bullet per fact. */
+export function formatMemoryForPrompt(facts) {
+    if (!facts.length)
+        return '';
+    const lines = facts.map((f) => `- ${f.description ? f.description + ' — ' : ''}${f.body.replace(/\s+/g, ' ').trim()}`);
+    return ('KNOWN BUSINESS KNOWLEDGE FOR THIS APP (learned from earlier runs — treat as ' +
+        'ground truth; do NOT re-ask what these already answer):\n' +
+        lines.join('\n'));
+}
+/** Write (or overwrite) a fact file + refresh the MEMORY.md index line. NEVER
+ *  throws — returns the path or an error string for the caller to log. Business
+ *  RULES only; the caller must never pass secrets / PII / credentials. */
+export async function writeFact(devRoot, fact) {
+    try {
+        const dir = memoryDir(devRoot);
+        await mkdir(dir, { recursive: true });
+        const slug = slugify(fact.name);
+        const file = `${slug}.md`;
+        const content = `---\nname: ${slug}\ndescription: ${fact.description}\ntype: ${fact.type}\n---\n\n${fact.body.trim()}\n`;
+        await writeFile(join(dir, file), content, 'utf-8');
+        await upsertIndex(dir, slug, fact);
+        return { path: join(dir, file) };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Add/replace this fact's line in MEMORY.md (`- [title](file.md) — hook`),
+ *  keyed by the file link so re-writing a fact updates rather than duplicates. */
+async function upsertIndex(dir, slug, fact) {
+    const indexPath = join(dir, 'MEMORY.md');
+    const link = `(${slug}.md)`;
+    const line = `- [${fact.name}](${slug}.md) — ${fact.description || fact.type}`;
+    let existing = '';
+    try {
+        existing = await readFile(indexPath, 'utf-8');
+    }
+    catch {
+        existing = '# Business memory\n\nWhat Hover has learned about this app. One fact per file.\n';
+    }
+    const kept = existing
+        .split('\n')
+        .filter((l) => !(l.startsWith('- [') && l.includes(link)));
+    await writeFile(indexPath, `${kept.join('\n').replace(/\n+$/, '')}\n${line}\n`, 'utf-8');
+}

package/dist/modes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Built-in (non-plugin) mode behavior. Hover's core modes — Flow (the default,
+ * modeId `null`) and the planned QA mode — are pure agent-behavior config: which
+ * actuation tools the agent uses and how a run crystallizes. (Plugin modes —
+ * api-test / pentest — bring runtime machinery instead: a MITM proxy, sidecars,
+ * Chrome proxy flags, lifecycle hooks; they resolve to PLUGIN_MODE_BEHAVIOR.)
+ *
+ * `resolveModeBehavior(modeId)` is the SINGLE place that answers "how does this
+ * mode drive the agent", replacing scattered `currentModeId === null` checks.
+ * Adding a built-in mode (e.g. QA) = one entry in BUILTIN_MODE_BEHAVIOR, not new
+ * conditionals threaded through the run-assembly path.
+ */
+export interface ModeBehavior {
+    /** Deny Playwright's loose interaction tools (browser_click / type / fill_form
+     *  / select_option / file_upload) AND inject the grounded-actuation directive,
+     *  so the agent actuates via the Hover control MCP and saved selectors are
+     *  role+name (record == replay). Flow and QA want this — they crystallize
+     *  browser steps; plugin modes don't — they explore to capture traffic and
+     *  keep the Playwright tools. */
+    groundedActuation: boolean;
+}
+/** Resolve the agent-behavior config for a mode id (null = Flow). Built-in modes
+ *  are table-driven; any other (plugin) id falls back to PLUGIN_MODE_BEHAVIOR. */
+export declare function resolveModeBehavior(modeId: string | null): ModeBehavior;
+/** Picker metadata for built-in non-Flow modes (Flow is the implicit null
+ *  default, not listed). core's broadcastModes merges these into the mode
+ *  catalogue alongside plugin-contributed modes, and switchMode/set-mode accept
+ *  them without requiring a plugin. */
+export interface BuiltinMode {
+    id: string;
+    label: string;
+    description: string;
+    accent: string;
+}
+export declare const BUILTIN_MODES: BuiltinMode[];
+/** True for a built-in non-null mode id (currently just `qa`). Lets core accept
+ *  it in set-mode / switchMode without a contributing plugin. */
+export declare function isBuiltinMode(modeId: string): boolean;
+//# sourceMappingURL=modes.d.ts.map

package/dist/modes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../src/modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;qCAKiC;IACjC,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAmBD;kFACkF;AAClF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAGvE;AAED;;;uCAGuC;AACvC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,eAAO,MAAM,aAAa,EAAE,WAAW,EAOtC,CAAC;AAEF;iEACiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/modes.js

@@ -0,0 +1,34 @@
+/** Flow — the default mode (modeId `null`): author a Playwright spec via grounded
+ *  actuation. */
+const FLOW_MODE_BEHAVIOR = { groundedActuation: true };
+/** Built-in modes other than Flow, keyed by modeId.
+ *  QA = comprehensive testing umbrella; its Functional capability reuses Flow's
+ *  grounded actuation (record == replay for promoted candidate flows). (Its API
+ *  capability — when enabled — delegates to the api-test plugin's MITM runtime;
+ *  that orchestration is a later QA stage, not a ModeBehavior field.) */
+const BUILTIN_MODE_BEHAVIOR = {
+    qa: { groundedActuation: true },
+};
+/** Plugin-contributed modes (api-test / pentest): full Playwright tool access —
+ *  they explore to capture traffic, not to crystallize browser steps. */
+const PLUGIN_MODE_BEHAVIOR = { groundedActuation: false };
+/** Resolve the agent-behavior config for a mode id (null = Flow). Built-in modes
+ *  are table-driven; any other (plugin) id falls back to PLUGIN_MODE_BEHAVIOR. */
+export function resolveModeBehavior(modeId) {
+    if (modeId === null)
+        return FLOW_MODE_BEHAVIOR;
+    return BUILTIN_MODE_BEHAVIOR[modeId] ?? PLUGIN_MODE_BEHAVIOR;
+}
+export const BUILTIN_MODES = [
+    {
+        id: 'qa',
+        label: 'QA Testing',
+        description: 'explore the whole app → findings report + promotable specs',
+        accent: '#22c55e',
+    },
+];
+/** True for a built-in non-null mode id (currently just `qa`). Lets core accept
+ *  it in set-mode / switchMode without a contributing plugin. */
+export function isBuiltinMode(modeId) {
+    return modeId in BUILTIN_MODE_BEHAVIOR;
+}

package/dist/playwright/cdpStatus.d.ts

@@ -11,19 +11,4 @@ export interface CdpStatusResult {
     reason?: string;
 }
 export declare function checkCdpStatus(cdpUrl: string, pageUrl: string): Promise<CdpStatusResult>;
-/**
- * Bring the debug-Chrome tab matching `pageUrl`'s origin to the front. If no
- * matching tab exists, open a new tab on the origin. Returns the URL of the
- * tab that was focused (or opened) for logging.
- *
- * Uses a short-lived playwright-core connection — opens it, does the work,
- * closes it. We don't keep a long-lived browser handle.
- */
-export declare function focusDebugTab(cdpUrl: string, pageUrl: string): Promise<{
-    ok: true;
-    focusedUrl: string;
-} | {
-    ok: false;
-    reason: string;
-}>;
 //# sourceMappingURL=cdpStatus.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cdpStatus.d.ts","sourceRoot":"","sources":["../../src/playwright/cdpStatus.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8C3E"}
+{"version":3,"file":"cdpStatus.d.ts","sourceRoot":"","sources":["../../src/playwright/cdpStatus.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC,CA4B1B"}

package/dist/playwright/cdpStatus.js

@@ -11,9 +11,7 @@
  *   - 'no-cdp'        no debug Chrome at all; the widget should let the user
  *                     trigger a launch.
  */
-import { chromium } from 'playwright-core';
 import { getPreflight } from './preflightCache.js';
-import { findCdpPid, raiseChromeWindow } from './raiseWindow.js';
 /**
  * Parse a page URL down to its origin (protocol + host + port). We compare
  * by origin, not full URL — the user might be on /login while the debug
@@ -52,68 +50,3 @@ export async function checkCdpStatus(cdpUrl, pageUrl) {
         browser: cdp.browser,
     };
 }
-/**
- * Bring the debug-Chrome tab matching `pageUrl`'s origin to the front. If no
- * matching tab exists, open a new tab on the origin. Returns the URL of the
- * tab that was focused (or opened) for logging.
- *
- * Uses a short-lived playwright-core connection — opens it, does the work,
- * closes it. We don't keep a long-lived browser handle.
- */
-export async function focusDebugTab(cdpUrl, pageUrl) {
-    const wantOrigin = originOf(pageUrl);
-    if (!wantOrigin) {
-        return { ok: false, reason: `unparseable page URL: ${pageUrl}` };
-    }
-    let browser;
-    try {
-        browser = await chromium.connectOverCDP(cdpUrl);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, reason: `couldn't connect to CDP at ${cdpUrl}: ${msg}` };
-    }
-    let focusedUrl;
-    try {
-        const pages = browser.contexts().flatMap(c => c.pages());
-        const match = pages.find(p => originOf(p.url()) === wantOrigin);
-        if (match) {
-            await match.bringToFront();
-            focusedUrl = match.url();
-        }
-        else {
-            // No tab on the dev origin yet — open one so the widget appears.
-            const context = browser.contexts()[0] ?? (await browser.newContext());
-            const page = await context.newPage();
-            await page.goto(pageUrl, { waitUntil: 'domcontentloaded' });
-            await page.bringToFront();
-            focusedUrl = page.url();
-        }
-    }
-    catch (err) {
-        await browser.close().catch(() => { });
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, reason: `bringToFront failed: ${msg}` };
-    }
-    await browser.close().catch(() => { });
-    // CDP-level bringToFront only activates the tab inside the Chrome process;
-    // on macOS in particular the Chrome *window* stays buried if it wasn't
-    // foreground already. Raise the OS window too. Best-effort, never fatal.
-    const port = portFromCdpUrl(cdpUrl);
-    if (port !== null) {
-        const pid = await findCdpPid(port);
-        if (pid !== null)
-            await raiseChromeWindow(pid);
-    }
-    return { ok: true, focusedUrl };
-}
-function portFromCdpUrl(cdpUrl) {
-    try {
-        const u = new URL(cdpUrl);
-        const port = Number.parseInt(u.port, 10);
-        return Number.isInteger(port) && port > 0 ? port : null;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/playwright/launchChrome.d.ts

@@ -21,6 +21,17 @@ export interface LaunchOptions {
         /** Base64 SHA-256 of the MITM CA's SubjectPublicKeyInfo. */
         spki: string;
     };
+    /** Launch Chrome headless (`--headless=new`) — no visible window. Still
+     *  CDP-drivable and still uses the persistent profile, so login state set in
+     *  a prior headed launch carries over. Used by the VSCode extension's silent
+     *  mode. Default false (visible window). */
+    headless?: boolean;
+    /** Close any existing debug Chrome on this port FIRST, then launch fresh.
+     *  The plain launch is idempotent (returns the running instance), so it can't
+     *  switch headless↔visible or recover a window that's there-but-not-showing —
+     *  `force` makes the headless/visible toggle and the "reopen browser" action
+     *  actually relaunch. Default false. */
+    force?: boolean;
 }
 export type LaunchResult = {
     ok: true;
@@ -32,6 +43,13 @@ export type LaunchResult = {
     reason: string;
 };
 export declare function findChromeBinary(): string | null;
+/**
+ * Close a debug Chrome on `port` by sending CDP `Browser.close` over its
+ * DevTools WebSocket (from /json/version). Works without a child-process handle
+ * — Hover spawns Chrome detached — so it's the only way to relaunch in a
+ * different mode. Resolves once closed (or the timeout lapses); never throws.
+ */
+export declare function closeDebugChrome(port: number, timeoutMs?: number): Promise<boolean>;
 /**
  * Start (or detect) a debug Chrome listening on the given CDP port. Detaches
  * the child process so the calling script can exit cleanly while Chrome keeps