@peekdev/mcp 0.1.0-alpha.1

package/dist/mcp/event-walker.js

@@ -0,0 +1,398 @@
+// The shared rrweb stream walker — the heart of the event-level read tools.
+//
+// rrweb records a session as a FullSnapshot (the serialized DOM at capture
+// start) followed by IncrementalSnapshot events (mutations, mouse interactions,
+// input edits) and Meta events (navigations). To answer the MCP read tools we
+// decode that stream once and offer three views over it:
+//
+//   • user actions      — clicks / inputs / navigations with timestamps +
+//                          derived selectors (get_user_action_before_error,
+//                          generate_playwright_repro).
+//   • DOM at a timestamp — the FullSnapshot's serialized tree with structural +
+//                          attribute + text mutations applied up to T, rendered
+//                          to an HTML-ish string (get_dom_snapshot). v1 scope:
+//                          see reconstructDomAt's doc.
+//   • selector history   — the timeline of attribute / text changes for a node
+//                          matched by selector (query_dom_history).
+//
+// Everything works on the decoded `eventWithTime[]` with no live DOM, so it
+// runs in plain Node (no jsdom) — matching ADR-0011's "thin local client".
+import { EventType, IncrementalSource, MouseInteractions, NodeType, } from './rrweb-types.js';
+import { MAX_DOM_DEPTH, indexNodes, nodeChildren, selectorFor, } from './selector.js';
+function isFullSnapshot(e) {
+    return e.type === EventType.FullSnapshot;
+}
+function isIncremental(e) {
+    return e.type === EventType.IncrementalSnapshot;
+}
+function isMeta(e) {
+    return e.type === EventType.Meta;
+}
+/**
+ * Walk the stream and pull out user actions (clicks, input commits, page
+ * navigations) in chronological order. The selector for a click/input is
+ * derived from whichever FullSnapshot is in effect at that point (rebuilt as
+ * new FullSnapshots arrive), with added nodes folded into the index so
+ * interactions on dynamically-inserted elements still resolve.
+ *
+ * Mouse *moves*, scrolls, and non-Click interactions are intentionally dropped
+ * — they're noise for repro/explanation and blow the token budget.
+ */
+export function extractUserActions(events) {
+    const actions = [];
+    // The live node index, seeded by the latest FullSnapshot and grown by adds.
+    let index;
+    const resolveSelector = (id) => index ? selectorFor(index, id) : undefined;
+    for (const e of events) {
+        if (isFullSnapshot(e)) {
+            index = new Map(indexNodes(e.data.node));
+            continue;
+        }
+        if (isMeta(e)) {
+            const href = e.data.href;
+            if (typeof href === 'string' && href.length > 0) {
+                actions.push({ type: 'navigate', ts: e.timestamp, url: href, summary: `navigate ${href}` });
+            }
+            continue;
+        }
+        if (!isIncremental(e))
+            continue;
+        const data = e.data;
+        if (data.source === IncrementalSource.Mutation) {
+            // Keep the index current so interactions on inserted nodes resolve.
+            foldAddsIntoIndex(index, data.adds);
+            continue;
+        }
+        if (data.source === IncrementalSource.MouseInteraction) {
+            const mi = data;
+            if (mi.type === MouseInteractions.Click || mi.type === MouseInteractions.DblClick) {
+                const selector = resolveSelector(mi.id);
+                actions.push({
+                    type: 'click',
+                    ts: e.timestamp,
+                    ...(selector !== undefined ? { selector } : {}),
+                    summary: selector !== undefined ? `click ${selector}` : `click node#${mi.id}`,
+                });
+            }
+            continue;
+        }
+        if (data.source === IncrementalSource.Input) {
+            const input = data;
+            const selector = resolveSelector(input.id);
+            // rrweb already masks values per the recorder config; we surface as-is.
+            const value = typeof input.text === 'string' ? input.text : '';
+            actions.push({
+                type: 'input',
+                ts: e.timestamp,
+                ...(selector !== undefined ? { selector } : {}),
+                value,
+                summary: selector !== undefined
+                    ? `input ${selector} = ${truncate(value, 40)}`
+                    : `input node#${input.id} = ${truncate(value, 40)}`,
+            });
+        }
+    }
+    return actions;
+}
+/** Fold a mutation's added nodes into the live index (best-effort, recursive). */
+function foldAddsIntoIndex(index, adds) {
+    if (!index || !adds)
+        return;
+    for (const add of adds) {
+        const register = (node, parentId, depth) => {
+            index.set(node.id, { node, parentId });
+            if (depth >= MAX_DOM_DEPTH)
+                return;
+            for (const child of nodeChildren(node))
+                register(child, node.id, depth + 1);
+        };
+        register(add.node, add.parentId, 0);
+    }
+}
+/** The user actions strictly before `errorTs`, most-recent-last, capped to `window`. */
+export function userActionsBeforeError(events, errorTs, window = 10) {
+    const all = extractUserActions(events).filter((a) => a.ts <= errorTs);
+    return all.slice(Math.max(0, all.length - window));
+}
+export function reconstructDomAt(events, ts, selector) {
+    // Find the base FullSnapshot (latest at or before ts).
+    let baseIdx = -1;
+    for (let i = 0; i < events.length; i += 1) {
+        const e = events[i];
+        if (e && isFullSnapshot(e) && e.timestamp <= ts)
+            baseIdx = i;
+    }
+    if (baseIdx < 0)
+        return undefined;
+    const baseEvent = events[baseIdx];
+    // Deep clone so we can mutate without touching the caller's events. Use a
+    // depth-bounded clone (not structuredClone, which recurses and overflows the
+    // stack on an adversarial deeply-nested tree before any of our guards run).
+    const root = cloneNodeBounded(baseEvent.data.node, 0);
+    const byId = new Map();
+    const parentOf = new Map();
+    (function indexMutable(node, parentId, depth) {
+        byId.set(node.id, node);
+        if (parentId !== null)
+            parentOf.set(node.id, parentId);
+        if (depth >= MAX_DOM_DEPTH)
+            return;
+        for (const child of nodeChildren(node))
+            indexMutable(child, node.id, depth + 1);
+    })(root, null, 0);
+    let mutationsApplied = 0;
+    for (let i = baseIdx + 1; i < events.length; i += 1) {
+        const e = events[i];
+        if (!e || e.timestamp > ts)
+            break;
+        if (!isIncremental(e))
+            continue;
+        const data = e.data;
+        if (data.source !== IncrementalSource.Mutation)
+            continue;
+        applyMutation(data, byId, parentOf);
+        mutationsApplied += 1;
+    }
+    // Optionally scope to the first node matching `selector`.
+    let renderRoot = root;
+    if (selector !== undefined) {
+        const match = findBySelector(root, byId, selector);
+        if (match)
+            renderRoot = match;
+    }
+    return {
+        baseSnapshotTs: baseEvent.timestamp,
+        mutationsApplied,
+        root: renderRoot,
+        html: serializeNode(renderRoot),
+    };
+}
+/**
+ * Depth-bounded deep clone of a serialized node. Stops cloning children past
+ * {@link MAX_DOM_DEPTH} (the truncated node keeps its own scalar fields but
+ * loses descendants), so it never overflows the stack on an adversarial
+ * deeply-nested subtree — unlike `structuredClone`, which recurses internally.
+ * Attribute objects are shallow-copied (flat string maps, never nested).
+ */
+function cloneNodeBounded(node, depth) {
+    const src = node;
+    const clone = { ...src };
+    if (src.attributes)
+        clone.attributes = { ...src.attributes };
+    const children = nodeChildren(node);
+    if (children.length > 0) {
+        clone.childNodes =
+            depth >= MAX_DOM_DEPTH ? [] : children.map((c) => cloneNodeBounded(c, depth + 1));
+    }
+    return clone;
+}
+/** Apply a single mutation event to the in-memory serialized tree. */
+function applyMutation(m, byId, parentOf) {
+    // Removes first (rrweb applies removes, then adds, then attrs/texts).
+    for (const r of m.removes ?? []) {
+        const parent = byId.get(r.parentId);
+        if (parent && Array.isArray(parent.childNodes)) {
+            parent.childNodes = parent.childNodes.filter((c) => c.id !== r.id);
+        }
+        byId.delete(r.id);
+        parentOf.delete(r.id);
+    }
+    for (const a of m.adds ?? []) {
+        const parent = byId.get(a.parentId);
+        if (!parent)
+            continue;
+        if (!Array.isArray(parent.childNodes))
+            parent.childNodes = [];
+        const clone = cloneNodeBounded(a.node, 0);
+        // Insert before `nextId` when present, else append.
+        if (a.nextId !== null && a.nextId !== undefined) {
+            const at = parent.childNodes.findIndex((c) => c.id === a.nextId);
+            if (at >= 0)
+                parent.childNodes.splice(at, 0, clone);
+            else
+                parent.childNodes.push(clone);
+        }
+        else {
+            parent.childNodes.push(clone);
+        }
+        // Register the added subtree (depth-bounded against adversarial nesting).
+        (function register(node, parentId, depth) {
+            byId.set(node.id, node);
+            parentOf.set(node.id, parentId);
+            if (depth >= MAX_DOM_DEPTH)
+                return;
+            for (const child of nodeChildren(node))
+                register(child, node.id, depth + 1);
+        })(clone, parent.id, 0);
+    }
+    for (const at of m.attributes ?? []) {
+        const node = byId.get(at.id);
+        if (!node)
+            continue;
+        if (!node.attributes)
+            node.attributes = {};
+        for (const [key, value] of Object.entries(at.attributes)) {
+            if (value === null)
+                delete node.attributes[key];
+            else
+                node.attributes[key] = value;
+        }
+    }
+    for (const t of m.texts ?? []) {
+        const node = byId.get(t.id);
+        if (node)
+            node.textContent = t.value ?? '';
+    }
+}
+/** Find the first node matching `selector` by re-deriving selectors from the tree. */
+function findBySelector(root, byId, selector) {
+    // Rebuild a NodeIndex over the (mutated) tree and compare derived selectors.
+    const index = indexNodes(root);
+    for (const [id, node] of byId) {
+        const derived = selectorFor(index, id);
+        if (derived === selector)
+            return node;
+    }
+    // Fallback: match the trailing segment (e.g. "#submit") loosely.
+    const tail = selector.split('>').pop()?.trim();
+    if (tail) {
+        for (const [id, node] of byId) {
+            const derived = selectorFor(index, id);
+            if (derived?.endsWith(tail))
+                return node;
+        }
+    }
+    return undefined;
+}
+/**
+ * Render a serialized node tree to an HTML-ish string (lightweight, not
+ * spec-perfect). Stops descending past {@link MAX_DOM_DEPTH} — emitting a
+ * truncation marker instead of recursing — so an adversarial deeply-nested
+ * recording can't overflow the stack (this code ingests untrusted blobs).
+ */
+export function serializeNode(node, depth = 0) {
+    const n = node;
+    switch (node.type) {
+        case NodeType.Document: {
+            if (depth >= MAX_DOM_DEPTH)
+                return '<!-- [truncated: max depth] -->';
+            return nodeChildren(node)
+                .map((c) => serializeNode(c, depth + 1))
+                .join('');
+        }
+        case NodeType.DocumentType: {
+            const dt = node;
+            return `<!DOCTYPE ${dt.name}>`;
+        }
+        case NodeType.Text: {
+            return n.textContent ?? '';
+        }
+        case NodeType.CDATA:
+            return '';
+        case NodeType.Comment:
+            return `<!--${n.textContent ?? ''}-->`;
+        case NodeType.Element: {
+            const el = node;
+            const tag = el.tagName.toLowerCase();
+            const attrs = renderAttributes(n.attributes ?? {});
+            if (VOID_ELEMENTS.has(tag))
+                return `<${tag}${attrs}>`;
+            if (depth >= MAX_DOM_DEPTH) {
+                return `<${tag}${attrs}><!-- [truncated: max depth] --></${tag}>`;
+            }
+            const children = nodeChildren(node)
+                .map((c) => serializeNode(c, depth + 1))
+                .join('');
+            return `<${tag}${attrs}>${children}</${tag}>`;
+        }
+        default:
+            return '';
+    }
+}
+const VOID_ELEMENTS = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+]);
+function renderAttributes(attrs) {
+    const parts = [];
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === false || value === null || value === undefined)
+            continue;
+        if (value === true) {
+            parts.push(` ${key}`);
+            continue;
+        }
+        const str = String(value).replace(/"/g, '&quot;');
+        parts.push(` ${key}="${str}"`);
+    }
+    return parts.join('');
+}
+export function queryDomHistory(events, selector, options = {}) {
+    const limit = options.limit ?? 100;
+    // Resolve the target id from the first FullSnapshot.
+    const fullSnapshot = events.find(isFullSnapshot);
+    if (!fullSnapshot)
+        return [];
+    const index = indexNodes(fullSnapshot.data.node);
+    let targetId;
+    for (const [id] of index) {
+        if (selectorFor(index, id) === selector) {
+            targetId = id;
+            break;
+        }
+    }
+    if (targetId === undefined)
+        return [];
+    const wantAttr = options.op !== 'innerText';
+    const wantText = options.op !== 'attributeChanges';
+    const changes = [];
+    for (const e of events) {
+        if (!isIncremental(e))
+            continue;
+        const data = e.data;
+        if (data.source !== IncrementalSource.Mutation)
+            continue;
+        const m = data;
+        if (wantAttr) {
+            for (const at of m.attributes ?? []) {
+                if (at.id !== targetId)
+                    continue;
+                for (const [key, value] of Object.entries(at.attributes)) {
+                    changes.push({
+                        ts: e.timestamp,
+                        op: 'attribute',
+                        attribute: key,
+                        value: value === null ? null : String(value),
+                    });
+                }
+            }
+        }
+        if (wantText) {
+            for (const t of m.texts ?? []) {
+                // Text mutations target the text node; also surface direct text-child
+                // edits whose parent is the target (common for innerText changes).
+                const parentId = index.get(t.id)?.parentId;
+                if (t.id === targetId || parentId === targetId) {
+                    changes.push({ ts: e.timestamp, op: 'text', value: t.value ?? null });
+                }
+            }
+        }
+    }
+    return changes.slice(0, limit);
+}
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+//# sourceMappingURL=event-walker.js.map

