dsh-builtin-browser 0.4.0 → 0.4.2

package/lib/tool-browser/index.js

@@ -66,7 +66,10 @@ export const READ_ONLY_TOOLS = new Set([
     'browser_list_tabs', 'browser_session', 'browser_history', 'browser_visited',
     // browser_auth reads cookies out of the browser: an observation, and one the
     // credentials switch gates on its own (see credentials.allowRead in the settings).
-    'browser_auth',
+    // browser_auth is deliberately NOT here. It reads cookies on "flush" but WRITES them on
+    // "restore", to arbitrary domains, which is an action like any other — exempting the tool
+    // would let a task that restricted its own actions rewrite the shared browser's logins.
+    //
     // Getting out of a bad state, or lifting the restriction itself. Without these a task
     // that restricted everything could neither recover nor be released.
     'browser_restrict', 'browser_reset_session', 'browser_reset',
@@ -94,6 +97,26 @@ function assertAllowed(state, toolName, task) {
 function agentOf(exec) {
     return exec?.agent;
 }
+/**
+ * Read a target's `index`, refusing the values that cannot mean anything.
+ *
+ * The index is looked up in the page (`els[index] ?? null`), so a negative one — `-1`, the
+ * common "give me the last one" shorthand — matches nothing. The page script then treated
+ * that as "not on the page yet" and polled for its whole 10s budget before reporting
+ * "element not found", which reads like a slow page rather than a bad argument. Refusing it
+ * here names the real problem immediately.
+ * @param target - the caller's target, or undefined when there is none.
+ * @returns the index, or undefined to let the page default to 0.
+ */
+function targetIndex(target) {
+    const index = target?.index;
+    if (index === undefined)
+        return undefined;
+    if (typeof index !== 'number' || !Number.isSafeInteger(index) || index < 0) {
+        throw new Error(`target.index must be a non-negative integer (got ${JSON.stringify(index)}); it is a 0-based position among the matches, and negative values such as -1 match nothing — pass the position you want, or narrow the selector`);
+    }
+    return index;
+}
 /**
  * The task key for a tool call: the calling DSH session id, or the shared
  * default key when the call carries no agent context (CLI probes, tests).
@@ -191,7 +214,7 @@ function parseFillValue(v) {
  */
 function formatSnapshot(snapshot, options = {}) {
     const showCoords = options.coords === true;
-    const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.frame === true ? ' (iframe)' : ''}${showCoords ? ` (${el.x},${el.y})` : ''}`);
+    const lines = snapshot.elements.map(el => `[${el.ref}] ${el.kind}: ${el.label}${el.selector !== undefined && el.selector !== '' ? ` {${el.selector}}` : ''}${el.frame === true ? ' (iframe)' : ''}${showCoords ? ` (${el.x},${el.y})` : ''}`);
     const header = `URL: ${snapshot.url}${snapshot.title !== undefined ? `\nTitle: ${snapshot.title}` : ''}`;
     const body = lines.length > 0 ? lines.join('\n') : '(no interactive elements found)';
     const tail = snapshot.truncated === true ? '\n(snapshot truncated)' : '';
@@ -203,6 +226,25 @@ function formatSnapshot(snapshot, options = {}) {
 /** Register all browser tools with `ctx.tools`. */
 export function apply(ctx, config = {}) {
     const timeoutMs = config.timeoutMs ?? 60_000;
+    /**
+     * Longest wait `browser_wait` may poll for, leaving room for the tool call itself to
+     * finish and report.
+     *
+     * `browser_wait` promises a VERDICT — `{ready:false, reason}` — and the enclosing tool
+     * call aborts at `timeoutMs`. A caller-supplied budget longer than that aborted the call
+     * instead, so the documented verdict never arrived. Clamping to just inside the budget is
+     * what keeps the promise: the polling stops, the reason is returned.
+     */
+    const maxWaitMs = Math.max(250, timeoutMs - 5_000);
+    /**
+     * Most fields `browser_fill` accepts in one batch.
+     *
+     * The batch runs as ONE page evaluation, so hundreds of fields do not produce hundreds of
+     * per-field verdicts — they produce a single evaluate that exceeds the tool budget and
+     * throws, which is the opposite of the documented "per-field failures are reported instead
+     * of throwing". Real forms are far smaller than this; anything larger should be split.
+     */
+    const maxFillFields = 200;
     // Per-context state: sessions, in-flight opens, and the restriction are
     // scoped to THIS plugin apply, so parallel contexts never share sessions
     // or leak restrictions into each other.
@@ -246,6 +288,12 @@ export function apply(ctx, config = {}) {
                                 x: { type: 'number', required: true },
                                 y: { type: 'number', required: true },
                                 frame: { type: 'boolean' },
+                                // The page-side script computes this for every element and the tool layer
+                                // passes it through. Without it in the schema, a declared
+                                // additionalProperties: false rejects the whole result at run time — which is
+                                // how this was found, on the very first real call, after a static review had
+                                // called the change verified.
+                                selector: { type: 'string' },
                             },
                         },
                     },
@@ -281,7 +329,7 @@ export function apply(ctx, config = {}) {
             return {
                 url: snapshot.url,
                 ...snapshot.title !== undefined ? { title: snapshot.title } : {},
-                elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
+                elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, selector: el.selector, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
                 truncated: snapshot.truncated,
                 ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
             };
@@ -314,6 +362,12 @@ export function apply(ctx, config = {}) {
                                 x: { type: 'number', required: true },
                                 y: { type: 'number', required: true },
                                 frame: { type: 'boolean' },
+                                // The page-side script computes this for every element and the tool layer
+                                // passes it through. Without it in the schema, a declared
+                                // additionalProperties: false rejects the whole result at run time — which is
+                                // how this was found, on the very first real call, after a static review had
+                                // called the change verified.
+                                selector: { type: 'string' },
                             },
                         },
                     },
@@ -341,7 +395,7 @@ export function apply(ctx, config = {}) {
             return {
                 url: snapshot.url,
                 ...snapshot.title !== undefined ? { title: snapshot.title } : {},
-                elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
+                elements: snapshot.elements.map(el => ({ ref: el.ref, kind: el.kind, label: el.label, selector: el.selector, x: el.x, y: el.y, ...el.frame === true ? { frame: true } : {} })),
                 truncated: snapshot.truncated,
                 ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
             };
@@ -349,10 +403,10 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_a11y',
-        description: 'Read the page\'s accessibility tree: every interactive node with its semantic role (button/link/textbox/checkbox/…), accessible name, current value, and states (enabled/disabled/checked/expanded/…), plus coordinates. Prefer this over browser_snapshot to understand a page\'s structure and find the right element: roles and names tell you WHAT each node is, and the coordinates let you drive it with browser_click/browser_type. Penetrates same-origin iframes and shadow roots.',
+        description: 'Read the page\'s accessibility tree: every interactive node with its semantic role (button/link/textbox/checkbox/…), accessible name, current value, and states (enabled/disabled/checked/expanded/…), (coordinates only when coords: true). Prefer this over browser_snapshot to understand a page\'s structure and find the right element: roles and names tell you WHAT each node is, and the name is what browser_click matches when you target by text. Penetrates same-origin iframes and shadow roots.',
         parameters: {
             includeHidden: { type: 'boolean', description: 'Include hidden elements (default false).' },
-            maxNodes: { type: 'number', description: 'Maximum nodes (default 500, range 10-5000).' },
+            maxNodes: { type: 'number', description: 'Maximum nodes (default 150, range 10-5000).' },
             coords: { type: 'boolean', description: 'Include each element\'s viewport coordinates. Off by default: a semantic target needs no coordinates, and they are pure noise unless a vision pass is going to click a pixel position.' },
         },
         output: {
@@ -381,6 +435,12 @@ export function apply(ctx, config = {}) {
                                 x: { type: 'number', required: true },
                                 y: { type: 'number', required: true },
                                 frame: { type: 'boolean' },
+                                // The page-side script computes this for every element and the tool layer
+                                // passes it through. Without it in the schema, a declared
+                                // additionalProperties: false rejects the whole result at run time — which is
+                                // how this was found, on the very first real call, after a static review had
+                                // called the change verified.
+                                selector: { type: 'string' },
                             },
                         },
                     },
@@ -396,13 +456,22 @@ export function apply(ctx, config = {}) {
                 const showCoords = args.coords === true;
                 const lines = nodes.map(n => {
                     const valuePart = n.value !== undefined && n.value !== null ? ` value="${String(n.value).slice(0, 60)}"` : '';
-                    const indent = '  '.repeat(Math.max(0, Math.min(8, Number(n.depth) || 0)));
+                    // One space per level, not two: indentation was 19.7% of a measured 38,953-character
+                    // result, and DOM depth is not a11y depth — deep wrapper divs push it to the cap.
+                    const indent = ' '.repeat(Math.max(0, Math.min(8, Number(n.depth) || 0)));
                     const coordsPart = showCoords ? ` (${n.x},${n.y})` : '';
-                    const statePart = Array.isArray(n.states) && n.states.length > 0 ? ` states=[${n.states.join(',')}]` : '';
-                    return `${indent}[${n.ref}] ${n.role} "${n.name}"${valuePart}${coordsPart}${statePart}${n.frame === true ? ' (iframe)' : ''}`;
+                    // Only states that are not the default. `states=[enabled]` was printed on 405 of 500
+                    // nodes whose state WAS the default — 22% of the output for no information. Absence
+                    // now means "enabled", which the description states.
+                    const notableStates = Array.isArray(n.states) ? n.states.filter((state) => state !== 'enabled') : [];
+                    const statePart = notableStates.length > 0 ? ` states=[${notableStates.join(',')}]` : '';
+                    // The provider computes this for a node with an id or a name; printing it is what
+                    // makes the node something the caller can point at instead of guessing at its text.
+                    const selectorPart = typeof n.selector === 'string' && n.selector !== '' ? ` {${n.selector}}` : '';
+                    return `${indent}[${n.ref}] ${n.role} "${n.name}"${valuePart}${coordsPart}${statePart}${selectorPart}${n.frame === true ? ' (iframe)' : ''}`;
                 });
                 const header = `URL: ${value.url}${value.title !== undefined ? `\nTitle: ${value.title}` : ''}`;
-                const hint = showCoords ? '' : '\n(coordinates omitted — pass coords: true to include them, or click by semantic target)';
+                const hint = showCoords ? '' : '\n(no coords; pass coords: true)';
                 return [{ type: 'text', text: `${header}\n\n${lines.length > 0 ? lines.join('\n') : '(no accessible interactive nodes)'}${value.truncated === true ? '\n(truncated)' : ''}${hint}` }];
             },
         },
@@ -430,6 +499,11 @@ export function apply(ctx, config = {}) {
                     states: [...n.states],
                     depth: n.depth,
                     tag: n.tag,
+                    // The provider computes this and the renderer prints it, but this mapping is an
+                    // explicit allow-list rather than a pass-through — so leaving it out here silently
+                    // dropped the field between the two, and the tool promised a reference it never
+                    // sent. The snapshot mapping lists its selector; this one did not.
+                    selector: n.selector,
                     x: n.x,
                     y: n.y,
                     ...n.frame === true ? { frame: true } : {},
@@ -504,7 +578,9 @@ export function apply(ctx, config = {}) {
                 throw new Error('tool-browser: browser service unavailable');
             const session = await ensureSession(browser, state, taskKey(exec), agentOf(exec));
             const result = await browser.waitFor(session, {
-                ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
+                // Capped so an over-budget argument returns the documented verdict (see maxWaitMs)
+                // rather than aborting the whole tool call.
+                ...args.timeoutMs !== undefined ? { timeoutMs: Math.min(args.timeoutMs, maxWaitMs) } : {},
                 ...args.url !== undefined ? { url: args.url } : {},
                 ...args.selector !== undefined ? { selector: args.selector } : {},
             }, exec.signal);
@@ -528,7 +604,19 @@ export function apply(ctx, config = {}) {
                     exception: { type: 'string' },
                 },
             },
-            render: (_args, value) => [{ type: 'text', text: value.ok ? `Result: ${String(value.value)}` : `Exception: ${value.exception}` }],
+            // A return value is whatever the page produced, and `document.body.outerHTML` measured
+            // 157,350 characters — ~39-52k tokens from one call. Bounded, with the cut stated so the
+            // caller knows to narrow the expression rather than the value being silently short.
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: `Exception: ${value.exception}` }];
+                const rendered = String(value.value ?? '');
+                const cap = 50_000;
+                const text = rendered.length > cap
+                    ? `Result: ${rendered.slice(0, cap)}\n(result truncated at ${cap} of ${rendered.length} characters — return a smaller value, or write it with browser_execute + a variable)`
+                    : `Result: ${rendered}`;
+                return [{ type: 'text', text }];
+            },
         },
         timeoutMs,
         isConcurrencySafe: () => false, // page JS can be stateful
@@ -568,7 +656,7 @@ export function apply(ctx, config = {}) {
                     truncated: { type: 'boolean', required: true },
                 },
             },
-            render: (_args, value) => [{ type: 'text', text: value.content + (value.truncated ? '\n(truncated)' : '') }],
+            render: (_args, value) => [{ type: 'text', text: value.content + (value.truncated ? `\n(content truncated — narrow it with selector= or raise maxChars)` : '') }],
         },
         timeoutMs,
         isConcurrencySafe: () => true,
@@ -614,7 +702,10 @@ export function apply(ctx, config = {}) {
             },
             render: (_args, value) => [{
                     type: 'text',
-                    text: `${value.count} item(s):\n${JSON.stringify(value.items, null, 2)}`,
+                    // Compact, unlike the pretty-printed form this used to emit: two-space indentation
+                    // carries no information a model can use and cost 13.7% of a measured 39,559-character
+                    // result. The count leads so the caller can tell a short list from a capped one.
+                    text: `${value.count} item(s):\n${JSON.stringify(value.items)}`,
                 }],
         },
         timeoutMs,
@@ -670,12 +761,13 @@ export function apply(ctx, config = {}) {
             if (target !== undefined && typeof target.value === 'string' && target.value === '') {
                 throw new Error('target.value is empty; pass a css selector, visible text or XPath, or omit target entirely to use x/y');
             }
+            const index = targetIndex(target);
             if (target !== undefined && typeof target.value === 'string' && target.value !== '') {
                 await browser.click(session, {
                     target: {
                         by: (target.by === 'text' || target.by === 'xpath' ? target.by : 'css'),
                         value: target.value,
-                        ...target.index !== undefined ? { index: target.index } : {},
+                        ...index !== undefined ? { index } : {},
                     },
                 }, exec.signal);
             }
@@ -723,13 +815,14 @@ export function apply(ctx, config = {}) {
             if (target !== undefined && typeof target.value === 'string' && target.value === '') {
                 throw new Error('target.value is empty; pass a css selector, visible text or XPath, or omit target entirely to use x/y');
             }
+            const index = targetIndex(target);
             if (target !== undefined && typeof target.value === 'string' && target.value !== '') {
                 await browser.type(session, {
                     text: args.text,
                     target: {
                         by: (target.by === 'text' || target.by === 'xpath' ? target.by : 'css'),
                         value: target.value,
-                        ...target.index !== undefined ? { index: target.index } : {},
+                        ...index !== undefined ? { index } : {},
                     },
                 }, exec.signal);
             }
@@ -918,7 +1011,11 @@ export function apply(ctx, config = {}) {
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');
             const session = await ensureSession(browser, state, taskKey(exec), agentOf(exec));
-            const fields = (args.fields ?? []).map((f) => {
+            const requested = args.fields ?? [];
+            if (requested.length > maxFillFields) {
+                throw new Error(`browser_fill: ${requested.length} fields in one call exceeds the ${maxFillFields}-field limit; split it into several calls so each one can report per-field results instead of timing out as a batch`);
+            }
+            const fields = requested.map((f) => {
                 // A missing value is a caller mistake, not a request to clear the field. Turning
                 // it into '' silently unchecks a checkbox or empties a text input while the tool
                 // still reports success, so it fails loudly. The schema marks value required, but
@@ -1149,7 +1246,7 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_screenshot',
-        description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — browser_snapshot, browser_a11y and browser_content carry the same page as text, and browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG needs a browser whose CDP encoder works — the self-hosted browser and an installed Chrome/Edge; the desktop sidebar falls back to PNG because the Electron CDP JPEG encoder hangs. Downscaling works on every carrier.',
+        description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — browser_snapshot, browser_a11y and browser_content carry the same page as text, and browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG needs a browser whose CDP encoder works — the self-hosted browser and an installed Chrome/Edge; some carriers (the desktop sidebar) return PNG instead. Downscaling works on every carrier.',
         parameters: {
             fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (default false).' },
             savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location). Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
@@ -1163,7 +1260,9 @@ export function apply(ctx, config = {}) {
                 type: 'object',
                 additionalProperties: false,
                 properties: {
-                    dataUrl: { type: 'string', required: true, description: 'Base64 PNG data URL of the screenshot.' },
+                    dataUrl: { type: 'string', required: true, description: 'Base64 data URL of the screenshot (PNG, or JPEG when the carrier uses CDP JPEG).' },
+                    width: { type: 'number', description: 'Pixel width of the returned image, when the capture was measured (present with maxWidth/maxHeight).' },
+                    height: { type: 'number', description: 'Pixel height of the returned image, when the capture was measured.' },
                     path: { type: 'string', description: 'The file path the screenshot was saved to, when savePath was given.' },
                 },
             },
@@ -1300,7 +1399,9 @@ export function apply(ctx, config = {}) {
     ctx.tools.register(defineTool({
         name: 'browser_history',
         description: 'List the shared browser session\'s recorded operation history (navigate/execute/click/type), newest last, with per-step success/error. Use to understand what the agent did and to pick a step to replay.',
-        parameters: {},
+        parameters: {
+            verbose: { type: 'boolean', description: "Include each operation's parameters (default false). They are what you just sent, so they are omitted unless asked for." },
+        },
         output: {
             schema: {
                 type: 'object',
@@ -1324,18 +1425,21 @@ export function apply(ctx, config = {}) {
                     },
                 },
             },
-            render: (_args, value) => {
+            render: (args, value) => {
                 const entries = value.entries;
                 if (entries.length === 0)
                     return [{ type: 'text', text: '(no recorded operations yet)' }];
-                return [{
-                        type: 'text',
-                        text: entries.map(e => {
-                            const rawParams = JSON.stringify(e.params);
-                            const shownParams = rawParams.length > 300 ? rawParams.slice(0, 300) + '…' : rawParams;
-                            return `#${e.seq} ${e.action} ${e.ok ? 'ok' : 'FAIL'} ${shownParams}${e.result !== undefined ? ` -> ${e.result}` : ''}${e.error !== undefined ? ` !! ${e.error}` : ''}`;
-                        }).join('\n'),
-                    }];
+                // The parameters are what the caller itself just sent, so echoing them back is cost
+                // without information — measured at 18,162 characters for 200 operations, of which the
+                // per-entry params dominated. Only the tail is shown by default: the recent steps are
+                // what a caller reasons about, and the count leads so the tail is not mistaken for all.
+                const recent = entries.slice(-20);
+                const omitted = entries.length - recent.length;
+                const lines = recent.map(e => `#${e.seq} ${e.action} ${e.ok ? 'ok' : 'FAIL'}${e.result !== undefined ? ` -> ${e.result}` : ''}${e.error !== undefined ? ` !! ${e.error}` : ''}${args.verbose === true ? ` ${JSON.stringify(e.params)}` : ''}`);
+                const header = omitted > 0
+                    ? `${entries.length} operations recorded; showing the last ${recent.length} (${args.verbose === true ? '' : ' (pass verbose: true for parameters)'}):`
+                    : `${entries.length} operation(s):`;
+                return [{ type: 'text', text: `${header}\n${lines.join('\n')}` }];
             },
         },
         timeoutMs,
