dsh-browser-playwright-codex 0.6.5 → 0.7.0

package/lib/plugin.js

@@ -0,0 +1,31 @@
+import z from '@deepseek-ai/schemastery';
+import BrowserRuntime, { Config as ServiceConfig } from "./service.js";
+import * as playwright from "./playwright.js";
+import * as tool from "./tool.js";
+import * as settingsCard from "./settings-card.js";
+import { Config as PlaywrightConfigSchema } from "./config.js";
+import { Config as ToolConfigSchema } from "./tool.js";
+/** Schemastery validation for {@link BrowserPluginConfig}. */
+export const Config = z.object({
+    service: ServiceConfig,
+    playwright: PlaywrightConfigSchema,
+    tool: ToolConfigSchema,
+});
+/** Cordis plugin name used by loader diagnostics (this is the row id in patches). */
+export const name = 'browser';
+/**
+ * Mount the whole capability: the seam, the Playwright provider, the tool family,
+ * and — when the deployment has a web server — the Settings card.
+ *
+ * @param ctx - plugin context
+ * @param config - nested config for each concern; the loader fills defaults
+ */
+export function apply(ctx, config) {
+    ctx.plugin(BrowserRuntime, config.service ?? {});
+    ctx.plugin(playwright, config.playwright);
+    ctx.plugin(tool, config.tool);
+    // The card's host half injects `webServer`, so in a CLI deployment this child
+    // simply stays pending instead of failing the whole plugin.
+    ctx.plugin(settingsCard);
+}
+export default { name, Config, apply };

package/lib/settings-card.d.ts

@@ -0,0 +1,9 @@
+export declare const name = "browser-toggle";
+export declare const inject: string[];
+export declare function apply(ctx: any): void;
+declare const _default: {
+    name: string;
+    inject: string[];
+    apply: typeof apply;
+};
+export default _default;

package/lib/settings-card.js