package/dist/mcp/event-walker.js.map

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

package/dist/mcp/host-bridge.d.ts

@@ -0,0 +1,80 @@
+import { RequestRegistry, type RequestRegistryDeps } from '../native-host/request-registry.js';
+import type { Action } from './action-schema.js';
+/** Input the MCP tool handler hands the bridge. */
+export interface HostActionRequest {
+    /** 'execute_action' | 'request_authorization' — picks audit shape + UX. */
+    readonly tool: 'execute_action' | 'request_authorization';
+    readonly sessionId: string;
+    readonly action: Action;
+    /** MCP client name (from clientInfo). */
+    readonly client: string;
+    /**
+     * Time the bridge waits before failing the await (5min default — longer
+     * than any plausible Level-3 banner decision). Defaults applied at the
+     * call site, not here, so different tools can use different budgets.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * A pre-existing confirmation token from a prior `request_authorization`
+     * call. Only meaningful for `tool === 'execute_action'`: the host can use
+     * it to skip the banner step. NULL/undefined → no token (auth still happens).
+     */
+    readonly confirmToken?: string;
+}
+/** Reply the bridge yields to the MCP tool handler. */
+export interface HostActionResponse {
+    /** verdict + result from the SW (see action-protocol.ts ActionResultMessage). */
+    readonly verdict: 'allow' | 'deny';
+    readonly result: 'ok' | 'denied' | 'error';
+    readonly approver: 'user' | 'allow-list-match' | 'level-4-auto';
+    readonly approvalMs?: number;
+    readonly destructiveTerm?: string;
+    readonly details?: unknown;
+    readonly error?: string;
+    /**
+     * For `request_authorization`: a one-shot token the AI then passes to
+     * `execute_action`. Opaque; the host validates.
+     */
+    readonly confirmToken?: string;
+}
+/**
+ * The bridge contract. The MCP tool handler awaits this; an implementation
+ * relays the request to the SW + waits for the verdict.
+ */
+export interface HostBridge {
+    request(req: HostActionRequest): Promise<HostActionResponse>;
+}
+/**
+ * Default placeholder used when the IPC layer hasn't been wired in this
+ * process (e.g. an MCP server started without a co-running native host).
+ *
+ * Every act-tool call resolves with `denied` + a clear error message so the
+ * AI sees a structured failure rather than the tool throwing. The audit log
+ * still records the attempt at the tool-handler layer.
+ */
+export declare class MissingHostBridge implements HostBridge {
+    #private;
+    constructor(reason?: string);
+    request(_req: HostActionRequest): Promise<HostActionResponse>;
+}
+/**
+ * A bridge backed by a {@link RequestRegistry}. The MCP tool handler's call
+ * registers a pending request; tests (or a future IPC implementation) call
+ * `resolveRequest` / `rejectRequest` to drive the reply. Used directly in
+ * `server.test.ts` to exercise the act-tool handlers without real IPC.
+ */
+export declare class RegistryBackedHostBridge implements HostBridge {
+    #private;
+    /** FIFO queue of {id, req} pairs awaiting resolution — exposed for tests. */
+    readonly pending: Array<{
+        id: string;
+        req: HostActionRequest;
+    }>;
+    constructor(registry?: RequestRegistry, deps?: RequestRegistryDeps);
+    request(req: HostActionRequest): Promise<HostActionResponse>;
+    /** Test helper: resolve the first pending request. */
+    resolveNext(payload: HostActionResponse): boolean;
+    /** Test helper: reject the first pending request. */
+    rejectNext(reason: unknown): boolean;
+}
+//# sourceMappingURL=host-bridge.d.ts.map

