@hover-dev/core 0.15.0 → 0.17.0

package/dist/qa/intensity.js

@@ -0,0 +1,25 @@
+export const QA_INTENSITY = {
+    quick: { label: 'Quick', maxSteps: 45, blurb: 'a fast pass over the main flows — breadth over depth (~20–45 steps)' },
+    standard: { label: 'Standard', maxSteps: 150, blurb: 'the main flows plus key negative tests (~45–150 steps)' },
+    deep: { label: 'Deep', maxSteps: 500, blurb: 'exhaustive — every reachable control and state (~150–500 steps)' },
+};
+export const DEFAULT_QA_INTENSITY = 'standard';
+/** Coerce arbitrary input (from the run payload) to a valid intensity. */
+export function asQaIntensity(v) {
+    return v === 'quick' || v === 'deep' || v === 'standard' ? v : DEFAULT_QA_INTENSITY;
+}
+/**
+ * Prompt directive: tell the agent its STEP budget so it paces and ALWAYS wraps
+ * up with a report before the ceiling. The `--max-turns` backstop is the hard
+ * limit; this prose is what guarantees a report.
+ */
+export function qaBudgetDirective(intensity) {
+    const spec = QA_INTENSITY[intensity];
+    const wrapAt = Math.max(5, spec.maxSteps - Math.ceil(spec.maxSteps * 0.1));
+    return (`RUN BUDGET — ${spec.label}: ${spec.blurb}. You have about ${spec.maxSteps} steps ` +
+        `(tool actions) this run, enforced. Pace yourself to fit: cover the most ` +
+        `important flows FIRST. By roughly step ${wrapAt}, STOP exploring and ` +
+        `immediately WRITE YOUR FINDINGS REPORT (and record any clean candidate flows) ` +
+        `while you still can — never end a run without a report. On Quick, be decisive ` +
+        `and favour breadth; on Deep, be exhaustive.`);
+}

package/dist/qa/qaReport.d.ts

