@hover-dev/core 0.15.0 → 0.17.0

package/dist/agents/codex.js

@@ -1,3 +1,4 @@
+import { stripMcpPrefix } from './shared.js';
 /**
  * Pricing per million tokens. Keep in lockstep with claude.ts's table —
  * approximate published OpenAI rates as of 2026. We are deliberately
@@ -16,6 +17,9 @@ const PRICE_PER_M_USD = {
     'gpt-4o': { in: 2.5, out: 10 },
     'gpt-4': { in: 30, out: 60 },
 };
+// `modelHint` is currently always passed as undefined — the parser can't see
+// the invocation's --model — so the default tier below is what gets used. The
+// parameter is kept so a future caller that does have the model id can pass it.
 function estimateCostUsd(modelHint, usage) {
     const m = (modelHint ?? 'gpt-5.5').toLowerCase();
     // Match by longest-prefix so 'gpt-5.5-mini' picks up the 'gpt-5.5' tier.
@@ -28,7 +32,7 @@ function codexState(state) {
     if (typeof state.runningCost !== 'number') {
         state.runningCost = 0;
         state.runningTurns = 0;
-        state.runningModel = undefined;
+        state.runningTokens = 0;
         state.runningSessionId = undefined;
         state.lastAgentMessage = undefined;
         state.sawErrorEvent = false;
@@ -39,27 +43,32 @@ function codexState(state) {
 function resetCodexCounters(s) {
     s.runningCost = 0;
     s.runningTurns = 0;
-    s.runningModel = undefined;
+    s.runningTokens = 0;
     s.runningSessionId = undefined;
     s.lastAgentMessage = undefined;
     s.sawErrorEvent = false;
     s.itemTypeById.clear();
 }
-/** Cap surfaced as a constraint in the system prompt — codex has no CLI flag. */
-const CODEX_DEVELOPER_INSTRUCTIONS = [
-    'You are operating in Hover, a browser-testing tool.',
-    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
-    'Do NOT call shell, file-edit, web-search, or any other built-in tool.',
-    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
-    'When the task is complete, emit a short agent_message summary and stop.',
-].join(' ');
+/** The tool-restriction is codex's only sandbox (no --allowedTools flag), so it
+ *  must mirror the hard-sandbox allow-list the service computes per mode — NOT a
+ *  hardcoded "playwright only", which made codex refuse the active mode's plugin
+ *  tools (api_request, replay_flow, hover-control, …). Built from opts.allowedTools. */
+function codexDeveloperInstructions(allowedTools) {
+    const prefixes = (allowedTools && allowedTools.length ? allowedTools : ['mcp__playwright']).map((p) => `${p}__*`);
+    return [
+        'You are operating in Hover, a browser- and API-testing tool.',
+        `Use ONLY MCP tools whose name starts with one of these prefixes: ${prefixes.join(', ')}. They cover driving the browser, the Hover control + API-request tools, and reading source — everything the task needs.`,
+        'Do NOT call shell, file-edit, web-search, or any other built-in tool.',
+        'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
+        'When the task is complete, emit a short agent_message summary and stop.',
+    ].join(' ');
+}
 export const codexAgent = {
     id: 'codex',
     binName: 'codex',
     protocol: 'argv',
     streamFormat: 'json-lines',
     sandboxStrength: 'soft',
-    apiKeyEnv: 'OPENAI_API_KEY',
     display: {
         label: 'OpenAI Codex',
         tagline: 'OpenAI — soft sandbox (no built-in tool deny-list)',
@@ -85,13 +94,19 @@ export const codexAgent = {
         if (opts.model) {
             args.push('--model', opts.model);
         }
+        // Reasoning effort → the API's reasoning_effort, set via the `-c` TOML
+        // override (no stable long flag exists). Sits alongside the other -c keys.
+        if (opts.effort) {
+            args.push('-c', `model_reasoning_effort=${opts.effort}`);
+        }
         // System-prompt injection. Codex has no --append-system-prompt; we route
         // through `-c developer_instructions='...'`. Concatenate the standing
         // Hover-mode instructions with whatever the caller passes (e.g. "user is
         // already on http://localhost:5173/").
+        const base = codexDeveloperInstructions(opts.allowedTools);
         const sysPrompt = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
-            ? `${CODEX_DEVELOPER_INSTRUCTIONS} ${opts.appendSystemPrompt}`
-            : CODEX_DEVELOPER_INSTRUCTIONS;
+            ? `${base} ${opts.appendSystemPrompt}`
+            : base;
         args.push('-c', `developer_instructions=${JSON.stringify(sysPrompt)}`);
         // MCP servers are configured in ~/.codex/config.toml at install time,
         // not per-invocation. If the user passed an mcpConfig path, we don't
@@ -128,13 +143,13 @@ export const codexAgent = {
                 // The exact field names aren't published. Read defensively: prefer
                 // `name`, fall back to `tool`. Same for input.
                 const rawName = it.name ?? it.tool ?? '';
-                const tool = rawName.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
-                out.push({ kind: 'tool_use', tool, input: it.input ?? it.arguments, costUsdSnapshot: s.runningCost });
+                const tool = stripMcpPrefix(rawName);
+                out.push({ kind: 'tool_use', tool, input: it.input ?? it.arguments, costUsdSnapshot: s.runningCost, tokensSnapshot: s.runningTokens });
             }
             else if (it.type === 'command_execution') {
                 // We DISCOURAGED this in developer_instructions but the agent can
                 // still try. Surface it so the user sees it happen.
-                out.push({ kind: 'tool_use', tool: 'shell', input: { command: it.command }, costUsdSnapshot: s.runningCost });
+                out.push({ kind: 'tool_use', tool: 'shell', input: { command: it.command }, costUsdSnapshot: s.runningCost, tokensSnapshot: s.runningTokens });
             }
             return out;
         }
@@ -158,9 +173,13 @@ export const codexAgent = {
         if (ev.type === 'turn.completed') {
             s.runningTurns += 1;
             if (ev.usage) {
-                s.runningCost += estimateCostUsd(s.runningModel, ev.usage);
+                // The parser has no access to the invocation's --model, so we let
+                // estimateCostUsd fall back to its fixed default tier. Cost is a
+                // high-water "should I hit Stop now" signal, not an invoice.
+                s.runningCost += estimateCostUsd(undefined, ev.usage);
+                s.runningTokens += (ev.usage.input_tokens ?? 0) + (ev.usage.output_tokens ?? 0);
             }
-            out.push({ kind: 'usage', costUsd: s.runningCost, turns: s.runningTurns });
+            out.push({ kind: 'usage', costUsd: s.runningCost, turns: s.runningTurns, tokens: s.runningTokens });
             return out;
         }
         // Codex emits various error envelopes; we conservatively match anything
@@ -185,6 +204,7 @@ export const codexAgent = {
             kind: 'session_end',
             turns: s.runningTurns,
             costUsd: s.runningCost,
+            tokens: s.runningTokens,
             isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
             summary: s.lastAgentMessage,
         };

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

@@ -1 +1 @@
-{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/agents/gemini.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AA4K3F,eAAO,MAAM,WAAW,EAAE,eAiJzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/agents/gemini.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AA+J3F,eAAO,MAAM,WAAW,EAAE,eAiJzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}

package/dist/agents/gemini.js

@@ -1,3 +1,4 @@
+import { HOVER_PROMPT_PREFACE, stripMcpPrefix } from './shared.js';
 function geminiState(state) {
     if (typeof state.runningTurns !== 'number') {
         state.runningTurns = 0;
@@ -17,11 +18,6 @@ function resetGeminiCounters(s) {
     s.sawErrorEvent = false;
     s.toolNameByUseId.clear();
 }
-/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
- *  names match the normalised names claude / codex / cursor / qwen emit. */
-function stripMcpPrefix(raw) {
-    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
-}
 /**
  * Extract assistant text from a `message` event whose `content` may be a
  * plain string OR an array of `{type:'text', text}` content blocks. Gemini's
@@ -41,13 +37,6 @@ function extractMessageText(ev) {
     }
     return undefined;
 }
-const GEMINI_PROMPT_PREFACE = [
-    'You are operating in Hover, a browser-testing tool.',
-    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
-    'Do NOT use shell, file-edit, web-search, or any other built-in tool.',
-    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
-    'When the task is complete, emit a short summary and stop.',
-].join(' ');
 export const geminiAgent = {
     id: 'gemini',
     binName: 'gemini',
@@ -65,8 +54,8 @@ export const geminiAgent = {
         // GEMINI_SYSTEM_MD env var which writes a file). Prepend the HOVER-mode
         // preface to the prompt instead — same pattern as cursor.ts / aider.ts.
         const preface = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
-            ? `${GEMINI_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
-            : GEMINI_PROMPT_PREFACE;
+            ? `${HOVER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : HOVER_PROMPT_PREFACE;
         const finalPrompt = `${preface}\n\n${opts.prompt}`;
         const args = ['-p', finalPrompt];
         // NDJSON streaming output.

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

@@ -1 +1 @@
-{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/agents/invoke.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAuB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,WAAW,CAAC,CA+ElF"}
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/agents/invoke.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAuB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,WAAW,CAAC,CA4ElF"}

package/dist/agents/invoke.js

@@ -31,15 +31,12 @@ export async function* invokeAgent(opts) {
         cwd: opts.cwd,
         // Clear CLAUDECODE so spawning `claude` from inside a Claude Code session
         // doesn't trip the nested-session guard. Harmless for other agents.
-        // If the caller supplied an API key and the descriptor names a key env var,
-        // inject it so the CLI runs on the key instead of a logged-in subscription.
-        // The key lives only in this child's env — never logged, never persisted.
+        // The CLI authenticates via its own logged-in subscription (or inherits any
+        // key already in process.env); opts.env carries the Local LLM endpoint vars.
         env: {
             ...process.env,
             CLAUDECODE: '',
-            ...(opts.apiKey && descriptor.apiKeyEnv
-                ? { [descriptor.apiKeyEnv]: opts.apiKey }
-                : {}),
+            ...(opts.env ?? {}),
         },
     });
     const onAbort = () => {

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

@@ -1 +1 @@
-{"version":3,"file":"qwen.d.ts","sourceRoot":"","sources":["../../src/agents/qwen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AAiK3F,eAAO,MAAM,SAAS,EAAE,eAqJvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}
+{"version":3,"file":"qwen.d.ts","sourceRoot":"","sources":["../../src/agents/qwen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AAoJ3F,eAAO,MAAM,SAAS,EAAE,eAqJvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}

package/dist/agents/qwen.js

@@ -1,3 +1,4 @@
+import { HOVER_PROMPT_PREFACE, stripMcpPrefix } from './shared.js';
 function qwenState(state) {
     if (typeof state.runningTurns !== 'number') {
         state.runningTurns = 0;
@@ -17,18 +18,6 @@ function resetQwenCounters(s) {
     s.sawErrorEvent = false;
     s.toolNameByUseId.clear();
 }
-/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
- *  names match the normalised names claude / codex / cursor emit. */
-function stripMcpPrefix(raw) {
-    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
-}
-const QWEN_PROMPT_PREFACE = [
-    'You are operating in Hover, a browser-testing tool.',
-    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
-    'Do NOT use shell, file-edit, web-search, or any other built-in tool.',
-    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
-    'When the task is complete, emit a short summary and stop.',
-].join(' ');
 export const qwenAgent = {
     id: 'qwen',
     binName: 'qwen',
@@ -62,8 +51,8 @@ export const qwenAgent = {
         // prepending to the user prompt. Concatenate the standing Hover-mode
         // preface with whatever the caller appended.
         const sysPrompt = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
-            ? `${QWEN_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
-            : QWEN_PROMPT_PREFACE;
+            ? `${HOVER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : HOVER_PROMPT_PREFACE;
         args.push('--append-system-prompt', sysPrompt);
         // MCP servers configured in ~/.qwen/settings.json — no per-invocation
         // --mcp-config equivalent. Same constraint as cursor / codex.

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

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAQlD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAOlD,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,eAAe,EAAE,CAE9C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAKlD,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,eAAe,EAAE,CAE9C"}

package/dist/agents/registry.js

@@ -1,7 +1,5 @@
 import { claudeAgent } from './claude.js';
 import { codexAgent } from './codex.js';
-import { cursorAgent } from './cursor.js';
-import { aiderAgent } from './aider.js';
 import { geminiAgent } from './gemini.js';
 import { qwenAgent } from './qwen.js';
 /**
@@ -20,8 +18,6 @@ import { qwenAgent } from './qwen.js';
 export const AGENTS = {
     [claudeAgent.id]: claudeAgent,
     [codexAgent.id]: codexAgent,
-    [cursorAgent.id]: cursorAgent,
-    [aiderAgent.id]: aiderAgent,
     [geminiAgent.id]: geminiAgent,
     [qwenAgent.id]: qwenAgent,
 };

package/dist/agents/shared.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cross-agent helpers shared by the soft-sandbox descriptors
+ * (codex / cursor / gemini / qwen / aider).
+ *
+ * These agents all need the same two things:
+ *   1. A standing "HOVER-mode" instruction preface that tells the agent to
+ *      drive the browser via the Playwright MCP tools only and not to touch
+ *      its built-in shell / file-edit tools. Each agent injects it through a
+ *      different channel (cursor / gemini / aider prepend it to the prompt,
+ *      qwen passes it via --append-system-prompt, codex via
+ *      `-c developer_instructions=`), so this module owns only the *text*, not
+ *      the injection.
+ *   2. Normalising the `mcp__playwright__` / `mcp__hover-playwright__` prefix
+ *      off a raw tool name so the emitted tool names line up across agents.
+ *
+ * codex deliberately does NOT use HOVER_PROMPT_PREFACE — it keeps its own
+ * wording ("Do NOT call …", "emit a short agent_message summary …") that is
+ * tuned to codex's event vocabulary. See codex.ts.
+ */
+/**
+ * The standing HOVER-mode instruction shared by cursor / gemini / qwen / aider.
+ * codex carries a near-identical but intentionally different variant inline.
+ */
+export declare const HOVER_PROMPT_PREFACE: string;
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names every agent emits. */
+export declare function stripMcpPrefix(raw: string): string;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/agents/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAMtB,CAAC;AAEZ;0DAC0D;AAC1D,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/agents/shared.js

@@ -0,0 +1,35 @@
+/**
+ * Cross-agent helpers shared by the soft-sandbox descriptors
+ * (codex / cursor / gemini / qwen / aider).
+ *
+ * These agents all need the same two things:
+ *   1. A standing "HOVER-mode" instruction preface that tells the agent to
+ *      drive the browser via the Playwright MCP tools only and not to touch
+ *      its built-in shell / file-edit tools. Each agent injects it through a
+ *      different channel (cursor / gemini / aider prepend it to the prompt,
+ *      qwen passes it via --append-system-prompt, codex via
+ *      `-c developer_instructions=`), so this module owns only the *text*, not
+ *      the injection.
+ *   2. Normalising the `mcp__playwright__` / `mcp__hover-playwright__` prefix
+ *      off a raw tool name so the emitted tool names line up across agents.
+ *
+ * codex deliberately does NOT use HOVER_PROMPT_PREFACE — it keeps its own
+ * wording ("Do NOT call …", "emit a short agent_message summary …") that is
+ * tuned to codex's event vocabulary. See codex.ts.
+ */
+/**
+ * The standing HOVER-mode instruction shared by cursor / gemini / qwen / aider.
+ * codex carries a near-identical but intentionally different variant inline.
+ */
+export const HOVER_PROMPT_PREFACE = [
+    'You are operating in Hover, a browser-testing tool.',
+    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
+    'Do NOT use shell, file-edit, web-search, or any other built-in tool.',
+    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
+    'When the task is complete, emit a short summary and stop.',
+].join(' ');
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names every agent emits. */
+export function stripMcpPrefix(raw) {
+    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
+}

package/dist/agents/types.d.ts

@@ -23,7 +23,15 @@ export interface InvokeOptions {
     allowedTools?: string[];
     disallowedTools?: string[];
     maxBudgetUsd?: number;
+    /** Hard ceiling on agent turns (~steps) — claude `--max-turns`. Used by QA
+     *  intensity to bound an exploratory run by step count. */
+    maxTurns?: number;
     model?: string;
+    /** Reasoning-effort level for the run. claude → `--effort <level>` (low /
+     *  medium / high / xhigh / max); codex → `-c model_reasoning_effort=<level>`
+     *  (minimal / low / medium / high / xhigh). The caller is responsible for
+     *  passing a level the chosen model actually supports. */
+    effort?: string;
     cwd?: string;
     sessionId?: string;
     /** Extra text appended to the agent's system prompt (claude: via
@@ -31,11 +39,10 @@ export interface InvokeOptions {
      *  "the user's current Chrome tab is already on http://localhost:5173/,
      *  don't browser_navigate there". */
     appendSystemPrompt?: string;
-    /** Optional model API key. Injected into the spawned CLI's environment under
-     *  the descriptor's `apiKeyEnv` var (e.g. ANTHROPIC_API_KEY) so a user without
-     *  a logged-in subscription can drive Hover with their own key. Never logged,
-     *  never persisted server-side — held only for the lifetime of the spawn. */
-    apiKey?: string;
+    /** Extra environment variables for the spawned CLI (merged over process.env).
+     *  Used for the "Local LLM" path: qwen-code reads OPENAI_BASE_URL /
+     *  OPENAI_API_KEY to target a user's self-hosted OpenAI-compatible endpoint. */
+    env?: Record<string, string>;
     /** Aborts the spawned child if signaled. Used to stop an orphan run when
      *  the WebSocket caller disconnects (e.g. user reloads the dev page). */
     signal?: AbortSignal;
@@ -57,6 +64,7 @@ export type InvokeEvent = {
     tool: string;
     input: unknown;
     costUsdSnapshot?: number;
+    tokensSnapshot?: number;
 } | {
     kind: 'tool_result';
     isError?: boolean;
@@ -73,6 +81,7 @@ export type InvokeEvent = {
     kind: 'usage';
     costUsd?: number;
     turns?: number;
+    tokens?: number;
 }
 /** End-of-session event. Three terminal states the widget renders distinctly:
  *
@@ -87,6 +96,7 @@ export type InvokeEvent = {
     kind: 'session_end';
     turns?: number;
     costUsd?: number;
+    tokens?: number;
     isError?: boolean;
     cancelled?: boolean;
     summary?: string;
@@ -156,12 +166,10 @@ export interface AgentDescriptor {
      *  per-CLI deny list live alongside its descriptor instead of as a magic
      *  array in the service. Soft-sandbox agents leave this undefined. */
     defaultDisallowedTools?: readonly string[];
-    /** Environment variable this CLI reads its model API key from
-     *  (claude: ANTHROPIC_API_KEY, codex: OPENAI_API_KEY). When set and the
-     *  caller supplies `InvokeOptions.apiKey`, the key is injected into the spawn
-     *  env so the user can run on a raw key instead of a logged-in subscription.
-     *  Undefined for agents that have no API-key env path. */
-    apiKeyEnv?: string;
+    /** A cheap/fast model id for non-interactive refinement work (the F7 optimize
+     *  pass) where the big model isn't worth the cost. Used when the user hasn't
+     *  set `hover.optimizeModel`; undefined → fall back to the session model. */
+    cheapModel?: string;
     buildArgs(opts: InvokeOptions): string[];
     /**
      * Parse a single line of agent stdout into normalised InvokeEvents.

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

@@ -1 +1 @@
-{"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;;;iFAG6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;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;;;0EAGsE;IACtE,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;8DAI0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,53 @@
+export { runSession } from './runSession.js';
+export type { RunSessionOptions, RunSessionResult } from './runSession.js';
+export { writeSpec } from './specs/writeSpec.js';
+export type { WriteSpecOptions, WriteSpecResult, Redaction } from './specs/writeSpec.js';
+export type { SkillStep } from './specs/specStep.js';
+export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
+export type { ReplayResult, ReplayFailure, ReplayStep, GroundedTarget } from './specs/replayGrounded.js';
+export { resolveMcpConfig, mcpToolPrefix } from './playwright/resolveMcpConfig.js';
+export { launchDebugChrome, closeDebugChrome, findChromeBinary } from './playwright/launchChrome.js';
+export type { LaunchOptions, LaunchResult } from './playwright/launchChrome.js';
+export { GROUNDED_ACTUATION_DENY, GROUNDED_ACTUATION_DIRECTIVE } from './agentDirectives.js';
+export { loadMemory, formatMemoryForPrompt, writeFact, memoryDir } from './memory/businessMemory.js';
+export type { BusinessFact } from './memory/businessMemory.js';
+export { RECON_DIRECTIVE, QA_EXPLORATION_DIRECTIVE } from './agentDirectives.js';
+export { QA_INTENSITY, DEFAULT_QA_INTENSITY, asQaIntensity, qaBudgetDirective } from './qa/intensity.js';
+export type { QaIntensity, QaIntensitySpec } from './qa/intensity.js';
+/**
+ * The always-on control-actuation MCP server id. Alphanumeric on purpose — a
+ * hyphen would make the hard-sandbox allow prefix (`mcp__hovercontrol`) fail to
+ * match the tool names (`mcp__hovercontrol__click_control`), so every grounded
+ * actuation would be denied. (Same constant + reasoning as service.ts.)
+ */
+export declare const CONTROL_MCP_ID = "hovercontrol";
+/** The hard-sandbox allow prefix for the control server — pass in
+ *  `runSession({ allowedToolsExtra: [CONTROL_MCP_TOOL_PREFIX] })`. */
+export declare const CONTROL_MCP_TOOL_PREFIX: string;
+export interface GroundedMcpOptions {
+    /** CDP endpoint of the debug Chrome the agent drives. */
+    cdpUrl: string;
+    /** Port used only to namespace the generated config filename. */
+    port: number;
+    /** Project root — where the control server resolves relative paths / writes
+     *  its placeholder upload fixture, and where `@playwright/mcp` resolves from. */
+    devRoot: string;
+    /** The dev-server origin the run targets (defaults to `cdpUrl`). */
+    devUrl?: string;
+    /** WS port the control server's back-channel (`ask_user` / `record_*`)
+     *  connects to. Omit when there's no listener — actuation still works; the
+     *  back-channel features silently no-op (actuateServer fails soft). */
+    approvalPort?: number;
+    /** Directory the Playwright MCP + control screenshots write into. */
+    outputDir?: string;
+}
+/**
+ * Build an MCP config mirroring the service's grounded/normal mode: the
+ * Playwright MCP over CDP PLUS the hover-control actuation server. Pair it in
+ * `runSession` with `allowedToolsExtra: [CONTROL_MCP_TOOL_PREFIX]`,
+ * `disallowedToolsExtra: GROUNDED_ACTUATION_DENY`, and append
+ * `GROUNDED_ACTUATION_DIRECTIVE` to the system prompt — then the selectors the
+ * agent actuates with are the ones crystallized (record==replay).
+ */
+export declare function buildGroundedMcpConfig(opts: GroundedMcpOptions): string;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACzF,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACjH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGzG,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAG7F,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACrG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAM/D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzG,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAE7C;sEACsE;AACtE,eAAO,MAAM,uBAAuB,QAAgC,CAAC;AAMrE,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb;qFACiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;2EAEuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAqBvE"}

package/dist/engine.js

@@ -0,0 +1,78 @@
+/**
+ * In-process engine surface for non-service consumers — the `hover` CLI and the
+ * `@hover-dev/mcp` server. The VS Code extension drives core through the WS
+ * service (`./service`); a standalone process instead calls `runSession`
+ * directly. This barrel exposes the same building blocks the service composes —
+ * the session run, the GROUNDED MCP config (so a CLI-authored spec gets the
+ * record==replay fidelity the extension does), and spec crystallization —
+ * without the WebSocket layer.
+ *
+ * Keep this a thin re-export + the one `buildGroundedMcpConfig` helper. The
+ * grounded path here MUST stay in lock-step with `service.ts`'s normal-mode
+ * assembly (the control-actuation server + `GROUNDED_ACTUATION_DENY` /
+ * `GROUNDED_ACTUATION_DIRECTIVE`), or CLI specs would drift from extension specs.
+ */
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveMcpConfig, mcpToolPrefix } from './playwright/resolveMcpConfig.js';
+// ── in-process session + crystallization ─────────────────────────────────────
+export { runSession } from './runSession.js';
+export { writeSpec } from './specs/writeSpec.js';
+// Creation-verification: replay a flow's grounded steps over CDP (no playwright test).
+export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
+// ── browser / MCP plumbing ───────────────────────────────────────────────────
+export { resolveMcpConfig, mcpToolPrefix } from './playwright/resolveMcpConfig.js';
+export { launchDebugChrome, closeDebugChrome, findChromeBinary } from './playwright/launchChrome.js';
+// ── grounded-actuation knobs (must match service.ts) ─────────────────────────
+export { GROUNDED_ACTUATION_DENY, GROUNDED_ACTUATION_DIRECTIVE } from './agentDirectives.js';
+// ── business memory (ask → remember loop; shared with the extension's QA mode) ─
+export { loadMemory, formatMemoryForPrompt, writeFact, memoryDir } from './memory/businessMemory.js';
+// ── autonomous-exploration directives (QA mode reuse) ────────────────────────
+// The CLI's "explore → discover business flows → record_candidate" loop is the
+// same mechanism QA mode drives the agent with; reuse the directives verbatim
+// so behaviour stays in lock-step.
+export { RECON_DIRECTIVE, QA_EXPLORATION_DIRECTIVE } from './agentDirectives.js';
+export { QA_INTENSITY, DEFAULT_QA_INTENSITY, asQaIntensity, qaBudgetDirective } from './qa/intensity.js';
+/**
+ * The always-on control-actuation MCP server id. Alphanumeric on purpose — a
+ * hyphen would make the hard-sandbox allow prefix (`mcp__hovercontrol`) fail to
+ * match the tool names (`mcp__hovercontrol__click_control`), so every grounded
+ * actuation would be denied. (Same constant + reasoning as service.ts.)
+ */
+export const CONTROL_MCP_ID = 'hovercontrol';
+/** The hard-sandbox allow prefix for the control server — pass in
+ *  `runSession({ allowedToolsExtra: [CONTROL_MCP_TOOL_PREFIX] })`. */
+export const CONTROL_MCP_TOOL_PREFIX = mcpToolPrefix(CONTROL_MCP_ID);
+// dist/engine.js sits beside dist/service.js, so mcp/actuateServer.js resolves
+// the same way it does from service.ts.
+const CONTROL_MCP_SCRIPT = resolve(dirname(fileURLToPath(import.meta.url)), 'mcp', 'actuateServer.js');
+/**
+ * Build an MCP config mirroring the service's grounded/normal mode: the
+ * Playwright MCP over CDP PLUS the hover-control actuation server. Pair it in
+ * `runSession` with `allowedToolsExtra: [CONTROL_MCP_TOOL_PREFIX]`,
+ * `disallowedToolsExtra: GROUNDED_ACTUATION_DENY`, and append
+ * `GROUNDED_ACTUATION_DIRECTIVE` to the system prompt — then the selectors the
+ * agent actuates with are the ones crystallized (record==replay).
+ */
+export function buildGroundedMcpConfig(opts) {
+    return resolveMcpConfig({
+        cdpUrl: opts.cdpUrl,
+        port: opts.port,
+        cwd: opts.devRoot,
+        outputDir: opts.outputDir,
+        extra: [
+            {
+                id: CONTROL_MCP_ID,
+                command: process.execPath,
+                args: [CONTROL_MCP_SCRIPT],
+                env: {
+                    HOVER_CDP_URL: opts.cdpUrl,
+                    HOVER_DEV_URL: opts.devUrl ?? opts.cdpUrl,
+                    HOVER_PROJECT_ROOT: opts.devRoot,
+                    ...(opts.approvalPort ? { HOVER_APPROVAL_PORT: String(opts.approvalPort) } : {}),
+                    ...(opts.outputDir ? { HOVER_SHOT_DIR: opts.outputDir } : {}),
+                },
+            },
+        ],
+    });
+}

package/dist/mcp/actuateServer.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=actuateServer.d.ts.map

package/dist/mcp/actuateServer.d.ts.map

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