package/dist/mcp/host-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-bridge.d.ts","sourceRoot":"","sources":["../../src/mcp/host-bridge.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAKjD,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,cAAc,CAAC;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC9D;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,UAAU;;gBAEtC,MAAM,SAAqD;IAGjE,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAQpE;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,UAAU;;IAEzD,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAM;gBAEzD,QAAQ,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,mBAAmB;IAI5D,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQlE,sDAAsD;IACtD,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO;IAMjD,qDAAqD;IACrD,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CAKrC"}

package/dist/mcp/host-bridge.js

@@ -0,0 +1,88 @@
+// MCP-process ↔ native-host-process bridge (Task 3.24).
+//
+// Architecture note (and an HONEST design boundary):
+//
+//   • The `peek-mcp` binary serves TWO roles via argv dispatch (see
+//     src/index.ts): the **native host** process (owns ~/.peek/sessions.db
+//     and the chrome.runtime.connectNative port), and the **MCP server**
+//     process (an AI client like Cursor spawns it over stdio).
+//   • For act-tool execution, the MCP server has to TELL the native host
+//     "ask the SW to do X". Two processes — they need IPC.
+//   • The two processes share ~/.peek/. The simplest cross-platform IPC for
+//     a local-only design is a Unix domain socket on macOS/Linux (`~/.peek/
+//     host.sock`) and a named pipe on Windows. That bridge lives outside
+//     this chunk's scope — it's part of the action-execution E2E that the
+//     brief explicitly marks as E2E-deferred.
+//
+//   This module defines:
+//     1. The `HostBridge` interface every layer above calls — the seam
+//        action-tool handlers depend on. PURE: in/out promises.
+//     2. A {@link MissingHostBridge} default that throws a clear "bridge not
+//        wired in this process" error. Used until the IPC implementation
+//        lands; lets the MCP server CONSTRUCT cleanly + lets tests inject
+//        a fake.
+//     3. A {@link RegistryBackedHostBridge} test/integration helper that
+//        wraps a {@link RequestRegistry} so tests can simulate the host
+//        side without real IPC.
+//
+//   When the IPC layer lands (3d-4 or 3e) we add a concrete
+//   `LocalSocketHostBridge` here; nothing else changes.
+import { RequestRegistry } from '../native-host/request-registry.js';
+// 5 minutes — longer than any plausible Level-3 banner-decision window.
+const DEFAULT_BRIDGE_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Default placeholder used when the IPC layer hasn't been wired in this
+ * process (e.g. an MCP server started without a co-running native host).
+ *
+ * Every act-tool call resolves with `denied` + a clear error message so the
+ * AI sees a structured failure rather than the tool throwing. The audit log
+ * still records the attempt at the tool-handler layer.
+ */
+export class MissingHostBridge {
+    #reason;
+    constructor(reason = 'native-host bridge not wired in this MCP process') {
+        this.#reason = reason;
+    }
+    async request(_req) {
+        return {
+            verdict: 'deny',
+            result: 'denied',
+            approver: 'user',
+            error: this.#reason,
+        };
+    }
+}
+/**
+ * A bridge backed by a {@link RequestRegistry}. The MCP tool handler's call
+ * registers a pending request; tests (or a future IPC implementation) call
+ * `resolveRequest` / `rejectRequest` to drive the reply. Used directly in
+ * `server.test.ts` to exercise the act-tool handlers without real IPC.
+ */
+export class RegistryBackedHostBridge {
+    #registry;
+    /** FIFO queue of {id, req} pairs awaiting resolution — exposed for tests. */
+    pending = [];
+    constructor(registry, deps) {
+        this.#registry = registry ?? new RequestRegistry(deps);
+    }
+    async request(req) {
+        const { id, response } = this.#registry.create(req.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS);
+        this.pending.push({ id, req });
+        return response;
+    }
+    /** Test helper: resolve the first pending request. */
+    resolveNext(payload) {
+        const entry = this.pending.shift();
+        if (!entry)
+            return false;
+        return this.#registry.resolve(entry.id, payload);
+    }
+    /** Test helper: reject the first pending request. */
+    rejectNext(reason) {
+        const entry = this.pending.shift();
+        if (!entry)
+            return false;
+        return this.#registry.reject(entry.id, reason);
+    }
+}
+//# sourceMappingURL=host-bridge.js.map

