dsh-builtin-browser 0.4.1 → 0.4.5

package/lib/tool-browser/index.js

@@ -14,6 +14,7 @@
  * @module dsh-browser/tool-browser
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { ELEMENT_ITEM_SCHEMA, NODE_ITEM_SCHEMA, projectElement, projectNode, } from './element-fields.js';
 /**
  * Register a cleanup that runs once when the process exits.
  *
@@ -66,7 +67,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 +98,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 +215,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 +227,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.
@@ -236,18 +279,8 @@ export function apply(ctx, config = {}) {
                     elements: {
                         type: 'array',
                         required: true,
-                        items: {
-                            type: 'object',
-                            additionalProperties: false,
-                            properties: {
-                                ref: { type: 'number', required: true },
-                                kind: { type: 'string', required: true },
-                                label: { type: 'string', required: true },
-                                x: { type: 'number', required: true },
-                                y: { type: 'number', required: true },
-                                frame: { type: 'boolean' },
-                            },
-                        },
+                        // Same shared item schema as browser_open's, so the two cannot drift apart.
+                        items: ELEMENT_ITEM_SCHEMA,
                     },
                     challenge: {
                         type: 'object',
@@ -281,7 +314,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 => projectElement(el)),
                 truncated: snapshot.truncated,
                 ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
             };
@@ -314,6 +347,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 +380,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 => projectElement(el)),
                 truncated: snapshot.truncated,
                 ...snapshot.challenge !== undefined ? { challenge: snapshot.challenge } : {},
             };
@@ -349,10 +388,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: {
@@ -367,22 +406,8 @@ export function apply(ctx, config = {}) {
                     nodes: {
                         type: 'array',
                         required: true,
-                        items: {
-                            type: 'object',
-                            additionalProperties: false,
-                            properties: {
-                                ref: { type: 'number', required: true },
-                                role: { type: 'string', required: true },
-                                name: { type: 'string', required: true },
-                                value: { type: 'string' },
-                                states: { type: 'array', required: true, items: { type: 'string' } },
-                                depth: { type: 'number', required: true },
-                                tag: { type: 'string', required: true },
-                                x: { type: 'number', required: true },
-                                y: { type: 'number', required: true },
-                                frame: { type: 'boolean' },
-                            },
-                        },
+                        // Same shared table as the node projection.
+                        items: NODE_ITEM_SCHEMA,
                     },
                 },
             },
@@ -396,13 +421,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}` }];
             },
         },
@@ -422,18 +456,18 @@ export function apply(ctx, config = {}) {
                 ...result.title !== undefined ? { title: result.title } : {},
                 count: result.count,
                 truncated: result.truncated,
-                nodes: result.nodes.map(n => ({
-                    ref: n.ref,
-                    role: n.role,
-                    name: n.name,
-                    ...n.value !== null ? { value: n.value } : {},
-                    states: [...n.states],
-                    depth: n.depth,
-                    tag: n.tag,
-                    x: n.x,
-                    y: n.y,
-                    ...n.frame === true ? { frame: true } : {},
-                })),
+                // The projection drops `value: null` (the schema declares a string, and the contract is
+                // that an absent value means "not applicable"), so the run-time shape and the inferred
+                // type differ by exactly that. The field table is what keeps the schema and the
+                // projection in agreement; this assertion is the type-level echo of that.
+                // The projection and the schema are now generated from one field table, so the shape
+                // they agree on is guaranteed at run time. TypeScript cannot see that agreement — it
+                // infers the output type from the schema object and compares it against the provider's
+                // interface, which describes the provider's internal shape rather than the contract
+                // (`value` nullable internally, absent on the wire; `selector` required by the
+                // interface, optional in the inferred schema). The assertion bridges that last gap; the
+                // test that walks every registered tool is what checks the agreement for real.
+                nodes: result.nodes.map(n => projectNode(n)),
             };
         },
     }));
@@ -504,7 +538,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 +564,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 +616,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 +662,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 +721,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 +775,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 +971,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 +1206,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,11 +1220,13 @@ 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.' },
                 },
             },
-            render: (_args, value) => [{ type: 'text', text: `Screenshot captured (${Math.round(value.dataUrl.length * 3 / 4 / 1024)} KiB)${value.path !== undefined ? ` saved to ${value.path}` : ''}.` }],
+            render: (_args, value) => [{ type: 'text', text: `Screenshot captured (${Math.round(value.dataUrl.length * 3 / 4 / 1024)} KiB${value.width !== undefined && value.height !== undefined ? `, ${value.width}x${value.height}` : ''})${value.path !== undefined ? ` saved to ${value.path}` : ''}.` }],
         },
         timeoutMs,
         isConcurrencySafe: () => true,
@@ -1187,6 +1246,12 @@ export function apply(ctx, config = {}) {
             return {
                 dataUrl: shot.dataUrl,
                 ...shot.path !== undefined ? { path: shot.path } : {},
+                // The provider measures these when it scales, the schema declares them, and the seam
+                // type carries them — but this mapping is an allow-list, so leaving them out dropped
+                // them silently. Same shape of bug as the a11y selector, found the same way: by
+                // reading the three places that mention a field and noticing this one did not.
+                ...shot.width !== undefined ? { width: shot.width } : {},
+                ...shot.height !== undefined ? { height: shot.height } : {},
             };
         },
     }));
@@ -1300,7 +1365,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 +1391,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 +1495,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 +1659,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',
@@ -1651,7 +1726,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.1",
+  "version": "0.4.5",
   "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,9 @@
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
-    "LICENSE"
+    "CHANGELOG.md",
+    "LICENSE",
+    "scripts"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -73,7 +75,10 @@
     "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 <0.3.0",
     "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2 <0.3.0",
     "@deepseek-ai/dsh-system-prompt": ">=0.1.1-rc.2 <0.3.0",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.1-rc.2 <0.3.0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.1-rc.2 <0.3.0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.1-rc.2 <0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -102,7 +107,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"
       }
     }
   }