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

package/dist/mcp/playwright-repro.js

@@ -1,11 +1,15 @@
 // generate_playwright_repro (Task 3.13): turn a window of extracted user
 // actions into a runnable Playwright test string. Each action maps to the
 // idiomatic Playwright call:
-//   navigate -> await page.goto('url')
-//   click    -> await page.click('selector')
-//   input    -> await page.fill('selector', 'value')
+//   navigate          -> await page.goto('url')
+//   click             -> await page.click('selector')
+//   input (select)    -> await page.selectOption('selector', 'value')
+//   input (checkbox/radio) -> await page.check/uncheck('selector')
+//   input (other)     -> await page.fill('selector', 'value')
 // The first navigation seeds the opening goto; subsequent navigations are
 // emitted inline (e.g. an in-app route change that triggered a full load).
+// After the actions, a final `await expect(page).toHaveURL(...)` is emitted
+// for the last navigation so the repro verifies the end state, not just replays.
 import { extractUserActions } from './event-walker.js';
 /** Default ceiling on emitted actions — caps the output size (PRD §B token budget). */
 const DEFAULT_MAX_ACTIONS = 200;
@@ -26,10 +30,43 @@ function actionToStatement(action) {
             return action.url ? `  await page.goto(${jsString(action.url)});` : undefined;
         case 'click':
             return action.selector ? `  await page.click(${jsString(action.selector)});` : undefined;
-        case 'input':
-            return action.selector
-                ? `  await page.fill(${jsString(action.selector)}, ${jsString(action.value ?? '')});`
-                : undefined;
+        case 'input': {
+            if (!action.selector)
+                return undefined;
+            const sel = jsString(action.selector);
+            if (action.elementTag === 'input') {
+                if (action.inputType === 'checkbox' || action.inputType === 'radio') {
+                    if (action.checked === true)
+                        return `  await page.check(${sel});`;
+                    if (action.checked === false)
+                        return `  await page.uncheck(${sel});`;
+                    return `  // TODO: <input type="${action.inputType}"> ${action.selector} — checked state unknown; add check()/uncheck()`;
+                }
+                if (action.inputType === 'hidden' ||
+                    action.inputType === 'submit' ||
+                    action.inputType === 'button' ||
+                    action.inputType === 'reset' ||
+                    action.inputType === 'image') {
+                    return `  // TODO: skipped <input type="${action.inputType}"> (not a user text entry)`;
+                }
+                if (action.inputType === 'file') {
+                    return `  // TODO: file input ${action.selector} — setInputFiles can't be reconstructed from a recording`;
+                }
+            }
+            if (action.elementTag === 'select') {
+                // rrweb captures only a single text value per input event, so only
+                // single-value <select> interactions are representable here. A
+                // <select multiple> repro would be incorrect (only one option captured);
+                // no multi-select detection is attempted — this is a known v1 limitation.
+                const value = action.value ?? '';
+                // I1: an empty value would make Playwright throw at runtime
+                // ("did not find some options"). Emit a TODO so the script stays runnable.
+                if (value === '')
+                    return '  // TODO: <select> reset to placeholder — selectOption needs a value or { index: 0 }';
+                return `  await page.selectOption(${jsString(action.selector)}, ${jsString(value)});`;
+            }
+            return `  await page.fill(${jsString(action.selector)}, ${jsString(action.value ?? '')});`;
+        }
         default:
             return undefined;
     }
@@ -69,10 +106,22 @@ export function generatePlaywrightRepro(events, options = {}) {
             lines.push(`  // TODO: ${action.summary} (target selector unresolved)`);
         }
     }
+    // T0.5: assert the end state. Find the last navigate (with a url) in the
+    // capped window and verify the page landed there — turning a blind replay
+    // into a test with a real oracle for the final URL.
+    for (let i = actions.length - 1; i >= 0; i -= 1) {
+        const a = actions[i];
+        if (a && a.type === 'navigate' && a.url) {
+            lines.push(`  await expect(page).toHaveURL(${jsString(a.url)});`);
+            break;
+        }
+    }
     lines.push('});');
     lines.push('');
     return lines.join('\n');
 }
