@peekdev/mcp 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -0,0 +1,163 @@
+<img src="https://raw.githubusercontent.com/Cubenest/rrweb-stack/main/assets/brand/sub-peek.svg" height="40" alt="peek">
+
+# @peekdev/mcp
+
+> Your real browser, exposed to your AI coding agent over MCP — capture once, query forever, never leaves your machine.
+
+[![npm](https://img.shields.io/npm/v/@peekdev/mcp.svg)](https://www.npmjs.com/package/@peekdev/mcp)
+[![downloads](https://img.shields.io/npm/dw/@peekdev/mcp.svg)](https://www.npmjs.com/package/@peekdev/mcp)
+[![license](https://img.shields.io/npm/l/@peekdev/mcp.svg)](https://github.com/Cubenest/rrweb-stack/blob/main/LICENSE)
+[![CI](https://github.com/Cubenest/rrweb-stack/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Cubenest/rrweb-stack/actions/workflows/ci.yml)
+[![rrweb-stack MCP server](https://glama.ai/mcp/servers/Cubenest/rrweb-stack/badges/score.svg)](https://glama.ai/mcp/servers/Cubenest/rrweb-stack)
+
+Docs: <https://peek.cubenest.in>
+
+`@peekdev/mcp` is **two things in one binary**:
+
+1. The **stdio MCP server** that AI coding agents (Claude Code, Cursor, Cline, Windsurf, Continue, Zed) speak to when querying your captured browser sessions.
+2. The **native messaging host** that Chrome's MV3 extension speaks to when writing into `~/.peek/sessions.db`.
+
+The same binary handles both roles — chosen by argv. You don't install this package directly in normal use; the [`@peekdev/cli`](https://www.npmjs.com/package/@peekdev/cli) `peek init` wizard wires it into your AI client's MCP config and into Chrome's `NativeMessagingHosts/`.
+
+> **Requires Node.js ≥ 22.** The native `better-sqlite3` dependency only ships
+> prebuilt binaries for Node 22+ — on Node 20 (notably Windows, which has no
+> C/C++ toolchain by default) the install falls back to compiling from source
+> and fails. Use Node 22 or newer.
+
+## You probably want `@peekdev/cli` instead
+
+```sh
+npm install -g @peekdev/cli
+peek init
+```
+
+Read on if you're configuring the MCP server manually, building tooling against it, or want the protocol/tool reference.
+
+## What this is NOT
+
+- Not a remote MCP server. Peek is **local-only**: stdio transport over a child-process pipe. There is no HTTP listener, no SSE endpoint, no remote auth. The MCP transport spec's Streamable HTTP variant is out of scope by design.
+- Not a write-by-default tool. Read tools are unauthenticated. The write tools (`execute_action`, `request_authorization`) are gated by the per-origin permission model (off by default) + the destructive blocklist + the audit-log writer. The cross-process IPC that delivers them to the browser native host (`LocalSocketHostBridge` ↔ `HostSocketServer` over `~/.peek/host.sock`) is now wired: at **Level 3** every action prompts the side-panel confirm banner before it runs. The real-browser MAIN-world dispatch + banner UX are covered by the Playwright E2E (`e2e/smoke.spec.ts`); the bridge, relay, dispatcher, and confirm logic are unit-tested.
+- Not a wrapper around Chrome DevTools Protocol. The server reads recorded events from SQLite; the extension owns capture. No live `chrome.debugger` access from the MCP server.
+
+## Manual MCP-client config
+
+If `peek init` doesn't recognize your client, paste this into your client's MCP server registry:
+
+```json
+{
+  "mcpServers": {
+    "peek": {
+      "command": "npx",
+      "args": ["-y", "@peekdev/mcp@latest"]
+    }
+  }
+}
+```
+
+The `@latest` tag is required while peek is in alpha: every published version is a
+prerelease (`0.1.0-alpha.*`), and a bare `npx -y @peekdev/mcp` resolves the
+implicit `*` range, which doesn't match prereleases (`ETARGET: No matching
+version found for @peekdev/mcp@*`). Pinning `@latest` forces the newest published
+build.
+
+`PEEK_HOME` defaults to `~/.peek`; set it via `env` only if you want a non-default capture directory.
+
+The per-user config paths `peek init` writes to (canonical, see `packages/peek-cli/src/lib/init-config.ts`):
+
+| Client | Path |
+|---|---|
+| Claude Code | `~/.claude.json` (or `claude mcp add`) |
+| Cursor | `~/.cursor/mcp.json` |
+| VS Code (MCP) | `~/.vscode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline | `~/cline_mcp_settings.json` |
+
+## What the AI agent can do
+
+| Tool | Action | Authorization |
+|---|---|---|
+| `list_recent_sessions` | List recently recorded sessions, newest first (id, origin, ts, event count) | none |
+| `get_session_summary` | LLM-readable narrative summary of a session | none |
+| `get_session_console_errors` | List console errors recorded in a session | none |
+| `get_session_network_errors` | List failed/notable network requests in a session | none |
+| `get_user_action_before_error` | Last N user actions before a console error | none |
+| `generate_playwright_repro` | Generate a runnable Playwright test from a session | none |
+| `get_dom_snapshot` | Reconstruct the DOM at a given timestamp | none |
+| `query_dom_history` | Timeline of attribute/text changes for a selector | none |
+| `request_authorization` | Side-panel consent for write actions (Level 3) | per-action user prompt |
+| `execute_action` | Dispatch a UI action (gated by permission level + destructive blocklist) | permission level + destructive blocklist |
+
+The full tool list is exposed via the MCP `tools/list` request (spec 2025-11-25 + back-compat for 2025-03-26). Tool docs ship with the binary via `tools/list` response `description` fields.
+
+## Permission model (the five levels)
+
+Per-origin, 5 levels (0–4). Default is **Level 1 — Read-only**. Higher levels are opt-in per origin.
+
+| Level | Name | What it allows | Default |
+|---|---|---|---|
+| 0 | Off | Recording suppressed, tool surface disabled for the origin | |
+| 1 | Read-only | Read recorded sessions; no action execution | enabled |
+| 2 | Suggest-only | Read + highlight DOM via overlay; no DOM mutation | |
+| 3 | Act-with-confirm | Read + execute actions, each prompting Allow once / Always for this site / Deny | |
+| 4 | YOLO this session | Read + execute non-destructive actions with no prompt (auto-expires on tab close or 60 min) | |
+
+At **Level 3** every `execute_action` call prompts the user via the side-panel banner (unless a one-shot `confirmToken` from a prior `request_authorization` is passed). At **Level 4 (YOLO)** non-destructive actions are auto-allowed with no prompt. Levels 0–2 deny `execute_action`.
+
+**Destructive-action blocklist (cross-level override)** — independent of the level, any action whose resolved target text/label matches a destructive term (`delete`, `remove`, `transfer`, `send`, `pay`, `withdraw`, etc. — full base list in `permissions/destructive.ts`, extensible via `~/.peek/policy.json`) **always** prompts for confirmation. This overrides all levels, including Level 4 YOLO — it is not a separate "Level 5".
+
+Every `execute_action` and `request_authorization` call is appended to `~/.peek/audit.log` (JSONL, mode 0600 — `peek audit log --json` prints it), including denied ones.
+
+**The write-path is wired end to end:** the five-level model, the destructive blocklist, and the audit-log writer are enforced inside `peek-mcp` (observable via `~/.peek/audit.log`), and the cross-process IPC that lets `execute_action` fire a click in the browser now lands — a `LocalSocketHostBridge` (MCP process) ↔ `HostSocketServer` (native host) over `~/.peek/host.sock`, a MAIN-world action dispatcher (click/type/navigate/scroll), and a side-panel confirm banner. Both write levels are implemented: **Level 3** (act-with-confirm — every action prompts the banner) and **Level 4** (YOLO — non-destructive actions auto-allow, destructive ones still prompt via the blocklist override). Both are opt-in per origin; the default stays Level 1 (read-only). Level 2 highlight and the remaining action types are queued. The real-browser dispatch + banner are covered by the Playwright E2E (`e2e/smoke.spec.ts`).
+
+## Database
+
+`~/.peek/sessions.db` — SQLite (better-sqlite3, WAL mode). Schema in `src/db/migrations/`. The CLI opens this DB read-mostly; the native host writes it during extension capture; the MCP server reads it for tool calls.
+
+The native host is the **only writer**. The CLI and MCP server only read (except for the audit log, which is append-only JSONL on disk, not in the DB).
+
+## Subpath exports
+
+For consumers building tooling on top of peek:
+
+```ts
+import { generatePlaywrightRepro } from '@peekdev/mcp/mcp/playwright-repro';
+import { loadSessionEvents } from '@peekdev/mcp/mcp/event-blobs';
+import { openDb, peekHomeDir } from '@peekdev/mcp/db';
+import { buildManifest, installManifests } from '@peekdev/mcp/native-host';
+```
+
+These are the subpath exports the `@peekdev/cli` package uses. API surface is small but stable.
+
+## Versioning & compatibility
+
+Semantic Versioning. Currently `0.1.0-alpha.x` — pre-release; tool schemas are stable in spirit but new tools may land in patch releases. See [SUPPORTED.md](https://github.com/Cubenest/rrweb-stack/blob/main/SUPPORTED.md) for the compatibility matrix (MCP protocol versions, Chrome stable channels, Node versions).
+
+## Privacy
+
+Local-only. No network destinations. No telemetry. The MCP transport is stdio over a child-process pipe — your AI client launches `peek-mcp`, talks to it over stdin/stdout, and kills it when done. The binary holds no persistent state outside `~/.peek/`.
+
+Full data-handling policy: [`docs/peek/PRIVACY_POLICY.md`](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/PRIVACY_POLICY.md). Threat model: [`docs/peek/THREATMODEL.md`](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/THREATMODEL.md).
+
+## Distribution (maintainer-facing)
+
+> This section is for the maintainer's submission workflow at Phase 5 launch.
+> If you're a user, you don't need any of this — just `npx @peekdev/cli init`.
+
+peek is listed (or queued for listing) on the discovery surfaces below.
+Each linked file is a **submission scaffold** with pre-filled metadata
+audited against the registry's current schema as of 2026-05-30 — not a
+user-facing install guide.
+
+- [Official MCP Registry submission](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/distribution/modelcontextprotocol-servers.md) — `server.json` for `registry.modelcontextprotocol.io` via `mcp-publisher` CLI. Downstream registries (PulseMCP, others) ingest from here.
+- [PulseMCP submission](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/distribution/pulsemcp.json) — URL-only form + auto-ingest from the MCP Registry.
+- [Smithery submission](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/distribution/smithery.json) — MCPB bundle uploaded via `smithery mcp publish`.
+- [mcp.so submission](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/distribution/mcp-so.md) — web-form submission with the source content paste-ready.
+- [Claude Code skill standalone install](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/distribution/claude-code-skill.md) — curl recipe for users who want the Claude Code skill without running `peek init`.
+
+Launch order is documented in [`docs/peek/distribution/README.md`](https://github.com/Cubenest/rrweb-stack/blob/main/docs/peek/distribution/README.md) (CWS first, then the MCP-registry fan-out).
+
+## License
+
+Apache 2.0. The bundled rrweb engine remains MIT-licensed; see `NOTICE`.
+
+Contributions are accepted under the [Developer Certificate of Origin (DCO)](https://developercertificate.org/) — sign your commits with `git commit -s`. See [CONTRIBUTING.md](https://github.com/Cubenest/rrweb-stack/blob/main/CONTRIBUTING.md) + [SECURITY.md](https://github.com/Cubenest/rrweb-stack/blob/main/SECURITY.md).

package/dist/db/open.d.ts

@@ -1,5 +1,23 @@
-import Database from 'better-sqlite3';
+import type Database from 'better-sqlite3';
 import { schemaVersion } from './migrate.js';
+/** Constructor signature of better-sqlite3's default export (value-erased import above). */
+type BetterSqlite3Ctor = new (filename?: string, options?: Database.Options) => Database.Database;
+/**
+ * Lazily load better-sqlite3's native constructor, wrapping a native-module
+ * load failure in an actionable error.
+ *
+ * WHY (P-Windows): the import was previously `import Database from
+ * 'better-sqlite3'` at top-level module scope, so the `.node` binding loaded at
+ * module-EVALUATION time. A missing / ABI-mismatched (Node < 22) / AV-locked
+ * prebuilt binary therefore threw before `main()` ran — and on stock Windows
+ * there is no compile-from-source fallback — so the native host process simply
+ * died and the browser saw a silently-closed stdio pipe with no message. Making
+ * this a type-only import + a lazy `require` defers the load to the first
+ * {@link openDb} call (inside `main()`, where it is caught) and lets us emit a
+ * message the user can act on. Node's own require cache makes repeat calls cheap,
+ * so no module-level memo is needed. `requireFn` is injectable for tests.
+ */
+export declare function loadBetterSqlite3(requireFn?: (id: string) => unknown): BetterSqlite3Ctor;
 /**
  * The native host's data directory (ADR-0007). Defaults to `~/.peek`; the
  * `PEEK_HOME` environment variable overrides it (used by tests and by users who

package/dist/db/open.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../src/db/open.ts"],"names":[],"mappings":"AAOA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAiB,aAAa,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAED,iDAAiD;AACjD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,QAAQ,CAAC,QAAQ,CA0BrE;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAwB,GAAG,gBAAgB,CAQ/E;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../src/db/open.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAiB,aAAa,EAAE,MAAM,cAAc,CAAC;AAE5D,4FAA4F;AAC5F,KAAK,iBAAiB,GAAG,KAAK,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,QAAQ,CAAC;AAElG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAwC,GAClE,iBAAiB,CASnB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAED,iDAAiD;AACjD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,QAAQ,CAAC,QAAQ,CA2BrE;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAwB,GAAG,gBAAgB,CAQ/E;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/db/open.js

@@ -2,10 +2,33 @@
 // same ~/.peek/sessions.db through here so the pragmas (WAL, foreign keys) and
 // the migration state stay consistent across the three thin clients (ADR-0007).
 import { existsSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import Database from 'better-sqlite3';
 import { runMigrations, schemaVersion } from './migrate.js';
+/**
+ * Lazily load better-sqlite3's native constructor, wrapping a native-module
+ * load failure in an actionable error.
+ *
+ * WHY (P-Windows): the import was previously `import Database from
+ * 'better-sqlite3'` at top-level module scope, so the `.node` binding loaded at
+ * module-EVALUATION time. A missing / ABI-mismatched (Node < 22) / AV-locked
+ * prebuilt binary therefore threw before `main()` ran — and on stock Windows
+ * there is no compile-from-source fallback — so the native host process simply
+ * died and the browser saw a silently-closed stdio pipe with no message. Making
+ * this a type-only import + a lazy `require` defers the load to the first
+ * {@link openDb} call (inside `main()`, where it is caught) and lets us emit a
+ * message the user can act on. Node's own require cache makes repeat calls cheap,
+ * so no module-level memo is needed. `requireFn` is injectable for tests.
+ */
+export function loadBetterSqlite3(requireFn = createRequire(import.meta.url)) {
+    try {
+        return requireFn('better-sqlite3');
+    }
+    catch (err) {
+        throw new Error(`peek: the better-sqlite3 native module failed to load, so the session database cannot be opened. peek requires Node.js 22+ and a prebuilt binary for your platform (${process.platform}/${process.arch}); this usually means the prebuild is missing/incompatible (e.g. Node < 22) or an antivirus has locked the .node file. Original error: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
 /**
  * The native host's data directory (ADR-0007). Defaults to `~/.peek`; the
  * `PEEK_HOME` environment variable overrides it (used by tests and by users who
@@ -37,6 +60,7 @@ export function openDb(options = {}) {
     if (path !== ':memory:' && !readonly) {
         mkdirSync(dirname(path), { recursive: true });
     }
+    const Database = loadBetterSqlite3();
     const db = new Database(path, readonly ? { readonly: true } : {});
     if (readonly) {
         // Read-only handles can't enable WAL (a DDL/pragma write); the writer (the

package/dist/db/open.js.map

@@ -1 +1 @@
-{"version":3,"file":"open.js","sourceRoot":"","sources":["../../src/db/open.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAEhF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;IACvC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACrD,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,CAAC,CAAC;AAC5C,CAAC;AAoBD;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,UAAyB,EAAE;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,aAAa,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC3C,0EAA0E;IAC1E,6EAA6E;IAC7E,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC,QAAQ,EAAE,CAAC;QACrC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClE,IAAI,QAAQ,EAAE,CAAC;QACb,2EAA2E;QAC3E,wEAAwE;QACxE,6CAA6C;IAC/C,CAAC;SAAM,CAAC;QACN,2EAA2E;QAC3E,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QAChC,uEAAuE;QACvE,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzC,aAAa,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAWD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,aAAa,EAAE;IAC3D,yEAAyE;IACzE,2EAA2E;IAC3E,4BAA4B;IAC5B,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAChE,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../src/db/open.ts"],"names":[],"mappings":"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"}

package/dist/entrypoint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * True when `metaUrl` (`import.meta.url`) refers to the same file as `argv1`
+ * (`process.argv[1]`). Compares via {@link pathToFileURL} (Windows-safe, encoded)
+ * and falls back to the realpath-resolved argv (bin shims / symlinks). A
+ * realpath failure resolves to `false`. `realpath` is injectable for tests.
+ */
+export declare function isDirectInvocation(metaUrl: string, argv1: string | undefined, realpath?: (p: string) => string): boolean;
+//# sourceMappingURL=entrypoint.d.ts.map

package/dist/entrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.d.ts","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAqB,GAC7C,OAAO,CAQT"}

package/dist/entrypoint.js

@@ -0,0 +1,33 @@
+// Decide whether this module is the process entry point (`node thisfile`, or an
+// npm-generated bin shim) versus merely imported. Bin / postinstall entries
+// guard their side effect on this so an ESM `import` (tests, consumers) is inert.
+//
+// WHY pathToFileURL (P-Windows): comparing `import.meta.url` against the
+// string-concatenated `` `file://${process.argv[1]}` `` produced an INVALID url
+// on Windows — `process.argv[1]` is a backslash path (`C:\…\x.js`), so the
+// concat yields `file://C:\…\x.js`, which never equals `import.meta.url`'s
+// RFC-8089 form (`file:///C:/…/x.js`). It also skipped percent-encoding for
+// space/unicode paths on POSIX. pathToFileURL produces the correct encoded
+// `file:` url on every platform. (Local copy of @peekdev/cli's helper — kept
+// per-package so neither bin's entry guard depends on the other's public API.)
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+/**
+ * True when `metaUrl` (`import.meta.url`) refers to the same file as `argv1`
+ * (`process.argv[1]`). Compares via {@link pathToFileURL} (Windows-safe, encoded)
+ * and falls back to the realpath-resolved argv (bin shims / symlinks). A
+ * realpath failure resolves to `false`. `realpath` is injectable for tests.
+ */
+export function isDirectInvocation(metaUrl, argv1, realpath = realpathSync) {
+    if (argv1 === undefined)
+        return false;
+    if (metaUrl === pathToFileURL(argv1).href)
+        return true;
+    try {
+        return metaUrl === pathToFileURL(realpath(argv1)).href;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=entrypoint.js.map

package/dist/entrypoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.js","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,kFAAkF;AAClF,EAAE;AACF,yEAAyE;AACzE,gFAAgF;AAChF,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAE/E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,KAAyB,EACzB,WAAkC,YAAY;IAE9C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,OAAO,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,CAAC;QACH,OAAO,OAAO,KAAK,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/mcp/action-schema.d.ts

@@ -117,6 +117,93 @@ export declare const WaitForActionSchema: z.ZodObject<{
     timeoutMs?: number | undefined;
 }>;
 export type WaitForAction = z.infer<typeof WaitForActionSchema>;
+/** Press Enter on the active element or a specific selector (focus → keydown/keypress/keyup). */
+export declare const EnterActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"enter">;
+    selector: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "enter";
+    selector?: string | undefined;
+}, {
+    type: "enter";
+    selector?: string | undefined;
+}>;
+export type EnterAction = z.infer<typeof EnterActionSchema>;
+/** Double-click a target element. */
+export declare const DblClickActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dblclick">;
+    selector: z.ZodString;
+    nth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "dblclick";
+    selector: string;
+    nth?: number | undefined;
+}, {
+    type: "dblclick";
+    selector: string;
+    nth?: number | undefined;
+}>;
+export type DblClickAction = z.infer<typeof DblClickActionSchema>;
+/** Agent-set banner string (Part 2). Rides execute_action rails; no DOM target. */
+export declare const SetIntentActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"set_intent">;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "set_intent";
+    text: string;
+}, {
+    type: "set_intent";
+    text: string;
+}>;
+export type SetIntentAction = z.infer<typeof SetIntentActionSchema>;
+/** Draw a non-destructive highlight overlay on a target, with an optional label. */
+export declare const HighlightActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"highlight">;
+    selector: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "highlight";
+    selector: string;
+    label?: string | undefined;
+}, {
+    type: "highlight";
+    selector: string;
+    label?: string | undefined;
+}>;
+export type HighlightAction = z.infer<typeof HighlightActionSchema>;
+/** Remove the active highlight overlay — no DOM target. */
+export declare const ClearHighlightActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"clear_highlight">;
+}, "strip", z.ZodTypeAny, {
+    type: "clear_highlight";
+}, {
+    type: "clear_highlight";
+}>;
+export type ClearHighlightAction = z.infer<typeof ClearHighlightActionSchema>;
+/** Plan B — input handoff. Rides the execute_action rails (wire tool='execute_action'). */
+export declare const RequestUserInputActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"request_user_input">;
+    prompt: z.ZodString;
+    selector: z.ZodOptional<z.ZodString>;
+    scope: z.ZodDefault<z.ZodEnum<["field", "page"]>>;
+    readBack: z.ZodDefault<z.ZodBoolean>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "request_user_input";
+    timeoutMs: number;
+    prompt: string;
+    scope: "field" | "page";
+    readBack: boolean;
+    selector?: string | undefined;
+}, {
+    type: "request_user_input";
+    prompt: string;
+    selector?: string | undefined;
+    timeoutMs?: number | undefined;
+    scope?: "field" | "page" | undefined;
+    readBack?: boolean | undefined;
+}>;
+export type RequestUserInputAction = z.infer<typeof RequestUserInputActionSchema>;
 /** The full Action discriminated union (P2 PRD §E.4). */
 export declare const ActionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"click">;
@@ -211,6 +298,75 @@ export declare const ActionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     type: "waitFor";
     selector?: string | undefined;
     timeoutMs?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"enter">;
+    selector: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "enter";
+    selector?: string | undefined;
+}, {
+    type: "enter";
+    selector?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"dblclick">;
+    selector: z.ZodString;
+    nth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "dblclick";
+    selector: string;
+    nth?: number | undefined;
+}, {
+    type: "dblclick";
+    selector: string;
+    nth?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"highlight">;
+    selector: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "highlight";
+    selector: string;
+    label?: string | undefined;
+}, {
+    type: "highlight";
+    selector: string;
+    label?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"clear_highlight">;
+}, "strip", z.ZodTypeAny, {
+    type: "clear_highlight";
+}, {
+    type: "clear_highlight";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"set_intent">;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "set_intent";
+    text: string;
+}, {
+    type: "set_intent";
+    text: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"request_user_input">;
+    prompt: z.ZodString;
+    selector: z.ZodOptional<z.ZodString>;
+    scope: z.ZodDefault<z.ZodEnum<["field", "page"]>>;
+    readBack: z.ZodDefault<z.ZodBoolean>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "request_user_input";
+    timeoutMs: number;
+    prompt: string;
+    scope: "field" | "page";
+    readBack: boolean;
+    selector?: string | undefined;
+}, {
+    type: "request_user_input";
+    prompt: string;
+    selector?: string | undefined;
+    timeoutMs?: number | undefined;
+    scope?: "field" | "page" | undefined;
+    readBack?: boolean | undefined;
 }>]>;
 export type Action = z.infer<typeof ActionSchema>;
 /**

package/dist/mcp/action-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-schema.d.ts","sourceRoot":"","sources":["../../src/mcp/action-schema.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qEAAqE;AACrE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAK5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,qCAAqC;AACrC,eAAO,MAAM,oBAAoB;;;;;;;;;EAG/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,gEAAgE;AAChE,eAAO,MAAM,gBAAgB;;;;;;EAAwC,CAAC;AACtE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;EAA2C,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;EAA0C,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,kFAAkF;AAClF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;EAK7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB;;;;;;;;;EAGjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,yDAAyD;AACzD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAUvB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqB3D"}
+{"version":3,"file":"action-schema.d.ts","sourceRoot":"","sources":["../../src/mcp/action-schema.ts"],"names":[],"mappings":"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"}

package/dist/mcp/action-schema.js

@@ -53,6 +53,49 @@ export const WaitForActionSchema = z.object({
     selector: z.string().optional(),
     timeoutMs: z.number().int().min(0).default(5000),
 });
+/** Press Enter on the active element or a specific selector (focus → keydown/keypress/keyup). */
+export const EnterActionSchema = z.object({
+    type: z.literal('enter'),
+    selector: z.string().optional(),
+});
+/** Double-click a target element. */
+export const DblClickActionSchema = z.object({
+    type: z.literal('dblclick'),
+    selector: z.string().min(1),
+    nth: z.number().int().min(0).optional(),
+});
+/** Agent-set banner string (Part 2). Rides execute_action rails; no DOM target. */
+export const SetIntentActionSchema = z.object({
+    type: z.literal('set_intent'),
+    text: z.string().max(80),
+});
+/** Draw a non-destructive highlight overlay on a target, with an optional label. */
+export const HighlightActionSchema = z.object({
+    type: z.literal('highlight'),
+    selector: z.string().min(1),
+    label: z.string().max(120).optional(),
+});
+/** Remove the active highlight overlay — no DOM target. */
+export const ClearHighlightActionSchema = z.object({
+    type: z.literal('clear_highlight'),
+});
+/** Plan B — input handoff. Rides the execute_action rails (wire tool='execute_action'). */
+export const RequestUserInputActionSchema = z.object({
+    type: z.literal('request_user_input'),
+    prompt: z.string().max(280),
+    selector: z.string().optional(),
+    scope: z.enum(['field', 'page']).default('field'),
+    readBack: z.boolean().default(false),
+    // This ceiling (10 min) is DOUBLE the bridge's DEFAULT_BRIDGE_TIMEOUT_MS
+    // (5 min, host-bridge.ts). server.ts's dispatchActTool now threads
+    // timeoutMs = handoffTimeout + 30000 into bridge.request, so the bridge waits
+    // with margin above the handoff timer instead of cutting the request off at
+    // its 5-min default. The SW controller's timer (clamped to
+    // MAX_HANDOFF_TIMEOUT_MS = 240000, action-handler.ts) fires FIRST, so a slow
+    // human yields a structured { resumed:false, reason:'timeout' } rather than a
+    // transport error.
+    timeoutMs: z.number().int().min(0).max(600000).default(120000),
+});
 /** The full Action discriminated union (P2 PRD §E.4). */
 export const ActionSchema = z.discriminatedUnion('type', [
     ClickActionSchema,
@@ -64,6 +107,12 @@ export const ActionSchema = z.discriminatedUnion('type', [
     ScrollActionSchema,
     ScreenshotActionSchema,
     WaitForActionSchema,
+    EnterActionSchema,
+    DblClickActionSchema,
+    HighlightActionSchema,
+    ClearHighlightActionSchema,
+    SetIntentActionSchema,
+    RequestUserInputActionSchema,
 ]);
 /**
  * Mask the action's sensitive fields for audit-log persistence. `type`
@@ -90,6 +139,26 @@ export function redactActionForAudit(action) {
                 return action;
             }
         }
+        case 'request_user_input':
+            // Record what the AI asked: prompt + selector + scope. `scope` is non-
+            // secret and audit-relevant — it distinguishes a page-scope FULL takeover
+            // (broader surface) from a field/free-text card in the trail. NEVER the
+            // returned value — it lives in the result `details`, which the audit writer
+            // never receives (audit.ts buildAuditEntry takes only the action).
+            //
+            // This intentionally returns a PARTIAL object (drops readBack/timeoutMs),
+            // which is why the `as Action` cast is needed — the result is audit-only
+            // (consumed solely by buildAuditEntry -> JSON.stringify) and is NOT a
+            // dispatchable Action. Do not feed it back into the dispatcher.
+            return {
+                type: 'request_user_input',
+                prompt: action.prompt,
+                selector: action.selector,
+                scope: action.scope,
+            };
+        case 'set_intent':
+            // AI-authored status string (not secret); clipped defensively (schema also caps 80).
+            return { type: 'set_intent', text: action.text.slice(0, 80) };
         default:
             return action;
     }

package/dist/mcp/action-schema.js.map

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

package/dist/mcp/event-blobs.d.ts

@@ -17,13 +17,23 @@ export declare function rrwebEventsDir(): string;
  * Resolve a `sessions.events_blob_path` value to an absolute path. The column
  * stores a path relative to {@link rrwebEventsDir}; an absolute value (older
  * rows / tests) is honored as-is.
+ *
+ * Pre-alpha.10 rows store the path as `rrweb-events/<sessionId>` (a duplicated
+ * prefix relative to {@link peekHomeDir} instead of {@link rrwebEventsDir}).
+ * Strip that one specific leading segment so the legacy and current layouts
+ * resolve to the same on-disk directory.
  */
 export declare function resolveBlobPath(blobPath: string, baseDir?: string): string;
 /**
  * Read + gunzip + JSON-parse a session's event blob into the rrweb event array.
  * Returns an empty array when the session has no blob path recorded or the
- * blob file is missing (e.g. an active session before its first flush, or a
- * blob pruned by retention) — callers degrade to "no events" rather than throw.
+ * blob file/dir is missing (e.g. an active session before its first flush, or
+ * a blob pruned by retention) — callers degrade to "no events" rather than throw.
+ *
+ * The native host writes one gzipped chunk per `session.append` batch at
+ * `<events-dir>/<sessionId>/<seq>.json.gz`, and stores `<events-dir>/<sessionId>`
+ * (a directory) in `sessions.events_blob_path`. Older rows / tests may instead
+ * point at a single `.gz` file — both layouts are honored here.
  *
  * @param blobPath the `sessions.events_blob_path` value (relative or absolute)
  * @param baseDir  override the ~/.peek/rrweb-events base (tests)

package/dist/mcp/event-blobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-blobs.d.ts","sourceRoot":"","sources":["../../src/mcp/event-blobs.ts"],"names":[],"mappings":"AAUA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGtE;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,GAAG,MAAM,CAE5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,GAAE,MAAyB,GACjC,aAAa,EAAE,CAoBjB"}
+{"version":3,"file":"event-blobs.d.ts","sourceRoot":"","sources":["../../src/mcp/event-blobs.ts"],"names":[],"mappings":"AAUA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGtE;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,GAAG,MAAM,CAO5F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,GAAE,MAAyB,GACjC,aAAa,EAAE,CAajB"}