@@ -1425,15 +1529,20 @@ export function apply(ctx, config = {}) {
             },
             render: (_args, value) => {
                 const entries = value.entries;
+                let lastSession;
                 if (entries.length === 0) {
                     return [{ type: 'text', text: '(no recorded visits — nothing has been browsed yet, or history recording is turned off in settings)' }];
                 }
                 return [{
                         type: 'text',
                         text: entries.map(entry => {
-                            const when = new Date(entry.at).toISOString().replace('T', ' ').slice(0, 19);
+                            const when = new Date(entry.at).toISOString().replace('T', ' ').slice(0, 16);
                             const title = entry.title !== undefined ? `${entry.title} — ` : '';
-                            return `${when}  ${title}${entry.url}${entry.session !== undefined ? `  [${entry.session}]` : ''}`;
+                            const tag = entry.session !== undefined && entry.session !== lastSession
+                                ? `  [session ${entry.session.slice(0, 8)}]`
+                                : '';
+                            lastSession = entry.session;
+                            return `${when}  ${title}${entry.url}${tag}`;
                         }).join('\n'),
                     }];
             },
@@ -1584,7 +1693,7 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_restrict',
-        description: 'Restrict which browser actions are allowed, to prevent stray clicks/navigation. Pass a list of browser tool names (e.g. ["browser_snapshot","browser_content","browser_click"]) — any other browser_* call is refused. Pass an empty list or omit to lift the restriction. Read-only tools (snapshot/content/screenshot/session) are never blocked. IMPORTANT: this is a SOFT guardrail against accidental actions, NOT a security boundary — you (the model) can lift it yourself with an empty list.',
+        description: 'Restrict which browser actions are allowed, to prevent stray clicks/navigation. Pass a list of browser tool names (e.g. ["browser_snapshot","browser_content","browser_click"]) — any other browser_* call is refused. Pass an empty list or omit to lift the restriction. Never blocked, whatever the list says: the observing tools (snapshot/a11y/content/scrape/screenshot/get_value/wait/challenge/list_tabs/session/history/visited) and the three that lift a restriction or recover from a bad state (restrict/reset/reset_session) — so a restriction can always be read around and undone. IMPORTANT: this is a SOFT guardrail against accidental actions, NOT a security boundary — you (the model) can lift it yourself with an empty list.',
         parameters: {
             allowed: {
                 type: 'array',
@@ -1619,7 +1728,7 @@ export function apply(ctx, config = {}) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_auth',
-        description: 'Export or restore the browser session\'s cookies (login state). Use "flush" to get a JSON cookie list (save it to a private file to persist logins), or "restore" with that list to put logins back (e.g. after the browser host restarted). Available on the self-hosted browser. Exported cookies are LIVE CREDENTIALS: treat them as secrets — do not echo them into the conversation, keep them out of logs, and store the list in a private file.',
+        description: 'Export or restore the browser session\'s cookies (login state). Use "flush" to get a JSON cookie list (save it to a private file to persist logins), or "restore" with that list to put logins back (e.g. after the browser host restarted). Available on all three carriers: the self-hosted browser reads its own session, while the desktop sidebar and an installed Chrome/Edge go through CDP. Refused entirely when the credential switch is off. Exported cookies are LIVE CREDENTIALS: treat them as secrets — do not echo them into the conversation, keep them out of logs, and store the list in a private file.',
         parameters: {
             action: { type: 'string', required: true, enum: ['flush', 'restore'], description: 'flush = export cookies; restore = import cookies.' },
             cookies: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Cookie list to restore (required when action=restore).' },
@@ -1651,7 +1760,7 @@ export function apply(ctx, config = {}) {
             // empty call returned {restored: 0} and rendered 'Restored 0 cookies.', which
             // reads as success and would leave the caller believing the login was restored.
             if (!Array.isArray(args.cookies) || args.cookies.length === 0) {
-                throw new Error('browser_auth: action "restore" needs a non-empty "cookies" array (get one from action "export" on the same profile)');
+                throw new Error('browser_auth: action "restore" needs a non-empty "cookies" array (get one from action "flush" on the same profile)');
             }
             const list = args.cookies;
             const restored = await browser.restoreAuth(session, list);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",
@@ -40,7 +40,8 @@
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
-    "LICENSE"
+    "LICENSE",
+    "scripts"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -102,7 +103,8 @@
         "0.1.1-rc.1": "compatible",
         "0.1.1-rc.2": "compatible",
         "0.2.0-rc.1": "compatible",
-        "0.2.0-rc.2": "compatible"
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-alpha.1": "compatible"
       }
     }
   }

package/scripts/verify-host-compat.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * Host-compatibility probe: does THIS build of the plugin run on the DSH in front of it?
+ *
+ * A version range in package.json is a claim, not evidence. This assembles a host out of the
+ * real DSH packages installed in a profile, loads the plugin's compiled output, registers its
+ * tools through the host's own `defineTool`, and calls two of them over the plugin's provider
+ * seam. It is the check that answers "did DSH 0.2.x break us?" without booting a browser.
+ *
+ * Usage:
+ *   node scripts/verify-host-compat.mjs                 # probe the profile named by DSH_PROFILE
+ *   DSH_PROFILE=desktop node scripts/verify-host-compat.mjs
+ *   DSH_HOME=/path/to/.dsh node scripts/verify-host-compat.mjs
+ *
+ * Resolution: the profile's own package.json is the module root, so `@deepseek-ai/*` resolves
+ * exactly as it does at runtime (links included). With no usable profile the probe reports
+ * that it could not run and exits 0 — an unprobeable host is not a compatibility failure, and
+ * making CI red for it would be reporting the wrong thing.
+ *
+ * What it does NOT cover: the browser actually launching (no Electron here), and the client
+ * panel rendering in a real session.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const REPO = new URL('..', import.meta.url)
+const failures = []
+
+const ok = (label, condition, detail = '') => {
+  console.log(`  ${condition ? 'OK  ' : 'FAIL'}  ${label}${detail === '' ? '' : `  — ${detail}`}`)
+  if (!condition) failures.push(label)
+}
+
+/** The profile whose node_modules resolve the host packages, or undefined. */
+function findProfileRoot() {
+  const home = process.env.DSH_HOME ?? join(process.env.USERPROFILE ?? process.env.HOME ?? '', '.dsh')
+  const profiles = join(home, 'profiles')
+  if (!existsSync(profiles)) return undefined
+  const named = process.env.DSH_PROFILE
+  const candidates = named !== undefined && named !== ''
+    ? [named]
+    : readdirSync(profiles).filter(entry => existsSync(join(profiles, entry, 'package.json')))
+  for (const candidate of candidates) {
+    const manifest = join(profiles, candidate, 'package.json')
+    if (existsSync(manifest)) return { name: candidate, manifest }
+  }
+  return undefined
+}
+
+const profile = findProfileRoot()
+if (profile === undefined) {
+  console.log('No DSH profile found (looked under $DSH_HOME/profiles).')
+  console.log('Set DSH_HOME or DSH_PROFILE to point at one; nothing to verify.')
+  process.exit(0)
+}
+
+const require = createRequire(profile.manifest)
+const load = async (spec) => import(pathToFileURL(require.resolve(spec)).href)
+
+console.log(`Host: profile "${profile.name}" at ${profile.manifest}`)
+let hostVersion = 'unknown'
+try {
+  hostVersion = JSON.parse(readFileSync(require.resolve('@deepseek-ai/dsh-system-prompt/package.json'), 'utf8')).version
+} catch { /* reported as unknown; the probe below is what matters */ }
+console.log(`      @deepseek-ai/dsh-system-prompt = ${hostVersion}`)
+console.log('')
+
+console.log('=== 1. the host API surface this plugin imports ===')
+let cordis
+let dshTools
+let dshLlm
+let schemastery
+try {
+  cordis = await load('@deepseek-ai/cordis')
+  dshTools = await load('@deepseek-ai/dsh-tools')
+  dshLlm = await load('@deepseek-ai/dsh-llm')
+  schemastery = await load('@deepseek-ai/schemastery')
+} catch (error) {
+  console.log(`  FAIL  a host package could not be resolved: ${String(error && error.message)}`)
+  process.exit(1)
+}
+const z = schemastery.default ?? schemastery
+
+ok('@deepseek-ai/cordis exports Context', typeof cordis.Context === 'function')
+ok('@deepseek-ai/cordis exports Service', typeof cordis.Service === 'function')
+ok('@deepseek-ai/dsh-tools exports defineTool', typeof dshTools.defineTool === 'function')
+ok('@deepseek-ai/dsh-llm exports HarnessError', typeof dshLlm.HarnessError === 'function')
+ok('@deepseek-ai/schemastery default is the schema builder', typeof z?.string === 'function')
+
+console.log('')
+console.log('=== 2. the plugin loads against a real cordis context ===')
+const root = new cordis.Context()
+
+// Stub services. DSH's own tools/systemPrompt implementations are not what is under test and
+// standing them up would mean booting a profile; only their SHAPE matters here, and it is
+// taken from the real ones: `ctx.tools.register(definition)`, `ctx.systemPrompt.section(spec)`.
+const registered = new Map()
+class StubTools extends cordis.Service {
+  constructor(ctx) { super(ctx, 'tools') }
+  register(definition) { registered.set(definition.name, definition); return () => {} }
+}
+class StubSystemPrompt extends cordis.Service {
+  constructor(ctx) { super(ctx, 'systemPrompt'); this.sections = [] }
+  section(spec) { this.sections.push(spec); return () => {} }
+}
+new StubTools(root)
+const prompts = new StubSystemPrompt(root)
+
+try {
+  const runtimeModule = await import(new URL('lib/browser/runtime.js', REPO).href)
+  ok('the plugin ships a browser seam service', typeof runtimeModule.default === 'function')
+  new runtimeModule.default(root)
+  ok('the seam registered itself as ctx.browser', root.get('browser') !== undefined)
+
+  const layer = await import(new URL('lib/tool-browser/index.js', REPO).href)
+  ok('the tool layer exports an apply()', typeof layer.apply === 'function')
+  layer.apply(root, {})
+  ok('tools registered through the host\'s own defineTool', registered.size > 30, `${registered.size} tools`)
+  ok('the system prompt section was declared', prompts.sections.length === 1)
+} catch (error) {
+  ok('the plugin loads and registers', false, String(error && error.stack).split('\n').slice(0, 2).join(' | '))
+}
+
+console.log('')
+console.log('=== 3. the definitions the host will consume ===')
+// `defineTool` already accepted every spec the plugin handed it — it throws on a shape it
+// cannot compile, and the tools came back — so what is left is the stored definition: a JSON
+// Schema the host can show a model, plus the output contract.
+const SCALAR_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'array', 'object', 'null'])
+const schemaFailures = []
+for (const [name, definition] of registered) {
+  if (typeof definition.execute !== 'function') schemaFailures.push(`${name}: no execute`)
+  if (definition.output?.schema === undefined) schemaFailures.push(`${name}: no output.schema`)
+  if (typeof definition.output?.render !== 'function') schemaFailures.push(`${name}: no output.render`)
+  if (typeof definition.description !== 'string' || definition.description === '') schemaFailures.push(`${name}: no description`)
+  const parameters = definition.parameters
+  if (typeof parameters !== 'object' || parameters === null) {
+    schemaFailures.push(`${name}: parameters is not a schema object`)
+    continue
+  }
+  if (parameters.type !== 'object') schemaFailures.push(`${name}: parameters.type is ${String(parameters.type)}`)
+  for (const [field, spec] of Object.entries(parameters.properties ?? {})) {
+    if (typeof spec?.type !== 'string' || !SCALAR_TYPES.has(spec.type)) schemaFailures.push(`${name}.${field}: type ${String(spec?.type)}`)
+  }
+}
+ok('every tool definition carries a usable schema', schemaFailures.length === 0, schemaFailures.slice(0, 4).join(' | '))
+
+console.log('')
+console.log('=== 4. a tool runs, over the plugin\'s own provider seam ===')
+const fakeSession = 'browser:00000000-0000-4000-8000-000000000001'
+try {
+  root.get('browser').registerBrowserProvider({
+    id: 'verify-host-compat',
+    available: () => true,
+    open: async () => fakeSession,
+    listTabs: async () => [{ id: 'tab:1', title: 'verify', url: 'about:blank', active: true }],
+    a11y: async () => ({
+      url: 'about:blank',
+      count: 1,
+      truncated: false,
+      nodes: [{ ref: 1, role: 'button', name: 'Probe', states: ['enabled'], depth: 0, tag: 'button', selector: '#probe', x: 1, y: 2 }],
+    }),
+  })
+} catch (error) {
+  ok('a provider can register on the seam', false, String(error && error.message))
+}
+
+const exec = { agent: { id: 'verify-host-compat' } }
+try {
+  const value = await registered.get('browser_session').execute({}, exec)
+  ok('browser_session ran', value !== undefined, JSON.stringify(value).slice(0, 100))
+} catch (error) {
+  ok('browser_session ran', false, String(error && error.message))
+}
+
+try {
+  const tool = registered.get('browser_a11y')
+  const value = await tool.execute({}, exec)
+  const text = JSON.stringify(tool.output.render({}, value))
+  ok('browser_a11y ran and rendered', value?.nodes?.length === 1, '')
+  ok('its renderer emits the element selector', text.includes('#probe'), text.slice(0, 120))
+} catch (error) {
+  ok('browser_a11y ran', false, String(error && error.message))
+}
+
+console.log('')
+if (failures.length === 0) {
+  console.log(`VERDICT: this build runs on the host above (${hostVersion}).`)
+} else {
+  console.log(`VERDICT: ${failures.length} failure(s) — this build does NOT match the host above:`)
+  for (const failure of failures) console.log(`  - ${failure}`)
+  process.exitCode = 1
+}