@@ -0,0 +1,268 @@
+/**
+ * Settings card host half, absorbed from dsh-browser-toggle 0.3.0 (2026-10-19).
+ * Same four /api/browser-playwright routes and CSRF rules; the only change is that the
+ * runtime state is now a sibling module instead of a package specifier.
+ *
+ * @module dsh-browser-playwright-codex/settings-card
+ */
+// @ts-nocheck — absorbed verbatim from the standalone package (plain JS), typed later.
+/**
+ * dsh-browser-toggle - Host half.
+ *
+ * HTTP API for the Settings → Plugins UI card that flips the runtime enable
+ * flag of dsh-browser-playwright-codex without restarting DSH.
+ *
+ *   GET  /api/browser-playwright/state             -> { enabled, engine, engineUserChosen, allowEvaluate, allowCdp }
+ *   POST /api/browser-playwright/toggle {enabled}   -> { enabled, changed }
+ *   POST /api/browser-playwright/engine {engine}    -> { engine, changed }
+ *   POST /api/browser-playwright/gates {allowEvaluate, allowCdp} -> { allowEvaluate, allowCdp, changed }
+ *   GET  /api/browser-playwright/logins             -> { logins: { source, capturedAt, cookies, total, sites } | null }
+ *
+ * `allowEvaluate` / `allowCdp` are the two power gates of the browser tool
+ * family: arbitrary page JavaScript and raw CDP. They are registration-time
+ * settings (an off gate means the tool is not registered at all, which is how
+ * the plugin keeps them out of the resident prompt), so this route cannot flip
+ * them in memory — it writes them into the home-level cordis.patch.yml, the
+ * layer with the highest priority among patch files, and lets the profile's
+ * `patchReload: live` re-apply the tree. The Settings page therefore reads the
+ * *effective* values published by the tool family (runtime-state.getGates),
+ * never a guess at the package default.
+ *
+ * The package itself ships both gates off: cordis.patch.yml travels inside the
+ * package, so anything it enabled would be enabled for every installer. This
+ * route is how a user opts in, in their own layer.
+ *
+ * `engine` is the page-reading mode: 'legacy' (the plugin's own DOM walk) or
+ * 'aria' (the browser's official accessibility tree). It is a user setting too,
+ * so it lives next to the enable flag and applies from the next operation on —
+ * no restart, no config edit. `engineUserChosen` says whether the current mode
+ * is the user's own pick or still the configured default.
+ *
+ * The enable flag lives in dsh-browser-playwright-codex's shared module
+ * (lib/runtime-state.js, persisted to ~/.dsh/dsh-browser-playwright.state.json —
+ * the file name is intentionally stable across package renames so the user's
+ * saved switch survives). Importing it through the package export
+ * gives this plugin the SAME module instance as the playwright provider, so
+ * flipping the flag here triggers the provider's disable-subscription (tears
+ * down any open window) in-process, and every future browser acquire is
+ * rejected while disabled.
+ *
+ * The specifier below must match the provider package's package.json#name.
+ * 2026-09-30: the provider was renamed to *-codex; the old specifier stopped
+ * resolving (MODULE_NOT_FOUND) and the toggle failed to load, so the import and
+ * the node_modules link have to move together with the rename.
+ *
+ * CSRF: POST requires the custom `x-dsh-plugin: browser-toggle` header, the
+ * same pattern as dsh-local-switch.
+ */
+// Namespace import on purpose: this host half and the provider package are
+// separate plugins, and a profile that is still running an older provider build
+// would otherwise fail at link time with "does not provide an export named".
+// Missing helpers degrade to "unknown" instead of breaking the Settings page.
+import * as runtimeState from "./runtime-state.js";
+// The patch writer lives in its own dependency-free module so it can be tested
+// without a DSH host (a half-written patch layer would break every plugin load).
+import { homePatchPath, parseGatesBlock, writeGates } from "./gates-patch.js";
+import { readFileSync } from 'node:fs';
+const { getEnabled, setEnabled, getEffectiveEngine, setSnapshotEngine, isEngineUserChosen } = runtimeState;
+export const name = 'browser-toggle';
+export const inject = ['webServer'];
+const PREFIX = '/api/browser-playwright';
+const HEADER = 'x-dsh-plugin';
+/** Read the gates the tool family published, or undefined while unknown. */
+function readGates() {
+    if (typeof runtimeState.getGates !== 'function')
+        return undefined;
+    try {
+        const gates = runtimeState.getGates();
+        if (gates && typeof gates.allowEvaluate === 'boolean' && typeof gates.allowCdp === 'boolean')
+            return gates;
+    }
+    catch {
+        /* fall through to unknown */
+    }
+    return undefined;
+}
+/**
+ * Report the current managed block (what the user's own layer says). The switch
+ * shows the *effective* gates from readGates(); this is the file-level view used
+ * for diagnostics when the two disagree (i.e. the reload has not landed yet).
+ */
+function managedBlockGates() {
+    try {
+        const text = readFileSync(homePatchPath(), 'utf8');
+        return parseGatesBlock(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function sendJson(res, status, payload) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(JSON.stringify(payload));
+}
+async function readBody(req) {
+    const chunks = [];
+    try {
+        for await (const chunk of req)
+            chunks.push(chunk);
+    }
+    catch (error) {
+        return { ok: false, error: String(error?.message ?? error) };
+    }
+    return { ok: true, text: Buffer.concat(chunks).toString('utf8') };
+}
+export function apply(ctx) {
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/state`,
+        handler: async (req, res) => {
+            if (req.method !== 'GET')
+                return sendJson(res, 405, { error: { code: 'METHOD', message: 'GET only' } });
+            // Required even for a read: this exposes the deployment's switch state. A custom
+            // header forces a CORS preflight, which is what stops any other page in the
+            // browser from reading it off 127.0.0.1 (2026-10-16: only the POST routes had it).
+            if (req.headers[HEADER] !== 'browser-toggle')
+                return sendJson(res, 403, { error: { code: 'CSRF', message: 'missing plugin header' } });
+            const gates = readGates();
+            sendJson(res, 200, {
+                enabled: getEnabled(),
+                engine: getEffectiveEngine(),
+                engineUserChosen: isEngineUserChosen(),
+                // Effective values, published by the tool family itself. null = the
+                // provider build in this profile is too old to report them.
+                allowEvaluate: gates ? gates.allowEvaluate : null,
+                allowCdp: gates ? gates.allowCdp : null,
+                // What the user's own layer says right now. Differs from the above
+                // between a write and the live reload that applies it.
+                patchGates: managedBlockGates() ?? null,
+            });
+        },
+    }));
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/toggle`,
+        handler: async (req, res) => {
+            if (req.method !== 'POST')
+                return sendJson(res, 405, { error: { code: 'METHOD', message: 'POST only' } });
+            if (req.headers[HEADER] !== 'browser-toggle')
+                return sendJson(res, 403, { error: { code: 'CSRF', message: 'missing plugin header' } });
+            const body = await readBody(req);
+            if (!body.ok)
+                return sendJson(res, 400, { error: { code: 'BODY_READ', message: body.error } });
+            let payload;
+            try {
+                payload = JSON.parse(body.text || '{}');
+            }
+            catch {
+                return sendJson(res, 400, { error: { code: 'INVALID_JSON', message: 'body must be JSON' } });
+            }
+            if (typeof payload.enabled !== 'boolean')
+                return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`enabled` must be a boolean' } });
+            const changed = setEnabled(payload.enabled);
+            sendJson(res, 200, { enabled: getEnabled(), changed });
+        },
+    }));
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/engine`,
+        handler: async (req, res) => {
+            if (req.method !== 'POST')
+                return sendJson(res, 405, { error: { code: 'METHOD', message: 'POST only' } });
+            if (req.headers[HEADER] !== 'browser-toggle')
+                return sendJson(res, 403, { error: { code: 'CSRF', message: 'missing plugin header' } });
+            const body = await readBody(req);
+            if (!body.ok)
+                return sendJson(res, 400, { error: { code: 'BODY_READ', message: body.error } });
+            let payload;
+            try {
+                payload = JSON.parse(body.text || '{}');
+            }
+            catch {
+                return sendJson(res, 400, { error: { code: 'INVALID_JSON', message: 'body must be JSON' } });
+            }
+            if (payload.engine !== 'legacy' && payload.engine !== 'aria')
+                return sendJson(res, 400, {
+                    error: { code: 'INVALID_BODY', message: '`engine` must be "legacy" or "aria"' },
+                });
+            const changed = setSnapshotEngine(payload.engine);
+            sendJson(res, 200, { engine: getEffectiveEngine(), changed });
+        },
+    }));
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/gates`,
+        handler: async (req, res) => {
+            if (req.method !== 'POST')
+                return sendJson(res, 405, { error: { code: 'METHOD', message: 'POST only' } });
+            if (req.headers[HEADER] !== 'browser-toggle')
+                return sendJson(res, 403, { error: { code: 'CSRF', message: 'missing plugin header' } });
+            const body = await readBody(req);
+            if (!body.ok)
+                return sendJson(res, 400, { error: { code: 'BODY_READ', message: body.error } });
+            let payload;
+            try {
+                payload = JSON.parse(body.text || '{}');
+            }
+            catch {
+                return sendJson(res, 400, { error: { code: 'INVALID_JSON', message: 'body must be JSON' } });
+            }
+            if (typeof payload.allowEvaluate !== 'boolean' || typeof payload.allowCdp !== 'boolean')
+                return sendJson(res, 400, {
+                    error: {
+                        code: 'INVALID_BODY',
+                        message: '`allowEvaluate` and `allowCdp` must both be booleans',
+                    },
+                });
+            const before = readGates();
+            if (before && before.allowEvaluate === payload.allowEvaluate && before.allowCdp === payload.allowCdp)
+                return sendJson(res, 200, { ...before, changed: false, patch: null });
+            try {
+                const written = await writeGates(payload.allowEvaluate, payload.allowCdp);
+                // The effective values only move once the loader re-applies the tree
+                // (profile patchReload: live); report what was written, and let the
+                // panel's next /state poll show whether it took effect.
+                sendJson(res, 200, {
+                    allowEvaluate: written.allowEvaluate,
+                    allowCdp: written.allowCdp,
+                    changed: true,
+                    patch: written.patch,
+                });
+            }
+            catch (error) {
+                sendJson(res, 500, {
+                    error: { code: 'PATCH_WRITE', message: String(error?.message ?? error) },
+                });
+            }
+        },
+    }));
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/logins`,
+        handler: async (req, res) => {
+            if (req.method !== 'GET')
+                return sendJson(res, 405, { error: { code: 'METHOD', message: 'GET only' } });
+            // The CSRF header is mandatory here, and this route is the reason the rule exists:
+            // the payload is a list of the sites this browser is signed in to. A custom header
+            // forces a preflight, so no other page in the browser can read it off 127.0.0.1.
+            if (req.headers[HEADER] !== 'browser-toggle')
+                return sendJson(res, 403, { error: { code: 'CSRF', message: 'missing plugin header' } });
+            // Read-only, display-only: the provider publishes this summary (counts and domain
+            // names, never cookie values or names). null = nothing published yet, or the
+            // provider build in this profile is too old to publish it.
+            let logins = null;
+            if (typeof runtimeState.getLoginSites === 'function') {
+                try {
+                    logins = runtimeState.getLoginSites() ?? null;
+                }
+                catch {
+                    logins = null;
+                }
+            }
+            sendJson(res, 200, { logins });
+        },
+    }));
+}
+export default { name, inject, apply };

package/lib/snapshot-render.d.ts

@@ -4,6 +4,18 @@
  * @module dsh-browser-playwright-codex/snapshot-render
  */
 import type { BrowserNode, BrowserSnapshot, SnapshotDiff } from './types.ts';
+/** Default cap for a rendered href, in characters. */
+export declare const MAX_HREF_LENGTH = 160;
+/**
+ * Trim a href for display: drop analytics parameters and clip the whole thing.
+ * The snapshot's refs remain the interaction handle, so this only affects what
+ * the model reads, never what a click does.
+ *
+ * @param href - the raw href from the accessibility tree
+ * @param maxLength - display budget in characters
+ * @returns the shortened href
+ */
+export declare function trimUrlForDisplay(href: string, maxLength?: number): string;
 /**
  * Render a node tree as indented lines, one element per line.
  * @param nodes - the snapshot's root nodes.

package/lib/snapshot-render.js

@@ -3,8 +3,106 @@
  * functions run on live calls and on session replay alike.
  * @module dsh-browser-playwright-codex/snapshot-render
  */
+/**
+ * Query parameters that only feed analytics or the site's own ranking pipeline.
+ * They make a rendered href several times longer than the link it names and the
+ * model never needs them: the ref (not the URL) is what clicks.
+ */
+const TRACKING_PARAMS = new Set([
+    'gclid',
+    'dclid',
+    'fbclid',
+    'msclkid',
+    'yclid',
+    'spm',
+    'scm',
+    'share_token',
+    'rsv_spt',
+    'rsv_iqid',
+    'rsv_bp',
+    'rsv_idx',
+    'rsv_enter',
+    'rsv_pq',
+    'rsv_t',
+    'rsv_dl',
+    'rsv_sug1',
+    'rsv_sug2',
+    'rsv_sug3',
+    'rsv_sug4',
+    'rsv_sug5',
+    'rsv_sug6',
+    'rsv_sug7',
+    'rsv_sug8',
+    'rsv_sug9',
+    'rsv_sug10',
+    'sa',
+    'usm',
+    'rqid',
+    'rsf',
+]);
+/** Default cap for a rendered href, in characters. */
+export const MAX_HREF_LENGTH = 160;
+/** Clip a string to a display budget, marking the cut. */
+function clip(value, maxLength) {
+    return value.length <= maxLength ? value : value.slice(0, maxLength - 1) + '…';
+}
+/**
+ * Trim a href for display: drop analytics parameters and clip the whole thing.
+ * The snapshot's refs remain the interaction handle, so this only affects what
+ * the model reads, never what a click does.
+ *
+ * @param href - the raw href from the accessibility tree
+ * @param maxLength - display budget in characters
+ * @returns the shortened href
+ */
+export function trimUrlForDisplay(href, maxLength = MAX_HREF_LENGTH) {
+    const hashAt = href.indexOf('#');
+    const hash = hashAt >= 0 ? href.slice(hashAt) : '';
+    const head = hashAt >= 0 ? href.slice(0, hashAt) : href;
+    const queryAt = head.indexOf('?');
+    if (queryAt < 0)
+        return clip(head + hash, maxLength);
+    const base = head.slice(0, queryAt);
+    const kept = head
+        .slice(queryAt + 1)
+        .split('&')
+        .filter((pair) => pair !== '')
+        .filter((pair) => {
+        let key = pair.split('=')[0] ?? '';
+        try {
+            key = decodeURIComponent(key);
+        }
+        catch {
+            /* keep the raw key: an undecodable one is not a known tracker */
+        }
+        key = key.toLowerCase();
+        return !key.startsWith('utm_') && !TRACKING_PARAMS.has(key);
+    });
+    return clip(base + (kept.length > 0 ? '?' + kept.join('&') : '') + hash, maxLength);
+}
+/**
+ * A wrapper element with no name, ref, state or link of its own. Keeping it
+ * would push every real element one level deeper and repeat the word "generic"
+ * for every <div> on the page; dropping it keeps the structure the model needs
+ * (nesting of things that have names) without the noise.
+ */
+function isTransparentWrapper(node) {
+    return (node.role === 'generic' &&
+        node.name === '' &&
+        node.ref === undefined &&
+        node.href === undefined &&
+        node.level === undefined &&
+        node.checked === undefined &&
+        node.selected === undefined &&
+        node.disabled === undefined);
+}
 /** Render one node line into the accumulating line list. */
 function renderNode(node, depth, lines) {
+    if (isTransparentWrapper(node)) {
+        for (const child of node.children)
+            renderNode(child, depth, lines);
+        return;
+    }
     const indent = '  '.repeat(depth);
     let line = indent + '- ' + node.role;
     if (node.name !== '')
@@ -23,7 +121,7 @@ function renderNode(node, depth, lines) {
     if (flags.length > 0)
         line += ' [' + flags.join(', ') + ']';
     if (node.href !== undefined)
-        line += ' -> ' + node.href;
+        line += ' -> ' + trimUrlForDisplay(node.href);
     lines.push(line);
     for (const child of node.children)
         renderNode(child, depth + 1, lines);

package/lib/tool-render.js

@@ -1,4 +1,4 @@
-import { CHALLENGE_NOTE, detectChallenge } from "./challenge.js";
+import { CHALLENGE_NOTE, detectChallenge, detectSilentPage } from "./challenge.js";
 import { renderSnapshot, renderSnapshotDiff } from "./snapshot-render.js";
 /**
  * Render one diagnostics payload as one line per entry. Diagnostics are read when
@@ -57,9 +57,32 @@ export function renderDiagnostics(kind, value) {
 }
 /** Project a provider snapshot into its canonical tool value. */
 export function snapshotValue(snapshot) {
-    const challenge = detectChallenge(snapshot);
+    // The ref count travels with the snapshot on purpose: the wording tier needs it
+    // to tell a real wall (nothing to click) from a results page whose title merely
+    // contains the phrase. Measured on 百度: 0 refs on the challenge, 57/81 on the
+    // search pages titled "安全验证_百度搜索" / "滑块验证_百度搜索".
+    const challenge = detectChallenge({
+        url: snapshot.url,
+        title: snapshot.title,
+        nodes: snapshot.nodes,
+        refs: snapshot.totalRefs,
+        ...(snapshot.response !== undefined ? { response: snapshot.response } : {}),
+    });
     const tree = renderSnapshot(snapshot);
     const notes = [];
+    // The HTTP status was captured for challenge detection but never shown, so a
+    // 404/500 error page reached the model looking like an ordinary page — measured
+    // 2026-10-17 on a real MDN 404: status 404, 35 refs, and nothing in the result
+    // said so. Suppressed when a challenge was identified, because that note
+    // already names the reason.
+    const status = snapshot.response?.status;
+    if (challenge === null && status !== undefined && (status < 200 || status >= 300)) {
+        notes.push('[http ' +
+            String(status) +
+            '] the server answered ' +
+            String(status) +
+            ' for this document, so what follows may be an error page or an interception page rather than the content you asked for.');
+    }
     const dialog = snapshot.dialogNote;
     if (dialog !== undefined && dialog !== '')
         notes.push(dialog);
@@ -80,6 +103,18 @@ export function snapshotValue(snapshot) {
     const stall = snapshot.stallNote;
     if (challenge === null && stall !== undefined && stall !== '')
         notes.push(stall);
+    // The backstop above needs an action to compare before and after; a page with
+    // nothing to click never gets one, so the emptiest wall-like pages used to say
+    // nothing at all. Only on a successful status: a 4xx/5xx already has its own line.
+    const healthyStatus = status === undefined || (status >= 200 && status < 300);
+    // A parked dialog means the page is fine, it is the dialog that blocks us: the
+    // dialog note already says what to do, and adding "nothing here" contradicts it.
+    const dialogPending = snapshot.dialogNote !== undefined && snapshot.dialogNote !== '';
+    if (challenge === null && healthyStatus && !dialogPending) {
+        const silent = detectSilentPage({ refs: snapshot.totalRefs, nodes: snapshot.nodes, title: snapshot.title });
+        if (silent !== null)
+            notes.push(silent);
+    }
     const head = notes.length > 0 ? notes.join('\n\n') + '\n\n' : '';
     // Incremental diff rides along when the provider computed one (snapshot.diff).
     const diffBlock = snapshot.diff !== undefined ? '\n\n' + renderSnapshotDiff(snapshot.diff) : '';

package/lib/tool-types.d.ts

@@ -53,6 +53,12 @@ export interface ChallengeSnapshot {
     readonly title?: string;
     readonly url?: string;
     readonly nodes?: readonly ChallengeNode[];
+    /**
+     * Actionable-element count. The wording tier uses it to tell a challenge page
+     * (nothing to click) from an ordinary page whose *title* merely contains the
+     * phrase — searching Baidu for "安全验证" produces exactly that false positive.
+     */
+    readonly refs?: number;
     /** Main document response metadata; absent when no navigation response was seen. */
     readonly response?: DocumentResponse;
 }

package/lib/tool.d.ts

@@ -31,6 +31,12 @@ export interface ToolConfig {
      * its schema would sit in the system prompt on every turn for nothing.
      */
     registerDisabledTools: boolean;
+    /**
+     * Register the two diagnostics tools (console messages, network requests).
+     * Defaults to false: they exist to debug a failed run, and their schemas
+     * would otherwise sit in the system prompt on every turn.
+     */
+    diagnostics: boolean;
     /** Upper bound for browser_wait in milliseconds. */
     maxWaitMs: number;
     /** Default value of the snapshot tool's interactiveOnly flag. */