craftdriver 1.7.0 → 1.8.0

package/dist/cli/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,4DAA4D;IAC5D,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC9F,iFAAiF;IACjF,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAUD,eAAO,MAAM,KAAK,EAAE,OAAO,EAqP1B,CAAC;AAIF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEzD;AAED,6EAA6E;AAC7E,wBAAsB,OAAO,CAC3B,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CAGlB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,YAAY,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,eAAe,CAAC;IAC7B,gDAAgD;IAChD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CAC/F;AAoCD,eAAO,MAAM,KAAK,EAAE,OAAO,EA4a1B,CAAC;AAIF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEzD;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtF;AAED,gFAAgF;AAChF,wBAAsB,OAAO,CAC3B,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAE9B"}

package/dist/cli/mcp/tools.js

@@ -1,94 +1,201 @@
-import { dispatch } from '../dispatcher.js';
-const STRING_SELECTOR = {
+import { toInputSchema, validateArgs } from './params.js';
+const SELECTOR = {
     type: 'string',
+    required: true,
     description: "CSS by default. Switch kind with a prefix: 'role=button[name=Submit]', " +
         "'text=Sign In', 'text*=Sign', 'label=Email', 'placeholder=...', " +
-        "'testid=...', 'xpath=...', 'id=...', 'name=...'.",
+        "'testid=...', 'xpath=...', 'id=...', 'name=...', or 'ref=eN' from a snapshot.",
 };
+const OPTIONAL_SELECTOR = { ...SELECTOR, required: false };
+const TIMEOUT = { type: 'number', min: 0, max: 300_000, description: 'Milliseconds.' };
+/** A page action that changes what the user sees. */
+function mutating(title, openWorld = true) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: openWorld,
+    };
+}
+/** An inspection that changes nothing. */
+function readOnly(title, openWorld = true) {
+    return {
+        title,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: openWorld,
+    };
+}
 export const TOOLS = [
+    // ---- navigation and core actions ---------------------------------------
     {
         name: 'browser_navigate',
         description: 'Navigate the active page to a URL. Waits for load.',
-        inputSchema: {
-            type: 'object',
-            properties: { url: { type: 'string' } },
-            required: ['url'],
-        },
-        mutating: true,
+        params: { url: { type: 'string', required: true, maxLength: 2048 } },
+        annotations: mutating('Navigate'),
         toDispatch: (a) => ({ cmd: 'go', args: { url: a.url } }),
     },
     {
         name: 'browser_click',
         description: 'Click an element. Auto-waits for visible+enabled. Returns NO_MATCH immediately ' +
-            'when the selector matches zero elements at t=0.',
-        inputSchema: {
-            type: 'object',
-            properties: { selector: STRING_SELECTOR, timeout_ms: { type: 'number' } },
-            required: ['selector'],
+            'when the selector matches zero elements at t=0. Set double for a double-click.',
+        params: {
+            selector: SELECTOR,
+            double: { type: 'boolean', description: 'Double-click instead of single.' },
+            timeout_ms: TIMEOUT,
         },
-        mutating: true,
-        toDispatch: (a) => ({ cmd: 'click', args: { selector: a.selector, timeout: a.timeout_ms } }),
+        annotations: mutating('Click'),
+        toDispatch: (a) => ({
+            cmd: a.double === true ? 'dblclick' : 'click',
+            args: { selector: a.selector, timeout: a.timeout_ms },
+        }),
     },
     {
         name: 'browser_fill',
-        description: 'Fill an input/textarea/select. The library auto-clears before typing. ' +
-            'For checkboxes prefer browser_click with the matching label.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                selector: STRING_SELECTOR,
-                value: { type: 'string' },
-                timeout_ms: { type: 'number' },
-            },
-            required: ['selector', 'value'],
+        description: 'Fill an input/textarea. Clears first, then enters the value with real key events. ' +
+            'For checkboxes use browser_element with action=check.',
+        params: {
+            selector: SELECTOR,
+            value: { type: 'string', required: true },
+            timeout_ms: TIMEOUT,
         },
-        mutating: true,
+        annotations: mutating('Fill field'),
         toDispatch: (a) => ({
             cmd: 'fill',
             args: { selector: a.selector, value: a.value, timeout: a.timeout_ms },
         }),
     },
+    {
+        name: 'browser_type',
+        description: 'Type text into whatever currently holds focus. No selector — use browser_fill to ' +
+            'target a field, or browser_element with action=focus first to append.',
+        params: { text: { type: 'string', required: true } },
+        annotations: mutating('Type into focus'),
+        toDispatch: (a) => ({ cmd: 'type', args: { text: a.text } }),
+    },
+    {
+        name: 'browser_element',
+        description: 'Act on one element: dblclick, focus, scroll, clear, check, uncheck, or select. ' +
+            'check/uncheck are idempotent and read the state back. select matches an <option> ' +
+            'by its value attribute, not its label.',
+        params: {
+            action: {
+                type: 'string',
+                required: true,
+                enum: ['dblclick', 'focus', 'scroll', 'clear', 'check', 'uncheck', 'select'],
+            },
+            selector: SELECTOR,
+            value: { type: 'string', description: 'Option value; required for action=select.' },
+            timeout_ms: TIMEOUT,
+        },
+        annotations: mutating('Element action'),
+        toDispatch: (a) => ({
+            cmd: a.action,
+            args: {
+                selector: a.selector,
+                ...(a.value !== undefined ? { value: a.value } : {}),
+                timeout: a.timeout_ms,
+            },
+        }),
+    },
     {
         name: 'browser_press',
-        description: 'Press a keyboard key (e.g. "Enter", "Tab", "Control+A"). Optional selector ' +
-            'focuses an element first.',
-        inputSchema: {
-            type: 'object',
-            properties: { key: { type: 'string' }, selector: STRING_SELECTOR },
-            required: ['key'],
-        },
-        mutating: true,
+        description: 'Press a key (e.g. "Enter", "Tab", "Control+A"). Optional selector focuses first.',
+        params: { key: { type: 'string', required: true, maxLength: 64 }, selector: OPTIONAL_SELECTOR },
+        annotations: mutating('Press key'),
         toDispatch: (a) => ({
             cmd: 'press',
             args: { key: a.key, ...(a.selector ? { selector: a.selector } : {}) },
         }),
     },
+    {
+        name: 'browser_key',
+        description: 'Low-level keyboard control: hold a key down, release it, or press it. Use for ' +
+            'modifier combinations that browser_press cannot express.',
+        params: {
+            action: { type: 'string', required: true, enum: ['press', 'down', 'up'] },
+            key: { type: 'string', required: true, maxLength: 64 },
+            selector: OPTIONAL_SELECTOR,
+        },
+        annotations: mutating('Keyboard'),
+        toDispatch: (a) => ({
+            cmd: 'key',
+            args: { action: a.action, key: a.key, ...(a.selector ? { selector: a.selector } : {}) },
+        }),
+    },
+    {
+        name: 'browser_mouse',
+        description: 'Move, click, press, release, or wheel the mouse, by element or by coordinate. ' +
+            'Use for drag, hover-reveal, and canvas interactions.',
+        params: {
+            action: { type: 'string', required: true, enum: ['move', 'click', 'down', 'up', 'wheel'] },
+            selector: OPTIONAL_SELECTOR,
+            x: { type: 'number' },
+            y: { type: 'number' },
+            button: { type: 'string', enum: ['left', 'middle', 'right'] },
+            delta_x: { type: 'number' },
+            delta_y: { type: 'number' },
+        },
+        annotations: mutating('Mouse'),
+        toDispatch: (a) => ({
+            cmd: 'mouse',
+            args: {
+                action: a.action,
+                ...(a.selector ? { selector: a.selector } : {}),
+                x: a.x,
+                y: a.y,
+                button: a.button,
+                deltaX: a.delta_x,
+                deltaY: a.delta_y,
+            },
+        }),
+    },
     {
         name: 'browser_hover',
         description: 'Hover over an element.',
-        inputSchema: {
-            type: 'object',
-            properties: { selector: STRING_SELECTOR, timeout_ms: { type: 'number' } },
-            required: ['selector'],
-        },
-        mutating: true,
+        params: { selector: SELECTOR, timeout_ms: TIMEOUT },
+        annotations: mutating('Hover'),
         toDispatch: (a) => ({ cmd: 'hover', args: { selector: a.selector, timeout: a.timeout_ms } }),
     },
+    {
+        name: 'browser_upload',
+        description: 'Set files on a file input. Paths must already exist and are never echoed back. ' +
+            'Bounded in count.',
+        params: {
+            selector: SELECTOR,
+            files: { type: 'string[]', required: true, maxItems: 10, maxLength: 4096 },
+        },
+        annotations: { ...mutating('Upload files'), openWorldHint: true },
+        toDispatch: (a) => ({ cmd: 'upload', args: { selector: a.selector, files: a.files } }),
+    },
+    {
+        name: 'browser_dialog',
+        description: 'Inspect, accept, or dismiss a native dialog (alert/confirm/prompt). An open dialog ' +
+            'blocks page script, so handle it before anything else.',
+        params: {
+            action: { type: 'string', required: true, enum: ['inspect', 'accept', 'dismiss'] },
+            text: { type: 'string', description: 'Prompt answer; used with accept.' },
+        },
+        annotations: mutating('Dialog'),
+        toDispatch: (a) => ({
+            cmd: 'dialog',
+            args: { action: a.action, ...(a.text !== undefined ? { text: a.text } : {}) },
+        }),
+    },
+    // ---- inspection ---------------------------------------------------------
     {
         name: 'browser_find',
-        description: 'Locate elements without acting on them. Returns up to `limit` matches with ' +
-            'tag, text snippet, and visibility. Use `all: true` to enumerate.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                selector: STRING_SELECTOR,
-                all: { type: 'boolean' },
-                limit: { type: 'number' },
-                offset: { type: 'number' },
-            },
-            required: ['selector'],
+        description: 'Locate elements without acting on them. Returns up to `limit` matches with tag, ' +
+            'text snippet, and visibility. Use `all` to enumerate.',
+        params: {
+            selector: SELECTOR,
+            all: { type: 'boolean' },
+            limit: { type: 'number', min: 1, max: 500, integer: true },
+            offset: { type: 'number', min: 0, integer: true },
         },
-        mutating: false,
+        annotations: readOnly('Find elements'),
         toDispatch: (a) => ({
             cmd: 'find',
             args: { selector: a.selector, all: a.all, limit: a.limit, offset: a.offset },
@@ -96,55 +203,27 @@ export const TOOLS = [
     },
     {
         name: 'browser_exists',
-        description: 'Zero-wait probe: returns { exists, count } immediately. Call this BEFORE ' +
-            'browser_click/wait when you are guessing a selector — it costs one BiDi ' +
-            "roundtrip instead of the full 5 s timeout.",
-        inputSchema: {
-            type: 'object',
-            properties: { selector: STRING_SELECTOR },
-            required: ['selector'],
-        },
-        mutating: false,
+        description: 'Zero-wait probe: returns { exists, count } immediately. Call this BEFORE clicking or ' +
+            'waiting when guessing a selector — one roundtrip instead of the full timeout.',
+        params: { selector: SELECTOR },
+        annotations: readOnly('Probe selector'),
         toDispatch: (a) => ({ cmd: 'exists', args: { selector: a.selector } }),
     },
-    {
-        name: 'browser_wait',
-        description: 'Wait for a condition: selector to become visible/hidden/attached/detached, ' +
-            'or a load state (load|domcontentloaded|networkidle).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                target: { type: 'string' },
-                kind: { type: 'string', enum: ['selector', 'load'] },
-                state: { type: 'string' },
-                timeout_ms: { type: 'number' },
-            },
-            required: ['target'],
-        },
-        mutating: false,
-        toDispatch: (a) => ({
-            cmd: 'wait',
-            args: { target: a.target, kind: a.kind ?? 'selector', state: a.state, timeout: a.timeout_ms },
-        }),
-    },
     {
         name: 'browser_read',
-        description: 'Read text/attr/value/is-state from an element, or page body text when no ' +
-            'selector is given. `kind` defaults to "text".',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                selector: STRING_SELECTOR,
-                kind: { type: 'string', enum: ['text', 'attr', 'value', 'is'] },
-                name: { type: 'string', description: 'attribute name when kind=attr' },
-                what: {
-                    type: 'string',
-                    enum: ['visible', 'enabled', 'checked'],
-                    description: 'state when kind=is',
-                },
+        description: 'Read text/attr/value/is-state from an element, or page body text when no selector ' +
+            'is given. `kind` defaults to "text".',
+        params: {
+            selector: OPTIONAL_SELECTOR,
+            kind: { type: 'string', enum: ['text', 'attr', 'value', 'is'] },
+            name: { type: 'string', description: 'Attribute name when kind=attr.' },
+            what: {
+                type: 'string',
+                enum: ['visible', 'enabled', 'checked'],
+                description: 'State when kind=is.',
             },
         },
-        mutating: false,
+        annotations: readOnly('Read element'),
         toDispatch: (a) => {
             const kind = a.kind ?? 'text';
             if (kind === 'attr')
@@ -157,88 +236,203 @@ export const TOOLS = [
         },
     },
     {
-        name: 'browser_pages',
-        description: 'List open pages with id/url/title. Use for tab/popup-aware flows.',
-        inputSchema: { type: 'object', properties: {} },
-        mutating: false,
-        toDispatch: () => ({ cmd: 'pages', args: {} }),
+        name: 'browser_wait',
+        description: 'Wait for a selector to become visible/hidden/attached/detached, or for a load state ' +
+            '(load|domcontentloaded|networkidle).',
+        params: {
+            target: { type: 'string', required: true },
+            kind: { type: 'string', enum: ['selector', 'load'] },
+            state: { type: 'string', maxLength: 32 },
+            timeout_ms: TIMEOUT,
+        },
+        annotations: readOnly('Wait for condition'),
+        toDispatch: (a) => ({
+            cmd: 'wait',
+            args: { target: a.target, kind: a.kind ?? 'selector', state: a.state, timeout: a.timeout_ms },
+        }),
     },
     {
         name: 'browser_snapshot',
-        description: 'Sanitized accessibility-tree summary of the active page: one line ' +
-            'per visible interactive element with role, accessible name, and a ' +
-            'stable ref (`e1`, `e2`, …). Use `ref=eN` as the selector for ' +
-            'subsequent tool calls — refs are auto-resolved without DOM hunting ' +
-            'and invalidate on the next snapshot or navigation. Cheaper and ' +
-            'more reliable than browser_screenshot for understanding the page.',
-        inputSchema: { type: 'object', properties: {} },
-        mutating: false,
+        description: 'Sanitized accessibility-tree summary of the active page: one line per visible ' +
+            'interactive element with role, accessible name, and a stable ref (e1, e2, …). Use ' +
+            '`ref=eN` as a selector for later calls. A ref binds to one element and fails ' +
+            'STALE_REF rather than drifting; it is exploration state and never belongs in a test.',
+        params: {},
+        annotations: readOnly('Page snapshot'),
         toDispatch: () => ({ cmd: 'snapshot', args: {} }),
     },
+    {
+        name: 'browser_locators',
+        description: 'Turn an element into durable selectors for a committed test, ordered by resilience ' +
+            '(role+name, label, test id, unique text, minimal CSS) and each re-checked against ' +
+            'the live page. Use this to convert a snapshot ref into something a test can keep. ' +
+            'No candidate ever contains a ref.',
+        params: {
+            selector: SELECTOR,
+            limit: { type: 'number', min: 1, max: 20, integer: true },
+        },
+        annotations: readOnly('Durable selectors'),
+        toDispatch: (a) => ({ cmd: 'locators', args: { selector: a.selector, limit: a.limit } }),
+    },
     {
         name: 'browser_screenshot',
-        description: 'Capture a PNG of the active page or a specific element. Always written ' +
-            'to disk under the per-session artifact directory; the response carries ' +
-            'the absolute path and byte count (zero image tokens). Pass `path` to ' +
-            'choose your own destination.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                selector: STRING_SELECTOR,
-                full_page: { type: 'boolean' },
-                path: {
-                    type: 'string',
-                    description: 'Absolute path to write the PNG to. If omitted, an artifact ' +
-                        'path is auto-allocated.',
-                },
-            },
+        description: 'Capture a PNG of the active page or one element. Written to disk under the ' +
+            'per-session artifact directory; the response carries the path and byte count, not ' +
+            'image tokens.',
+        // No destination parameter: the description promises the per-session
+        // artifact directory, and a caller-supplied path made that promise false
+        // — it could write a PNG anywhere the process could reach. The server
+        // allocates the path instead.
+        params: {
+            selector: OPTIONAL_SELECTOR,
+            full_page: { type: 'boolean' },
         },
-        mutating: false,
-        returnsImage: true,
+        annotations: { ...readOnly('Screenshot'), idempotentHint: false },
         toDispatch: (a) => ({
             cmd: 'screenshot',
             args: {
                 ...(a.selector ? { selector: a.selector } : {}),
                 fullPage: a.full_page,
-                ...(a.path ? { path: a.path } : {}),
             },
         }),
     },
     {
-        name: 'browser_trace',
-        description: 'Start or stop browser tracing. Stop with path to create a zip playable at player.vibium.dev.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                action: { type: 'string', enum: ['start', 'stop'] },
-                out_dir: { type: 'string', description: 'Raw trace directory; required for start.' },
-                path: { type: 'string', description: 'Vibium-compatible zip path; used for stop.' },
-                title: { type: 'string', description: 'Viewer title; used for start.' },
+        name: 'browser_status',
+        description: 'Report whether a browser is up and which URL is active.',
+        params: {},
+        annotations: readOnly('Status', false),
+        toDispatch: () => ({ cmd: 'status', args: {} }),
+    },
+    // ---- pages, evidence, and artifacts -------------------------------------
+    {
+        name: 'browser_page',
+        description: 'List, open, select, or close a tab. A tab the application opens is listed but never ' +
+            'selected implicitly. Switching or closing clears refs, so snapshot again afterwards.',
+        params: {
+            action: { type: 'string', required: true, enum: ['list', 'open', 'select', 'close'] },
+            target: { type: 'string', maxLength: 128, description: 'Index or page id.' },
+            url: { type: 'string', maxLength: 2048, description: 'Used with action=open.' },
+        },
+        annotations: mutating('Tabs'),
+        toDispatch: (a) => ({
+            cmd: 'page',
+            args: {
+                action: a.action,
+                ...(a.target !== undefined ? { target: a.target } : {}),
+                ...(a.url !== undefined ? { url: a.url } : {}),
+            },
+        }),
+    },
+    {
+        name: 'browser_logs',
+        description: 'Console and network history for this session, captured from launch — so an error ' +
+            'thrown during the first navigation is still answerable. Every result carries a ' +
+            'cursor; pass it back as `since` for only what is new. kind=error covers both ' +
+            'uncaught exceptions and console.error. Network rows are summaries: no bodies, ' +
+            'cookies or headers.',
+        params: {
+            action: { type: 'string', enum: ['list', 'wait', 'clear'] },
+            kind: {
+                type: 'string',
+                maxLength: 64,
+                description: 'Comma-separated: console, error, request, response.',
             },
-            required: ['action'],
+            level: { type: 'string', maxLength: 32 },
+            contains: { type: 'string', maxLength: 512 },
+            since: { type: 'number', min: 0, integer: true },
+            limit: { type: 'number', min: 1, max: 500, integer: true },
+            timeout_ms: TIMEOUT,
         },
-        mutating: false,
-        toDispatch: (a) => a.action === 'start'
-            ? { cmd: 'trace-start', args: { outDir: a.out_dir, title: a.title } }
-            : { cmd: 'trace-stop', args: { path: a.path } },
+        annotations: readOnly('Console and network'),
+        toDispatch: (a) => ({
+            cmd: 'logs',
+            args: {
+                action: a.action ?? 'list',
+                kind: a.kind,
+                level: a.level,
+                contains: a.contains,
+                since: a.since,
+                limit: a.limit,
+                timeout: a.timeout_ms,
+            },
+        }),
     },
     {
-        name: 'browser_status',
-        description: 'Report whether a browser is up and which URL is active.',
-        inputSchema: { type: 'object', properties: {} },
-        mutating: false,
-        toDispatch: () => ({ cmd: 'status', args: {} }),
+        name: 'browser_mock',
+        description: 'Serve a fixed response for matching requests, or block them, so an error path can be ' +
+            'driven without changing the application. Validated before installation and bounded ' +
+            'in count. Clear them when done — they outlive the call that added them.',
+        params: {
+            action: { type: 'string', enum: ['add', 'block', 'list', 'remove', 'clear'] },
+            pattern: { type: 'string', maxLength: 500, description: 'URL pattern, e.g. **/api/*.' },
+            status: { type: 'number', min: 100, max: 599, integer: true },
+            body: { type: 'string', maxLength: 64 * 1024 },
+            content_type: { type: 'string', maxLength: 128 },
+            id: { type: 'string', maxLength: 128, description: 'Used with action=remove.' },
+        },
+        annotations: mutating('Network mocks'),
+        toDispatch: (a) => ({
+            cmd: 'mock',
+            args: {
+                action: a.action ?? 'list',
+                pattern: a.pattern,
+                status: a.status,
+                body: a.body,
+                contentType: a.content_type,
+                id: a.id,
+            },
+        }),
     },
+    {
+        name: 'browser_state',
+        description: 'Save or restore cookies and local storage, so a login is captured once instead of ' +
+            'replayed. Navigate to the site BEFORE loading: local storage only restores onto its ' +
+            'own origin, and loading onto a blank page would silently drop it. Names are bare ' +
+            '(no paths); values are never printed.',
+        params: {
+            action: { type: 'string', enum: ['save', 'load', 'list'] },
+            name: { type: 'string', maxLength: 64 },
+            session_storage: { type: 'boolean', description: 'Include sessionStorage on save.' },
+        },
+        annotations: { ...mutating('Login state'), destructiveHint: true },
+        toDispatch: (a) => ({
+            cmd: 'state',
+            args: {
+                action: a.action ?? 'list',
+                ...(a.name !== undefined ? { name: a.name } : {}),
+                sessionStorage: a.session_storage,
+            },
+        }),
+    },
+    {
+        name: 'browser_trace',
+        description: 'Record actions, console, network and screenshots to a file for a failure a snapshot ' +
+            'cannot explain. One trace at a time; output lands in an owned directory. Stop with ' +
+            'zip for an archive playable at player.vibium.dev.',
+        params: {
+            action: { type: 'string', enum: ['start', 'stop', 'status'] },
+            name: { type: 'string', maxLength: 64, description: 'Bare name; used with start.' },
+            zip: { type: 'boolean', description: 'Also write an archive; used with stop.' },
+            no_screenshots: { type: 'boolean', description: 'Skip screenshots; used with start.' },
+        },
+        annotations: mutating('Tracing'),
+        toDispatch: (a) => ({
+            cmd: 'trace',
+            args: {
+                action: a.action ?? 'status',
+                ...(a.name !== undefined ? { name: a.name } : {}),
+                zip: a.zip,
+                noScreenshots: a.no_screenshots,
+            },
+        }),
+    },
+    // ---- escape hatch -------------------------------------------------------
     {
         name: 'browser_advanced_eval',
-        description: 'Evaluate arbitrary JavaScript in the page. LAST RESORT — prefer ' +
-            'browser_find/click/fill when possible. Costs tokens and bypasses auto-wait.',
-        inputSchema: {
-            type: 'object',
-            properties: { js: { type: 'string' } },
-            required: ['js'],
-        },
-        mutating: true,
+        description: 'Evaluate arbitrary JavaScript in the page. LAST RESORT — prefer the targeted tools. ' +
+            'Costs tokens and bypasses auto-wait.',
+        params: { js: { type: 'string', required: true, maxLength: 32 * 1024 } },
+        annotations: { ...mutating('Evaluate JavaScript'), destructiveHint: true },
         toDispatch: (a) => ({ cmd: 'eval', args: { js: a.js } }),
     },
 ];