-// `expect` is imported in the generated script for the author to add assertions;
-// we don't synthesize assertions in v1 (we have no oracle for "correct" state).
+// `expect` is used for the final-URL assertion above (the one oracle we can
+// derive from a recording). We don't synthesize other assertions — we have no
+// ground truth for "correct" intermediate state — so the author still adds
+// content/visibility checks as needed.
 //# sourceMappingURL=playwright-repro.js.map

package/dist/mcp/playwright-repro.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-repro.js","sourceRoot":"","sources":["../../src/mcp/playwright-repro.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,0EAA0E;AAC1E,6BAA6B;AAC7B,uCAAuC;AACvC,6CAA6C;AAC7C,qDAAqD;AACrD,0EAA0E;AAC1E,2EAA2E;AAG3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAcvD,uFAAuF;AACvF,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,kFAAkF;AAClF,SAAS,QAAQ,CAAC,KAAa;IAC7B,0EAA0E;IAC1E,4EAA4E;IAC5E,OAAO,IAAI,KAAK;SACb,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC;AAC9B,CAAC;AAED,8EAA8E;AAC9E,SAAS,iBAAiB,CAAC,MAAkB;IAC3C,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,UAAU;YACb,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,qBAAqB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAChF,KAAK,OAAO;YACV,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,sBAAsB,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3F,KAAK,OAAO;YACV,OAAO,MAAM,CAAC,QAAQ;gBACpB,CAAC,CAAC,qBAAqB,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI;gBACrF,CAAC,CAAC,SAAS,CAAC;QAChB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAuB,EACvB,UAAgC,EAAE;IAElC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,iBAAiB,CAAC;IAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,iBAAiB,CAAC;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,uBAAuB,CAAC;IACvD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAE7D,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,OAAO,IAAI,CAAC,CAAC,EAAE,IAAI,KAAK,CAAC,CAAC;IAC/F,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,GAAG,UAAU,CAAC;IAClD,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IAE7F,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;IAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,QAAQ,QAAQ,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAE7D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;IACnE,CAAC;SAAM,IAAI,SAAS,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CACR,gCAAgC,UAAU,OAAO,WAAW,CAAC,MAAM,8CAA8C,CAClH,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,OAAO,+BAA+B,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,iFAAiF;AACjF,gFAAgF"}
+{"version":3,"file":"playwright-repro.js","sourceRoot":"","sources":["../../src/mcp/playwright-repro.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.d.ts

@@ -46,5 +46,5 @@ export interface CreatePeekMcpServerOptions {
  */
 export declare function createPeekMcpServer(options?: CreatePeekMcpServerOptions): PeekMcpServer;
 /** The tool names this server registers, for smoke tests / docs. */
-export declare const PEEK_MCP_TOOLS: readonly ["list_recent_sessions", "get_session_summary", "get_session_console_errors", "get_session_network_errors", "get_user_action_before_error", "generate_playwright_repro", "get_dom_snapshot", "query_dom_history", "request_authorization", "execute_action"];
+export declare const PEEK_MCP_TOOLS: readonly ["list_recent_sessions", "get_session_summary", "get_session_console_errors", "get_session_network_errors", "get_user_action_before_error", "generate_playwright_repro", "get_dom_snapshot", "query_dom_history", "request_authorization", "execute_action", "suggest_element", "clear_highlight", "request_user_input", "set_intent"];
 //# sourceMappingURL=server.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAUpE,eAAO,MAAM,cAAc,QAAe,CAAC;AAU3C,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,kBAAkB,CAAC;AAUtE,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,YAAY,CAAC;AAGhE,eAAO,MAAM,WAAW,aAAa,CAAC;AACtC,eAAO,MAAM,mBAAmB,QAUqB,CAAC;AAsBtD,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,sCAAsC;IACtC,KAAK,IAAI,IAAI,CAAC;IACd,sFAAsF;IACtF,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3D,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,0BAA0B;IACzC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAqd3F;AAED,oEAAoE;AACpE,eAAO,MAAM,cAAc,uQAajB,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAUpE,eAAO,MAAM,cAAc,QAAe,CAAC;AAU3C,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,kBAAkB,CAAC;AAUtE,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,YAAY,CAAC;AAGhE,eAAO,MAAM,WAAW,aAAa,CAAC;AACtC,eAAO,MAAM,mBAAmB,QAUqB,CAAC;AAsBtD,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,sCAAsC;IACtC,KAAK,IAAI,IAAI,CAAC;IACd,sFAAsF;IACtF,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3D,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,0BAA0B;IACzC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAiwB3F;AAED,oEAAoE;AACpE,eAAO,MAAM,cAAc,iVAoBjB,CAAC"}

package/dist/mcp/server.js

@@ -125,19 +125,29 @@ export function createPeekMcpServer(options = {}) {
     function registerTools() {
         // 1. list_recent_sessions ------------------------------------------------
         server.registerTool('list_recent_sessions', {
-            description: "List the user's recently recorded browser sessions, newest first. " +
-                'Returns compact rows with ids to pass to the get_session_* tools.',
+            title: 'List recent browser sessions',
+            description: "List the user's recorded browser sessions, newest first — the entry point for the get_session_* and DOM tools. Returns compact JSON rows ({ sessionId, origin, url, title, startedAt, ... }); free-text fields are clipped (origin 100, url 300, title 200 chars). If the MCP client scoped roots to specific origins and no origin filter is given, results are restricted to the client's scoped origins. Start here to obtain a sessionId, then call get_session_summary.",
             inputSchema: {
-                limit: z.number().int().min(1).max(50).default(10),
-                origin: z.string().optional(),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(50)
+                    .default(10)
+                    .describe('Maximum sessions to return (1-50, newest first; default 10).'),
+                origin: z
+                    .string()
+                    .optional()
+                    .describe("Filter to one origin, e.g. 'https://app.example.com'. Omit to list across all recorded origins (subject to client roots scoping)."),
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ limit, origin }) => {
             const handle = getDb();
             if (!handle)
                 return textResult(NO_DB_MESSAGE);
             // Apply the roots soft-scope: if the client scoped to origins and the
-            // caller didn't ask for a specific one, restrict to the first scoped
-            // origin set by filtering post-query (origins are few).
+            // caller didn't ask for a specific one, restrict to the scoped origin
+            // set by filtering post-query against all allowedOrigins (origins are few).
             const rows = listRecentSessions(handle, {
                 limit,
                 ...(origin !== undefined ? { origin } : {}),
@@ -155,9 +165,12 @@ export function createPeekMcpServer(options = {}) {
         });
         // 2. get_session_summary -------------------------------------------------
         server.registerTool('get_session_summary', {
-            description: 'Get an LLM-readable narrative summary of one session: pages visited, ' +
-                'click/input counts, navigations, and error counts.',
-            inputSchema: { sessionId: z.string() },
+            title: 'Summarize a session',
+            description: 'Get an LLM-readable narrative summary of one session: pages visited, click/input/navigation counts, and error counts. Use this first for an overview before drilling into get_session_console_errors / get_session_network_errors. Returns a structured JSON summary.',
+            inputSchema: {
+                sessionId: z.string().describe('Session id from list_recent_sessions.'),
+            },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ sessionId }) => {
             const handle = getDb();
             if (!handle)
@@ -173,13 +186,24 @@ export function createPeekMcpServer(options = {}) {
         });
         // 3. get_session_console_errors -----------------------------------------
         server.registerTool('get_session_console_errors', {
-            description: 'List console error messages recorded in a session, oldest first. ' +
-                'Each row has an id usable with get_user_action_before_error.',
+            title: 'List console errors',
+            description: 'List console error messages recorded in a session, oldest first. Each row has a numeric id to pass to get_user_action_before_error. Returns JSON rows ({ id, ts, level, message, stack }); message clipped to 500 and stack to 800 chars. For error counts at a glance, use get_session_summary first.',
             inputSchema: {
-                sessionId: z.string(),
-                since: z.number().int().optional(),
-                limit: z.number().int().min(1).max(200).default(50),
+                sessionId: z.string().describe('Session id from list_recent_sessions.'),
+                since: z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('Only return errors with ts >= this epoch-ms timestamp (to page forward through a long session). Omit to start from the beginning.'),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(200)
+                    .default(50)
+                    .describe('Maximum errors to return (1-200, oldest first; default 50).'),
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ sessionId, since, limit }) => {
             const handle = getDb();
             if (!handle)
@@ -198,13 +222,26 @@ export function createPeekMcpServer(options = {}) {
         });
         // 4. get_session_network_errors -----------------------------------------
         server.registerTool('get_session_network_errors', {
-            description: 'List failed/notable network requests in a session (status >= statusGte ' +
-                'or a network error), oldest first.',
+            title: 'List failed network requests',
+            description: 'List failed or notable network requests in a session (HTTP status >= statusGte, or a transport-level network error), oldest first. Returns JSON rows ({ id, ts, method, url, status, statusText, resourceType, durationMs, errorText }); url and errorText clipped to 300 chars.',
             inputSchema: {
-                sessionId: z.string(),
-                statusGte: z.number().int().min(100).max(599).default(400),
-                limit: z.number().int().min(1).max(200).default(50),
+                sessionId: z.string().describe('Session id from list_recent_sessions.'),
+                statusGte: z
+                    .number()
+                    .int()
+                    .min(100)
+                    .max(599)
+                    .default(400)
+                    .describe('Minimum HTTP status treated as notable (100-599; default 400, i.e. 4xx/5xx). Transport-level errors are always included regardless.'),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(200)
+                    .default(50)
+                    .describe('Maximum requests to return (1-200, oldest first; default 50).'),
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ sessionId, statusGte, limit }) => {
             const handle = getDb();
             if (!handle)
@@ -224,14 +261,20 @@ export function createPeekMcpServer(options = {}) {
         });
         // 5. get_user_action_before_error ---------------------------------------
         server.registerTool('get_user_action_before_error', {
-            description: 'Show the last N user actions (click/type/navigate) before a console ' +
-                'error, to reconstruct what the user did. errorId comes from ' +
-                'get_session_console_errors.',
+            title: 'Actions before an error',
+            description: 'Reconstruct what the user did right before a console error: returns the last `window` user actions (click/type/navigate) preceding the error, to explain how it was triggered. Returns JSON { errorId, errorTs, actions }. Get errorId from get_session_console_errors first.',
             inputSchema: {
-                sessionId: z.string(),
-                errorId: z.number().int(),
-                window: z.number().int().min(1).max(50).default(10),
+                sessionId: z.string().describe('Session id from list_recent_sessions.'),
+                errorId: z.number().int().describe('Console error id from get_session_console_errors.'),
+                window: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(50)
+                    .default(10)
+                    .describe('How many preceding user actions to return (1-50; default 10).'),
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ sessionId, errorId, window }) => {
             const handle = getDb();
             if (!handle)
@@ -248,13 +291,22 @@ export function createPeekMcpServer(options = {}) {
         });
         // 6. generate_playwright_repro ------------------------------------------
         server.registerTool('generate_playwright_repro', {
-            description: 'Generate a runnable Playwright test from the user actions in a session ' +
-                '(optionally limited to a [startTs, endTs] window).',
+            title: 'Generate Playwright repro',
+            description: 'Generate a runnable Playwright test (TypeScript) reproducing the user actions in a session: clicks, typing, navigation, and <select> changes. Optionally limit to a [startTs, endTs] epoch-ms window. Returns the test source as text. Note: only single-value <select> is represented (rrweb captures one value per input).',
             inputSchema: {
-                sessionId: z.string(),
-                startTs: z.number().int().optional(),
-                endTs: z.number().int().optional(),
+                sessionId: z.string().describe('Session id from list_recent_sessions.'),
+                startTs: z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('Only include actions at or after this epoch-ms timestamp. Omit to start at the session beginning.'),
+                endTs: z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('Only include actions at or before this epoch-ms timestamp. Omit to run through the session end.'),
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ sessionId, startTs, endTs }) => {
             const handle = getDb();
             if (!handle)
@@ -274,14 +326,20 @@ export function createPeekMcpServer(options = {}) {
         });
         // 7. get_dom_snapshot ----------------------------------------------------
         server.registerTool('get_dom_snapshot', {
-            description: 'Reconstruct the DOM at a timestamp (or a selector subtree within it) ' +
-                'and return it as HTML. v1 applies structural/attribute/text mutations ' +
-                'on top of the nearest full snapshot.',
+            title: 'Reconstruct DOM at a time',
+            description: 'Reconstruct the page DOM as it existed at a timestamp (or a selector subtree within it) and return it as HTML. Applies structural/attribute/text mutations on top of the nearest full snapshot at or before ts. Returns JSON { baseSnapshotTs, mutationsApplied, html }; html clipped to 24000 chars. Fails if no full snapshot exists at or before ts.',
             inputSchema: {
-                sessionId: z.string(),
-                ts: z.number().int(),
-                selector: z.string().optional(),
+                sessionId: z.string().describe('Session id from list_recent_sessions.'),
+                ts: z
+                    .number()
+                    .int()
+                    .describe('Epoch-ms timestamp to reconstruct the DOM at. Use timestamps from get_session_summary, error rows, or get_user_action_before_error.'),
+                selector: z
+                    .string()
+                    .optional()
+                    .describe('CSS selector to return only that subtree. Omit to return the full document.'),
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ sessionId, ts, selector }) => {
             const handle = getDb();
             if (!handle)
@@ -302,14 +360,26 @@ export function createPeekMcpServer(options = {}) {
         });
         // 8. query_dom_history ---------------------------------------------------
         server.registerTool('query_dom_history', {
-            description: "Timeline of attribute and/or text changes for a selector's node over " +
-                'a session. op restricts to attributeChanges or innerText.',
+            title: 'DOM change timeline',
+            description: 'Timeline of attribute and/or text changes over a session for the node matching a CSS selector - useful for tracking how one element evolved. Returns JSON { selector, changes }. Use op to restrict to attribute changes or innerText; omit for both.',
             inputSchema: {
-                sessionId: z.string(),
-                selector: z.string(),
-                op: z.enum(['attributeChanges', 'innerText']).optional(),
-                limit: z.number().int().min(1).max(500).default(100),
+                sessionId: z.string().describe('Session id from list_recent_sessions.'),
+                selector: z
+                    .string()
+                    .describe("CSS selector for the node to track, e.g. '#status' or '.cart-count'."),
+                op: z
+                    .enum(['attributeChanges', 'innerText'])
+                    .optional()
+                    .describe("Restrict to 'attributeChanges' or 'innerText'. Omit to include both."),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(500)
+                    .default(100)
+                    .describe('Maximum changes to return (1-500; default 100).'),
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, ({ sessionId, selector, op, limit }) => {
             const handle = getDb();
             if (!handle)
@@ -329,13 +399,19 @@ export function createPeekMcpServer(options = {}) {
         // banner. On Allow the host returns a one-shot confirmToken the AI passes
         // to execute_action. EVERY call (including denied ones) is audit-logged.
         server.registerTool('request_authorization', {
-            description: 'Ask the user to authorize an action in their browser via the side-' +
-                'panel banner (Level 3 act-with-confirm). Returns a one-shot ' +
-                'confirmToken to pass to execute_action, or denies the request. ' +
-                'Every call is recorded to ~/.peek/audit.log.',
+            title: 'Request action authorization',
+            description: 'Ask the user to authorize a browser action via the side-panel banner (Level-3 act-with-confirm). On Allow, returns a one-shot confirmToken to pass to execute_action; on Deny, returns the denial. Every call - allowed or denied - is recorded to ~/.peek/audit.log. Use before execute_action when the origin is at permission Level 3, or to pre-authorize.',
             inputSchema: {
-                sessionId: z.string(),
-                action: ActionSchema,
+                sessionId: z
+                    .string()
+                    .describe('Session id (origin context) from list_recent_sessions; determines the per-origin permission level.'),
+                action: ActionSchema.describe('The browser action to authorize (e.g. click/type/navigate; see the action schema).'),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
             },
         }, async ({ sessionId, action }) => {
             return await dispatchActTool({
@@ -351,17 +427,23 @@ export function createPeekMcpServer(options = {}) {
         // banner step at Level 3. Without it: Level 3 raises a banner; Level 4
         // proceeds (unless destructive); Level <3 denies.
         server.registerTool('execute_action', {
-            description: "Execute an action in the user's browser. Requires per-origin " +
-                'permission Level 3+ (Level 3 prompts unless confirmToken is passed; ' +
-                'Level 4 auto-allows non-destructive). The destructive-action ' +
-                'override (delete/remove/transfer/send/pay/purchase/buy/confirm/' +
-                'subscribe/logout/sign out/unsubscribe/cancel subscription/wire/' +
-                'withdraw) always prompts, even at Level 4. Every call is ' +
-                'recorded to ~/.peek/audit.log.',
+            title: 'Execute a browser action',
+            description: "Execute an action (click/type/navigate/...) in the user's live browser. Requires per-origin permission Level 3+: Level 3 raises a confirm banner unless a valid confirmToken from request_authorization is passed; Level 4 auto-allows non-destructive actions; Level <3 denies. The destructive-action override (delete/remove/transfer/send/pay/purchase/buy/confirm/subscribe/logout/sign out/unsubscribe/cancel subscription/wire/withdraw) always prompts, even at Level 4. Every call is recorded to ~/.peek/audit.log.",
             inputSchema: {
-                sessionId: z.string(),
-                action: ActionSchema,
-                confirmToken: z.string().optional(),
+                sessionId: z
+                    .string()
+                    .describe('Session id (origin context) from list_recent_sessions; determines the per-origin permission level.'),
+                action: ActionSchema.describe('The browser action to execute (e.g. click/type/navigate; see the action schema).'),
+                confirmToken: z
+                    .string()
+                    .optional()
+                    .describe('One-shot token from a prior request_authorization Allow, to skip the Level-3 banner. Omit to trigger the banner (Level 3) or rely on Level-4 auto-allow.'),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: true,
             },
         }, async ({ sessionId, action, confirmToken }) => {
             return await dispatchActTool({
@@ -371,6 +453,150 @@ export function createPeekMcpServer(options = {}) {
                 ...(confirmToken !== undefined ? { confirmToken } : {}),
             });
         });
+        // 11. suggest_element (Level-2 Suggest tier) -----------------------------
+        // Non-mutating highlight overlay. Routed through the execute_action audit
+        // path (wire tool='execute_action'); the SW intercepts the `highlight`
+        // action BEFORE the act gate and auto-allows it at per-origin Level 2+.
+        server.registerTool('suggest_element', {
+            title: 'Highlight an element in the live browser',
+            description: "Draw a non-destructive highlight overlay on a CSS selector in the user's live browser, with an optional label, to point something out. Available at per-origin permission Level 2 (Suggest) and above; it never clicks, types, or navigates. The overlay persists until clear_highlight is called. Every call is recorded to ~/.peek/audit.log.",
+            inputSchema: {
+                sessionId: z
+                    .string()
+                    .describe('Session id (origin context) from list_recent_sessions; determines the per-origin permission level.'),
+                selector: z.string().min(1).describe('CSS selector of the element to highlight.'),
+                label: z
+                    .string()
+                    .max(120)
+                    .optional()
+                    .describe('Optional short text shown in a badge next to the highlight (<=120 chars).'),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async ({ sessionId, selector, label }) => {
+            return await dispatchActTool({
+                tool: 'execute_action',
+                sessionId,
+                action: { type: 'highlight', selector, ...(label !== undefined ? { label } : {}) },
+            });
+        });
+        // 12. clear_highlight (Level-2 Suggest tier) -----------------------------
+        server.registerTool('clear_highlight', {
+            title: 'Clear the highlight overlay',
+            description: "Remove the highlight overlay previously drawn by suggest_element in the user's live browser. Available at per-origin permission Level 2 (Suggest) and above. Idempotent. Recorded to ~/.peek/audit.log.",
+            inputSchema: {
+                sessionId: z
+                    .string()
+                    .describe('Session id (origin context) from list_recent_sessions; determines the per-origin permission level.'),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async ({ sessionId }) => {
+            return await dispatchActTool({
+                tool: 'execute_action',
+                sessionId,
+                action: { type: 'clear_highlight' },
+            });
+        });
+        // 13. set_intent (Part 2 — control-shield banner) ------------------------
+        // Set the agent's status banner shown on the Level-4 control shield so the
+        // user can follow what the agent is doing. Rides the execute_action audit
+        // path on the wire; auto-allowed at Level 4 with the shield up.
+        server.registerTool('set_intent', {
+            title: 'Set the control-shield banner text',
+            description: "Set the agent's status banner shown on the control shield (e.g. 'Applying to Senior Frontend · step 2/4'), so the user can follow what you're doing. Up to 80 chars, plain text. Requires the origin at Level 4 with the shield up; auto-allowed. Recorded to ~/.peek/audit.log.",
+            inputSchema: {
+                sessionId: z
+                    .string()
+                    .describe('Session id (origin context) from list_recent_sessions; determines the per-origin permission level.'),
+                text: z
+                    .string()
+                    .max(80)
+                    .describe('Status text shown in the shield banner (<=80 chars). Pass an empty string to clear it.'),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async ({ sessionId, text }) => {
+            return await dispatchActTool({
+                tool: 'execute_action',
+                sessionId,
+                action: { type: 'set_intent', text },
+            });
+        });
+        // 14. request_user_input (Plan B — input handoff) ------------------------
+        // Pause the agent + hand the keyboard back to the user for ONE editable,
+        // non-destructive field (or a free-text prompt), then resume. Rides the
+        // execute_action audit path on the wire; the SW gates it at per-origin
+        // Level 4 with the control shield up. The per-request bridge timeout is
+        // clamped to 30s ABOVE the handoff timeout so the SW controller's timer
+        // fires first → structured {resumed:false,'timeout'} (not a transport error).
+        server.registerTool('request_user_input', {
+            title: 'Pause and ask the user to fill something in on the page',
+            description: "Pause the agent and hand the keyboard back to the user for ONE editable, non-destructive field (or a free-text prompt), then resume. Requires the origin at Level 4 with the control shield up. Blocks until the user clicks Done, a timeout fires, or the run is stopped. Returns { resumed:true, value? } or { resumed:false, reason }. The returned value is only included when readBack:true and the field isn't a password/OTP/credit-card field. Recorded to ~/.peek/audit.log (prompt + selector only — never the value).",
+            inputSchema: {
+                sessionId: z
+                    .string()
+                    .describe('Session id (origin context) from list_recent_sessions; determines the per-origin permission level.'),
+                prompt: z
+                    .string()
+                    .max(280)
+                    .describe('What to ask the user to do (shown in the card, below a peek-authored framing line).'),
+                selector: z
+                    .string()
+                    .optional()
+                    .describe('CSS selector of the editable field to unlock for the user. Omit for a free-text prompt card.'),
+                readBack: z
+                    .boolean()
+                    .optional()
+                    .describe('If true, return what the user typed to the agent (never for password/OTP/cc fields). Default false.'),
+                timeoutMs: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(600000)
+                    .optional()
+                    .describe('How long to wait for the user (default 120000, max 600000).'),
+                scope: z
+                    .enum(['field', 'page'])
+                    .default('field')
+                    .describe("'field' (default) unlocks one editable field; 'page' hands full page control back (CAPTCHAs, native widgets, final review) until Resume. Inherits the handoff recording-suspension."),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        }, async ({ sessionId, prompt, selector, readBack, timeoutMs, scope }) => {
+            const handoffTimeout = Math.min(Math.max(timeoutMs ?? 120000, 0), 600000);
+            return await dispatchActTool({
+                tool: 'execute_action',
+                sessionId,
+                action: {
+                    type: 'request_user_input',
+                    prompt,
+                    ...(selector !== undefined ? { selector } : {}),
+                    scope,
+                    readBack: readBack ?? false,
+                    timeoutMs: handoffTimeout,
+                },
+                // The bridge waits 30s longer than the handoff so the SW controller's
+                // timer fires first → structured {resumed:false,'timeout'}.
+                timeoutMs: handoffTimeout + 30_000,
+            });
+        });
     }
     // --- Act-tool dispatch (shared between execute_action + request_authorization) ---
     async function dispatchActTool(input) {
@@ -387,6 +613,7 @@ export function createPeekMcpServer(options = {}) {
                 action: input.action,
                 client,
                 ...(input.confirmToken !== undefined ? { confirmToken: input.confirmToken } : {}),
+                ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
             });
         }
         catch (err) {
@@ -472,5 +699,12 @@ export const PEEK_MCP_TOOLS = [
     // Write tools (Phase 3d, Level 3+).
     'request_authorization',
     'execute_action',
+    // Suggest tools (Level 2+ — non-mutating highlight overlay).
+    'suggest_element',
+    'clear_highlight',
+    // Input handoff (Plan B — Level 4 with the control shield up).
+    'request_user_input',
+    // Control-shield banner (Part 2 — Level 4 auto-allowed).
+    'set_intent',
 ];
 //# sourceMappingURL=server.js.map