package/dist/mcp/host-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-bridge.js","sourceRoot":"","sources":["../../src/mcp/host-bridge.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,qDAAqD;AACrD,EAAE;AACF,oEAAoE;AACpE,2EAA2E;AAC3E,yEAAyE;AACzE,+DAA+D;AAC/D,yEAAyE;AACzE,2DAA2D;AAC3D,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,8CAA8C;AAC9C,EAAE;AACF,yBAAyB;AACzB,uEAAuE;AACvE,gEAAgE;AAChE,6EAA6E;AAC7E,yEAAyE;AACzE,0EAA0E;AAC1E,iBAAiB;AACjB,yEAAyE;AACzE,wEAAwE;AACxE,gCAAgC;AAChC,EAAE;AACF,4DAA4D;AAC5D,wDAAwD;AAExD,OAAO,EAAE,eAAe,EAA4B,MAAM,oCAAoC,CAAC;AAG/F,wEAAwE;AACxE,MAAM,yBAAyB,GAAG,CAAC,GAAG,MAAM,CAAC;AAiD7C;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IACnB,OAAO,CAAS;IACzB,YAAY,MAAM,GAAG,kDAAkD;QACrE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,IAAuB;QACnC,OAAO;YACL,OAAO,EAAE,MAAM;YACf,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,IAAI,CAAC,OAAO;SACpB,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,wBAAwB;IAC1B,SAAS,CAAkB;IACpC,6EAA6E;IACpE,OAAO,GAAkD,EAAE,CAAC;IAErE,YAAY,QAA0B,EAAE,IAA0B;QAChE,IAAI,CAAC,SAAS,GAAG,QAAQ,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAsB;QAClC,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAC5C,GAAG,CAAC,SAAS,IAAI,yBAAyB,CAC3C,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,sDAAsD;IACtD,WAAW,CAAC,OAA2B;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,qDAAqD;IACrD,UAAU,CAAC,MAAe;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;CACF"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,8 @@
+import { type CreatePeekMcpServerOptions } from './server.js';
+/**
+ * Start the peek MCP stdio server and resolve when the transport closes (the
+ * client disconnected — stdin EOF). The DB handle is released on close.
+ */
+export declare function runMcpServer(options?: CreatePeekMcpServerOptions): Promise<void>;
+export { createPeekMcpServer, PEEK_MCP_TOOLS, SERVER_NAME, type CreatePeekMcpServerOptions, type PeekMcpServer, } from './server.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,0BAA0B,EAAuB,MAAM,aAAa,CAAC;AAEnF;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB1F;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,32 @@
+// MCP-mode entry (Task 3.11, ADR-0011): construct the peek MCP server and
+// connect it over a single StdioServerTransport — the only transport peek
+// exposes in v1. Invoked from src/index.ts when `peek-mcp` runs without
+// --native-host and without a chrome-extension:// origin arg.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createPeekMcpServer } from './server.js';
+/**
+ * Start the peek MCP stdio server and resolve when the transport closes (the
+ * client disconnected — stdin EOF). The DB handle is released on close.
+ */
+export async function runMcpServer(options = {}) {
+    const peek = createPeekMcpServer(options);
+    const transport = new StdioServerTransport();
+    // Resolve when the client disconnects (stdin EOF). McpServer.connect
+    // (Protocol.connect) PRESERVES and chains a pre-existing transport.onclose:
+    // it captures the current handler and invokes it before its own internal
+    // teardown. So we set it ONCE here, before connect — setting it again after
+    // connect would clobber the SDK's chained cleanup. The read-only DB handle is
+    // released in the same callback.
+    const closed = new Promise((resolve) => {
+        transport.onclose = () => {
+            peek.close();
+            resolve();
+        };
+    });
+    await peek.server.connect(transport);
+    // `connect` returns once the transport is started; the process stays alive on
+    // the open stdio streams until the client closes them. Block for that.
+    await closed;
+}
+export { createPeekMcpServer, PEEK_MCP_TOOLS, SERVER_NAME, } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,8DAA8D;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAmC,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEnF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAsC,EAAE;IACzE,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,qEAAqE;IACrE,4EAA4E;IAC5E,yEAAyE;IACzE,4EAA4E;IAC5E,8EAA8E;IAC9E,iCAAiC;IACjC,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC3C,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE;YACvB,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAErC,8EAA8E;IAC9E,uEAAuE;IACvE,MAAM,MAAM,CAAC;AACf,CAAC;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,WAAW,GAGZ,MAAM,aAAa,CAAC"}