@@ -246,9 +440,30 @@ const BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
 export function getTool(name) {
     return BY_NAME.get(name);
 }
-/** Run a tool against the dispatcher. Throws CraftdriverError on failure. */
-export async function runTool(ctx, tool, args) {
-    const mapped = tool.toDispatch(args);
-    return dispatch(ctx, mapped.cmd, mapped.args);
+/** The advertised schema for a tool, derived from its parameter descriptor. */
+export function inputSchemaFor(tool) {
+    return toInputSchema(tool.params);
+}
+/**
+ * Validate arguments against the tool's descriptor.
+ *
+ * Separate from dispatch so the server can reject before touching the session
+ * queue: an invalid call should not wait behind a slow browser action to be
+ * told it was malformed.
+ */
+export function validateToolArgs(tool, args) {
+    return validateArgs(tool.name, tool.params, args);
+}
+/** Map a tool to a dispatcher command and run it through the shared session. */
+export async function runTool(session, tool, args) {
+    return session.run(tool.toDispatch(args));
+}
+/**
+ * As {@link runTool}, but keeps the post-action snapshot the session captured
+ * in the same operation. The MCP adapter renders that as the second content
+ * block; it does not compute or own it.
+ */
+export async function runToolDetailed(session, tool, args) {
+    return session.runDetailed(tool.toDispatch(args));
 }
 //# sourceMappingURL=tools.js.map