@hover-dev/core 0.14.1 → 0.15.0

package/README.md

@@ -26,6 +26,78 @@ The local Node service. Owns:
 
 To add an agent: implement an `AgentDescriptor`, register it in `registry.ts`. Done.
 
+## Spec generation (specs/)
+
+A verified session crystallizes into a standard `@playwright/test` file under
+`<devRoot>/__vibe_tests__/`. Translation is **deterministic — no LLM on the
+per-save path** (reproducible by construction):
+
+- `writeSpec.ts` walks the captured `browser_*` actions and emits one Playwright
+  call each (`getByRole` / `getByLabel` / `getByText` selectors — never XPath).
+  A few high-frequency multi-action shapes are hardcoded (popup / new-tab →
+  `Promise.all([context.waitForEvent('page'), …click()])`). An action with no
+  single-step translation (file upload, drag, …) leaves a structured
+  `// hover:optimizable: <tool>` marker rather than a `// TODO` — the draft stays
+  runnable around it. `countOptimizableMarkers()` reads the count back; `listSpecs`
+  surfaces it as `SpecSummary.optimizableCount`.
+- Alongside the `.spec.ts`, a **sidecar** is written to
+  `.hover/<slug>.json` — the structured `SpecStep[]` + observed signals. This is
+  the machine-readable behavior record the optimization pass reads (it keeps the
+  spec itself clean).
+
+### Optional optimization pass (F7)
+
+The **service** (never the sandboxed browser agent) can optionally run an LLM
+**codegen** call over a draft to polish it — chiefly to add assertions for the
+feedback the session observed. Its input is data the service already holds (the
+draft + sidecar + relevant seeds), not live page content, so it sits outside the
+agent's prompt-injection surface and needs no filesystem access. It writes an
+**optimization candidate** to `.hover/optimized/<slug>.spec.ts.draft` (never
+`*.spec.ts`, so the test runner can't collect an unreviewed candidate). A human
+promotes or discards it via diff — **the deterministic original is always
+preserved**. Off by default.
+
+### Seed library — extending translation (`.hover/rules/`)
+
+The optimization pass generalizes from **seeds**: human-written worked examples
+of "captured steps → the Playwright code they should produce." This is how
+coverage of new multi-step patterns grows **without core changes** — you (or the
+community) drop a JSON file; the pass picks it up as few-shot.
+
+A seed lives at `<projectRoot>/.hover/rules/<name>.json` and matches
+[`src/specs/seed.schema.json`](src/specs/seed.schema.json):
+
+```json
+{
+  "name": "oauth-popup",
+  "signature": ["browser_click", "browser_tabs:select"],
+  "note": "sign in through a provider popup that opens a new tab",
+  "example": {
+    "steps": [
+      { "tool": "browser_click", "element": "Sign in with Google button" },
+      { "tool": "browser_tabs", "action": "select", "idx": 1 }
+    ],
+    "code": "const [popup] = await Promise.all([\n  context.waitForEvent('page'),\n  page.getByRole('button', { name: 'Sign in with Google' }).click(),\n]);\nawait popup.getByLabel('Email').fill('user@example.com');"
+  }
+}
+```
+
+- **`signature`** is a cheap relevance filter only — `relevantSeeds()` keeps a
+  seed if any of its base tools (`browser_tabs:select` → `browser_tabs`) appears
+  in the spec being optimized. It is **not** exact-matched.
+- **`code`** must obey the same rules as generated specs: semantic selectors, no
+  XPath, no `waitForTimeout`.
+- **Built-in seeds** ship in `src/specs/seeds.ts` (`BUILTIN_SEEDS`). The bar to
+  be built-in is high — only **highly certain**, app-agnostic, deterministic
+  patterns qualify (currently just `download`). Semantic / judgement-based
+  optimizations (e.g. *which* feedback text to assert) are not seeds — they're
+  standing instructions in the prompt. Popup is hardcoded in `writeSpec.ts`, not
+  a seed. Speculative or project-specific patterns belong in your own
+  `.hover/rules/`, where the bar is your call.
+
+`readSeeds(projectRoot)` returns built-ins + your `.hover/rules/*.json`
+(malformed files are skipped, not fatal).
+
 ## Smoke test
 
 ```bash
@@ -56,7 +128,7 @@ Environment variables:
 The `claude -p` invocation is locked down so Claude can only drive the browser:
 
 - `--strict-mcp-config` — ignore any MCP servers in `~/.claude/` or `.mcp.json`
-- `--allowedTools mcp__playwright Skill` — only Playwright MCP and the Skill tool are callable
+- `--allowedTools mcp__playwright` — only Playwright MCP is callable
 - `--disallowedTools Bash Edit Write Read Grep Glob Task WebFetch WebSearch EnterWorktree CronCreate …` — every built-in tool explicitly denied (full list in `CLAUDE_DEFAULT_DISALLOWED_TOOLS` in `claude.ts`)
 - `--permission-mode dontAsk` — anything not whitelisted aborts the run
 - `--max-budget-usd <n>` — optional hard $ ceiling per session (no default; pass `maxBudgetUsd` in plugin options or via the CLI flag to enable)

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

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA2C,MAAM,YAAY,CAAC;AA6G3F,eAAO,MAAM,WAAW,EAAE,eA0HzB,CAAC"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA2C,MAAM,YAAY,CAAC;AA0H3F,eAAO,MAAM,WAAW,EAAE,eA2HzB,CAAC"}

package/dist/agents/claude.js

@@ -60,6 +60,19 @@ const CLAUDE_DEFAULT_DISALLOWED_TOOLS = [
     'Monitor', 'TaskOutput', 'TaskStop',
     'AskUserQuestion',
     'ShareOnboardingGuide',
+    // Skills are loaded independently of the --allowedTools allow-list, so an
+    // allow-list of `mcp__playwright` does NOT block the `Skill` tool. Left
+    // through, the agent burns a turn "checking for a project skill first" and
+    // pollutes the crystallized spec with a junk `When · Skill` step. Deny it.
+    'Skill',
+    // Playwright MCP's arbitrary-JS tools. browser_run_code_unsafe /
+    // browser_evaluate run any JS in the page — a real prompt-injection exfil
+    // path (fetch a token out, read localStorage) that punches through the
+    // "Playwright MCP only" sandbox, and their output can't be translated into
+    // a deterministic Playwright spec anyway (it lands as a `// TODO`). Agents
+    // drive via click/fill/select and read state via snapshot instead.
+    'mcp__playwright__browser_run_code_unsafe',
+    'mcp__playwright__browser_evaluate',
 ];
 export const claudeAgent = {
     id: 'claude',
@@ -68,6 +81,7 @@ export const claudeAgent = {
     streamFormat: 'stream-json',
     sandboxStrength: 'hard',
     defaultDisallowedTools: CLAUDE_DEFAULT_DISALLOWED_TOOLS,
+    apiKeyEnv: 'ANTHROPIC_API_KEY',
     display: {
         label: 'Claude Code',
         tagline: 'Anthropic — best-in-class browser driving, hard tool sandbox',

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

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

package/dist/agents/codex.js

@@ -59,6 +59,7 @@ export const codexAgent = {
     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)',

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,CAsElF"}
+{"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"}

package/dist/agents/invoke.js

@@ -31,7 +31,16 @@ 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.
-        env: { ...process.env, CLAUDECODE: '' },
+        // 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.
+        env: {
+            ...process.env,
+            CLAUDECODE: '',
+            ...(opts.apiKey && descriptor.apiKeyEnv
+                ? { [descriptor.apiKeyEnv]: opts.apiKey }
+                : {}),
+        },
     });
     const onAbort = () => {
         if (!child.killed)

package/dist/agents/types.d.ts

@@ -31,6 +31,11 @@ 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;
     /** 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;
@@ -151,6 +156,12 @@ 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;
     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":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,OAAO,GACP,KAAK,GACL,QAAQ,CAAC;AAEb,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,KAAK,GACL,YAAY,GACZ,YAAY,CAAC;AAEjB,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAI5C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;yCAGqC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;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"}

package/dist/playwright/resolveMcpConfig.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"resolveMcpConfig.d.ts","sourceRoot":"","sources":["../../src/playwright/resolveMcpConfig.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B;2EACuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;2CAIuC;IACvC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAgDT"}
+{"version":3,"file":"resolveMcpConfig.d.ts","sourceRoot":"","sources":["../../src/playwright/resolveMcpConfig.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B;2EACuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;2CAIuC;IACvC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;kFAG8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,CAiDT"}

package/dist/playwright/resolveMcpConfig.js

@@ -19,7 +19,8 @@ export function resolveMcpConfig(opts) {
     // can't actually load. `process.cwd()` is the user's project root,
     // and `@playwright/mcp` is always reachable from there because it's
     // a declared dependency of `@hover-dev/core`, which the user installed.
-    const require = createRequire(resolve(process.cwd(), 'package.json'));
+    // The caller may override with an explicit `cwd` (e.g. `hover run --cwd`).
+    const require = createRequire(resolve(opts.cwd ?? process.cwd(), 'package.json'));
     const pkgJsonPath = require.resolve('@playwright/mcp/package.json');
     const pkgRoot = dirname(pkgJsonPath);
     // The package's `bin` map declares "playwright-mcp": "cli.js" — we

package/dist/runSession.d.ts

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

package/dist/runSession.d.ts.map

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

package/dist/runSession.js

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

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

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

package/dist/service/cdpHint.js

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

package/dist/service/conventions.d.ts

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

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

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

package/dist/service/conventions.js

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

package/dist/service/saveHandlers.d.ts

@@ -1,17 +1,15 @@
 /**
- * Save-artifact WebSocket handlers (skill / spec / Jira CSV).
+ * Save-artifact WebSocket handlers (spec / Jira CSV).
  *
- * All three save-* messages share the same shape: validate `name + steps`,
- * call a per-kind writer, fork on Exists-error vs. success. The differences
- * (which writer, which message names, which fields to pluck, skill's
- * "push a fresh skills-list afterwards" tail) are captured in the
- * `SaveArtifactConfig` descriptor table below.
- *
- * Replaces three near-identical handlers that drifted apart over time —
- * see the v0.2.x refactor pass for the full rationale.
+ * Both save-* messages share the same shape: validate `name + steps`, call a
+ * per-kind writer, fork on Exists-error vs. success. The differences (which
+ * writer, which message names, which fields to pluck) are captured in the
+ * `SaveArtifactConfig` descriptor table below. (Save-as-Skill was retired; the
+ * generic `onSaved` hook it used is kept for any future artifact that needs a
+ * post-write tail.)
  */
 import type { WebSocket } from 'ws';
-import { writeSkill, type SkillStep } from '../skills/writeSkill.js';
+import { type SkillStep } from '../skills/writeSkill.js';
 import { writeSpec, type SpecAssertion } from '../specs/writeSpec.js';
 import { writeCaseCsv } from '../specs/writeCaseCsv.js';
 import { type ClientMessage } from './types.js';
@@ -25,8 +23,8 @@ interface SaveArtifactConfig<TWriteResult extends {
     savedType: string;
     /** Emitted when the writer threw an Exists-error. */
     existsType: string;
-    /** Optional — fires after a successful write. Used by the skill flow to
-     *  push a refreshed `skills-list` to the widget. */
+    /** Optional — fires after a successful write (e.g. to push a refreshed list
+     *  to the widget). Currently unused; kept generic for future artifacts. */
     onSaved?: (ws: WebSocket, devRoot: string) => Promise<void>;
     /** Class used in `err instanceof …` to detect "already exists" errors. */
     ExistsError: new (...args: never[]) => {
@@ -48,7 +46,6 @@ export declare function handleSaveArtifact<TWriteResult extends {
     slug: string;
     path: string;
 }>(ws: WebSocket, msg: ClientMessage, devRoot: string, cfg: SaveArtifactConfig<TWriteResult>): Promise<void>;
-export declare const SKILL_CONFIG: SaveArtifactConfig<Awaited<ReturnType<typeof writeSkill>>>;
 export declare const SPEC_CONFIG: SaveArtifactConfig<Awaited<ReturnType<typeof writeSpec>>>;
 export declare const CASE_CSV_CONFIG: SaveArtifactConfig<Awaited<ReturnType<typeof writeCaseCsv>>>;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"saveHandlers.d.ts","sourceRoot":"","sources":["../../src/service/saveHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,UAAU,EAAgC,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,EAAE,SAAS,EAAmB,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,YAAY,EAAsB,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD,UAAU,kBAAkB,CAAC,YAAY,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;IAC9E,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB;wDACoD;IACpD,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;IAC9E,wEAAwE;IACxE,KAAK,EAAE,CAAC,IAAI,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,SAAS,EAAE,CAAC;QACnB,UAAU,EAAE,aAAa,EAAE,CAAC;QAC5B,OAAO,EAAE,WAAW,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/C,SAAS,EAAE,OAAO,CAAC;KACpB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAC7B;AAED,wBAAsB,kBAAkB,CAAC,YAAY,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC1F,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,kBAAkB,CAAC,YAAY,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAED,eAAO,MAAM,YAAY,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAanF,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAOjF,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAYxF,CAAC"}
+{"version":3,"file":"saveHandlers.d.ts","sourceRoot":"","sources":["../../src/service/saveHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAmB,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,YAAY,EAAsB,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD,UAAU,kBAAkB,CAAC,YAAY,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;IAC9E,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB;+EAC2E;IAC3E,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,WAAW,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;IAC9E,wEAAwE;IACxE,KAAK,EAAE,CAAC,IAAI,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,SAAS,EAAE,CAAC;QACnB,UAAU,EAAE,aAAa,EAAE,CAAC;QAC5B,OAAO,EAAE,WAAW,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/C,SAAS,EAAE,OAAO,CAAC;KACpB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAC7B;AAED,wBAAsB,kBAAkB,CAAC,YAAY,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC1F,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,kBAAkB,CAAC,YAAY,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAED,eAAO,MAAM,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAOjF,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAYxF,CAAC"}

package/dist/service/saveHandlers.js

@@ -1,16 +1,13 @@
 /**
- * Save-artifact WebSocket handlers (skill / spec / Jira CSV).
+ * Save-artifact WebSocket handlers (spec / Jira CSV).
  *
- * All three save-* messages share the same shape: validate `name + steps`,
- * call a per-kind writer, fork on Exists-error vs. success. The differences
- * (which writer, which message names, which fields to pluck, skill's
- * "push a fresh skills-list afterwards" tail) are captured in the
- * `SaveArtifactConfig` descriptor table below.
- *
- * Replaces three near-identical handlers that drifted apart over time —
- * see the v0.2.x refactor pass for the full rationale.
+ * Both save-* messages share the same shape: validate `name + steps`, call a
+ * per-kind writer, fork on Exists-error vs. success. The differences (which
+ * writer, which message names, which fields to pluck) are captured in the
+ * `SaveArtifactConfig` descriptor table below. (Save-as-Skill was retired; the
+ * generic `onSaved` hook it used is kept for any future artifact that needs a
+ * post-write tail.)
  */
-import { writeSkill, listSkills, SkillExistsError } from '../skills/writeSkill.js';
 import { writeSpec, SpecExistsError } from '../specs/writeSpec.js';
 import { writeCaseCsv, CaseCsvExistsError } from '../specs/writeCaseCsv.js';
 import { send } from './types.js';
@@ -45,8 +42,8 @@ export async function handleSaveArtifact(ws, msg, devRoot, cfg) {
         return;
     }
     send(ws, { type: cfg.savedType, payload: { name: result.slug, path: result.path } });
-    // The artifact is already on disk; an onSaved failure (e.g. listSkills
-    // re-scan) shouldn't surface as if the save itself failed — log and move on.
+    // The artifact is already on disk; an onSaved failure (e.g. a follow-up
+    // list re-scan) shouldn't surface as if the save itself failed — log on.
     if (cfg.onSaved) {
         try {
             await cfg.onSaved(ws, devRoot);
@@ -57,19 +54,6 @@ export async function handleSaveArtifact(ws, msg, devRoot, cfg) {
         }
     }
 }
-export const SKILL_CONFIG = {
-    requestName: 'save-skill',
-    savedType: 'skill-saved',
-    existsType: 'skill-exists',
-    ExistsError: SkillExistsError,
-    write: ({ devRoot, name, description, steps, overwrite }) => writeSkill({ devRoot, name, description, steps, overwrite }),
-    onSaved: async (ws, devRoot) => {
-        // Push a fresh list so the widget's skills overlay updates without a
-        // round-trip — most relevant right after the save.
-        const skills = await listSkills(devRoot);
-        send(ws, { type: 'skills-list', payload: { skills } });
-    },
-};
 export const SPEC_CONFIG = {
     requestName: 'save-spec',
     savedType: 'spec-saved',

package/dist/service/types.d.ts

@@ -35,6 +35,11 @@ export interface ClientMessage {
         /** set-mode only — id of the plugin-contributed mode to activate,
          *  or null to return to normal (unmoded) operation. */
         modeId?: string | null;
+        /** optimize-spec / promote-optimized / discard-optimized — the spec slug. */
+        slug?: string;
+        /** set-api-key only — the model API key to inject into the spawned CLI's
+         *  env (or empty/missing to clear it). Held in memory only, never logged. */
+        key?: string;
     };
 }
 export declare function send(ws: WebSocket, message: {

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/service/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;uDAC+C;QAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;2DAEmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;+DACuD;QACvD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEtF;AAED;;;;sEAIsE;AACtE,wBAAgB,UAAU,CACxB,EAAE,EAAE,SAAS,EACb,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,OAAO,CAIT"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/service/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;uDAC+C;QAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;2DAEmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;+DACuD;QACvD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,6EAA6E;QAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;QACd;qFAC6E;QAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEtF;AAED;;;;sEAIsE;AACtE,wBAAgB,UAAU,CACxB,EAAE,EAAE,SAAS,EACb,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,OAAO,CAIT"}