@@ -0,0 +1,19 @@
+import type { SessionFinding } from '../sessions/sessions.js';
+export interface QaReportInput {
+    prompt: string;
+    summary: string;
+    findings: SessionFinding[];
+    endedAt: string;
+    targetUrl?: string;
+}
+/** Render the report Markdown (pure — exported for testing). */
+export declare function renderQaReport(input: QaReportInput): string;
+/** Write the QA report into the run's folder as `report.md`. Each run (incl.
+ *  each phase of a two-pass run) has its own folder, so there's no name
+ *  collision. NEVER throws; returns the path or an error string. */
+export declare function writeQaReport(runDirPath: string, input: QaReportInput): Promise<{
+    path: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=qaReport.d.ts.map

package/dist/qa/qaReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qaReport.d.ts","sourceRoot":"","sources":["../../src/qa/qaReport.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAkB3D;AAED;;oEAEoE;AACpE,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAS/C"}

package/dist/qa/qaReport.js

@@ -0,0 +1,50 @@
+/**
+ * QA report artifact — the durable, human-readable output of a QA Testing run.
+ *
+ * QA is report-first: a run produces findings (rendered live in the chat's
+ * Findings card via the normal parseFindings pipeline) AND this persistent
+ * Markdown report under `<devRoot>/.hover/qa-reports/<slug>.md`, mirroring
+ * pentest's report file. Latest-run-wins per prompt slug (the session ledger
+ * keeps the full history; this is the readable artifact).
+ *
+ * Best-effort by contract: a report-write failure must NEVER break a run or the
+ * ledger (same rule as the session ledger + business memory).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Render the report Markdown (pure — exported for testing). */
+export function renderQaReport(input) {
+    const { prompt, summary, findings, endedAt, targetUrl } = input;
+    const meta = [endedAt, targetUrl, `${findings.length} finding${findings.length === 1 ? '' : 's'}`]
+        .filter(Boolean)
+        .join(' · ');
+    const body = [`# QA report — ${prompt.trim()}`, '', `_${meta}_`];
+    if (summary.trim())
+        body.push('', summary.trim());
+    body.push('', '## Findings');
+    if (findings.length) {
+        for (const f of findings) {
+            const sev = (f.severity || 'note').trim();
+            const head = f.title && f.title !== f.text ? `${f.title} — ` : '';
+            body.push(`- **${sev}** — ${head}${f.text.trim()}`);
+        }
+    }
+    else {
+        body.push('_No issues found._');
+    }
+    return body.join('\n') + '\n';
+}
+/** Write the QA report into the run's folder as `report.md`. Each run (incl.
+ *  each phase of a two-pass run) has its own folder, so there's no name
+ *  collision. NEVER throws; returns the path or an error string. */
+export async function writeQaReport(runDirPath, input) {
+    try {
+        await mkdir(runDirPath, { recursive: true });
+        const path = join(runDirPath, 'report.md');
+        await writeFile(path, renderQaReport(input), 'utf-8');
+        return { path };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/runSession.d.ts

@@ -1,5 +1,5 @@
 import type { InvokeEvent } from './agents/types.js';
-import type { SkillStep } from './skills/writeSkill.js';
+import type { SkillStep } from './specs/specStep.js';
 export interface RunSessionOptions {
     prompt: string;
     agentId: string;
@@ -7,9 +7,14 @@ export interface RunSessionOptions {
      *  is supplied (the service passes a pre-built config; the CLI passes this). */
     cdpUrl?: string;
     model?: string;
+    /** Reasoning-effort level forwarded to the agent (claude --effort / codex
+     *  -c model_reasoning_effort). Undefined = agent/model default. */
+    effort?: string;
+    /** Extra env for the spawned CLI (Local LLM: OPENAI_BASE_URL / _API_KEY). */
+    env?: Record<string, string>;
     maxBudgetUsd?: number;
-    /** Optional model API key, injected into the spawned CLI's env. */
-    apiKey?: string;
+    /** Hard ceiling on agent turns (~steps) — QA intensity step budget. */
+    maxTurns?: number;
     /** 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;
@@ -23,6 +28,12 @@ export interface RunSessionOptions {
     /** Extra hard-sandbox allow-list prefixes — e.g. active-mode plugin MCP
      *  server ids the service contributes. Appended to ['mcp__playwright']. */
     allowedToolsExtra?: string[];
+    /** Extra hard-sandbox deny entries — specific tools to forbid even though
+     *  their server is allowed. Normal mode passes the Playwright interaction
+     *  tools (browser_click / _type / _fill_form / _select_option) here so the
+     *  agent must use the grounded mcp__hover-control__* actuation tools, whose
+     *  role+name selectors crystallize 1:1 instead of confabulating getByText. */
+    disallowedToolsExtra?: 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;

package/dist/runSession.d.ts.map

@@ -1 +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,CAuD3B"}
+{"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,qBAAqB,CAAC;AAGrD,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;uEACmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;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;;;;kFAI8E;IAC9E,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;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,CAyE3B"}

package/dist/runSession.js

@@ -27,6 +27,11 @@ export async function runSession(opts, onEvent) {
     const steps = [{ kind: 'user', text: opts.prompt }];
     let summary = '';
     let isError = false;
+    // Index of the most recently captured tool step, so the tool_result that
+    // follows can mark whether that action errored. Without this, every captured
+    // step looks successful and the agent's failed exploration attempts get
+    // crystallized into the spec as if they were real flow.
+    let lastStepIdx = -1;
     const mcpConfig = opts.mcpConfig ??
         resolveMcpConfig({
             cdpUrl: opts.cdpUrl ?? 'http://localhost:9222',
@@ -43,25 +48,35 @@ export async function runSession(opts, onEvent) {
         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,
+        // The allowed-tool set (Playwright MCP + the active mode's plugin servers:
+        // hover-control, api-test flows, source reader, …) is the SAME for every
+        // agent — hard-sandbox agents enforce it via --allowedTools; soft agents
+        // (codex) surface it in their developer_instructions so they don't
+        // self-restrict to Playwright and refuse the plugin tools (e.g. api_request).
+        // The DISallow list is hard-sandbox only (soft agents can't enforce it).
+        allowedTools: ['mcp__playwright', ...(opts.allowedToolsExtra ?? [])],
         disallowedTools: isHardSandbox
-            ? (descriptor?.defaultDisallowedTools ? [...descriptor.defaultDisallowedTools] : undefined)
+            ? [...(descriptor?.defaultDisallowedTools ?? []), ...(opts.disallowedToolsExtra ?? [])]
             : undefined,
         maxBudgetUsd: opts.maxBudgetUsd,
+        maxTurns: opts.maxTurns,
         model: opts.model,
-        apiKey: opts.apiKey,
+        effort: opts.effort,
+        env: opts.env,
         signal: opts.signal,
     })) {
         onEvent(ev);
         if (ev.kind === 'tool_use') {
-            steps.push({ kind: 'step', tool: ev.tool, input: ev.input });
+            lastStepIdx = steps.push({ kind: 'step', tool: ev.tool, input: ev.input }) - 1;
+        }
+        else if (ev.kind === 'tool_result') {
+            // Mark the step this result belongs to (the normalized stream emits
+            // tool_result right after its tool_use). A failed action stays in the
+            // sidecar as part of the full-fidelity record, but writeSpec drops it from
+            // the runnable spec so the artifact reflects the working flow, not the agent's
+            // trial-and-error.
+            if (lastStepIdx >= 0 && ev.isError)
+                steps[lastStepIdx].isError = true;
         }
         else if (ev.kind === 'session_end') {
             if (ev.summary)
@@ -70,6 +85,11 @@ export async function runSession(opts, onEvent) {
                 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

@@ -1,11 +1,8 @@
 /**
  * CDP-related WebSocket message handlers.
  *
- *   check-cdp     → checkCdpStatus → emit cdp-status
  *   launch-chrome → emit "launching" placeholder → launchDebugChrome →
  *                   re-check status → emit cdp-status
- *   focus-debug   → focusDebugTab → no message on success (the widget the
- *                   user is about to focus runs its own check-cdp anyway)
  *
  * Extracted from service.ts during the v0.2.x refactor pass so the main
  * file can be a thin orchestrator.
@@ -14,22 +11,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;
-};
-/**
- * "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
- * either:
- *   - same-window  → normal, drives the page
- *   - wrong-window → disabled, with a "use the other window" notice
- *   - no-cdp       → enabled but click triggers launch-chrome instead
- */
-export declare function handleCheckCdp(ws: WebSocket, msg: ClientMessage, cdpUrl: string, extras?: LaunchExtras): Promise<void>;
+ *  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' | 'userDataDir'>;
 /**
  * Launch a debug Chrome navigated to `pageUrl`, then re-check status. The
  * re-check usually returns 'wrong-window' (because the widget asking is in
@@ -37,12 +21,4 @@ export declare function handleCheckCdp(ws: WebSocket, msg: ClientMessage, cdpUrl
  * displays the "use the other window" state.
  */
 export declare function handleLaunchChrome(ws: WebSocket, msg: ClientMessage, cdpUrl: string, extras?: LaunchExtras): Promise<void>;
-/**
- * bringToFront the debug-Chrome tab matching `pageUrl`'s origin (or open one
- * if none exists). Used by the wrong-window UI's "switch to debug Chrome"
- * button. Doesn't return cdp-status — bringToFront doesn't change anything
- * the widget cares about, and the widget the user is about to focus is a
- * different page (and will run its own check-cdp on its own ws connection).
- */
-export declare function handleFocusDebug(ws: WebSocket, msg: ClientMessage, cdpUrl: string, extras?: LaunchExtras): Promise<void>;
 //# sourceMappingURL=cdpHandlers.d.ts.map

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;;;;;;;;GAQG;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,GAAG,aAAa,CAAC,CAAC;AAExE;;;;;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,CA+Bf"}

package/dist/service/cdpHandlers.js

@@ -1,38 +1,15 @@
 /**
  * CDP-related WebSocket message handlers.
  *
- *   check-cdp     → checkCdpStatus → emit cdp-status
  *   launch-chrome → emit "launching" placeholder → launchDebugChrome →
  *                   re-check status → emit cdp-status
- *   focus-debug   → focusDebugTab → no message on success (the widget the
- *                   user is about to focus runs its own check-cdp anyway)
  *
  * Extracted from service.ts during the v0.2.x refactor pass so the main
  * file can be a thin orchestrator.
  */
-import { checkCdpStatus, focusDebugTab } from '../playwright/cdpStatus.js';
+import { checkCdpStatus } from '../playwright/cdpStatus.js';
 import { launchDebugChrome } from '../playwright/launchChrome.js';
 import { send } from './types.js';
-/**
- * "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
- * either:
- *   - same-window  → normal, drives the page
- *   - wrong-window → disabled, with a "use the other window" notice
- *   - no-cdp       → enabled but click triggers launch-chrome instead
- */
-export async function handleCheckCdp(ws, msg, cdpUrl, extras) {
-    const pageUrl = msg.payload?.pageUrl;
-    if (typeof pageUrl !== 'string' || !pageUrl) {
-        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);
-    send(ws, { type: 'cdp-status', payload: status });
-}
 /**
  * Launch a debug Chrome navigated to `pageUrl`, then re-check status. The
  * re-check usually returns 'wrong-window' (because the widget asking is in
@@ -48,7 +25,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,39 +36,15 @@ export async function handleLaunchChrome(ws, msg, cdpUrl, extras) {
     const result = await launchDebugChrome({
         url: pageUrl,
         port,
-        userDataDir: extras?.userDataDir,
         proxy: extras?.proxy,
+        userDataDir: extras?.userDataDir,
+        headless: msg.payload?.headless === true,
+        force: msg.payload?.force === true,
     });
     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 });
 }
-/**
- * bringToFront the debug-Chrome tab matching `pageUrl`'s origin (or open one
- * if none exists). Used by the wrong-window UI's "switch to debug Chrome"
- * button. Doesn't return cdp-status — bringToFront doesn't change anything
- * the widget cares about, and the widget the user is about to focus is a
- * different page (and will run its own check-cdp on its own ws connection).
- */
-export async function handleFocusDebug(ws, msg, cdpUrl, extras) {
-    const pageUrl = msg.payload?.pageUrl;
-    if (typeof pageUrl !== 'string' || !pageUrl) {
-        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);
-    if (!result.ok) {
-        send(ws, { type: 'error', payload: { message: `focus-debug: ${result.reason}` } });
-    }
-}

package/dist/service/cdpHint.d.ts

@@ -1,27 +1,24 @@
 /**
  * System-prompt addendum sent to the agent on every command.
  *
- * Two roles:
- *   1. Navigation rules — the most failure-prone agent behaviours are
- *      `browser_navigate` to same-origin paths (kills the widget) and
- *      reading the JS bundle for credentials. We tell the agent both
- *      mistakes by name, including the actual origin to forbid.
- *   2. Narration format — how the widget renders the run depends on the
- *      agent emitting short imperative one-liners before each logical
- *      step. The good/bad examples are present-tense and 3–8 words.
+ * Principle-first and deliberately short (v0.16 prompt-trim pass). With
+ * Opus 4.x, emphatic "do NOT / CRITICAL" rule-stacking over-triggers and the
+ * middle of a long prompt gets ignored, so behaviour is steered with a few
+ * stated principles — each negative carrying its reason — rather than an
+ * enumerated rule list. Ordering follows attention, not chronology: the
+ * highest-value instructions (verify, trust boundary, scope) sit at the top,
+ * the volatile tab snapshot at the very bottom.
  *
  * 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.
+ * repo and the easiest to break with a typo. Tests import it 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.
+ * Two-tier split (prompt-cache aware):
+ *   - `buildCdpHint(tabs)`: the full block. First turn of a session (no
+ *     `--resume`).
+ *   - `buildCdpHintResume(tabs)`: ONLY the volatile tab list — the rules
+ *     persist in the agent's context from turn 1. Re-sending the stable rules
+ *     each turn would fragment Anthropic's prompt cache and bill ~500 extra
+ *     input tokens per turn for zero behavioural change.
  */
 interface Tab {
     url: string;
@@ -32,16 +29,12 @@ 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.
+ * 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 drifts
+ * between turns (user opens a second tab, switches focus).
  */
 export declare function buildCdpHintResume(tabs: Tab[]): string;
 export {};

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,CAmJhD;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;;;;;;;;;;;;;;;;;;;;;GAqBG;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,CAgGhD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAYtD"}