dsh-browser-playwright-codex 0.8.2 → 0.9.0

package/lib/script-store.js

@@ -0,0 +1,104 @@
+/**
+ * Where saved scripts live: one JSON file per script under `~/.dsh/browser-scripts`.
+ *
+ * Kept deliberately dumb — read, write, list — because the interesting rules
+ * (what a step may contain, what may run) live in `script-steps.ts` and
+ * `script-runner.ts`. A store that also validated would be the second place to
+ * change when the step vocabulary grows.
+ *
+ * Names are restricted to a flat, boring charset and are never joined onto a
+ * path unvalidated: a script name reaches `path.join`, so `../` in a name would
+ * otherwise write anywhere the process can reach.
+ * @module dsh-browser-playwright-codex/script-store
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ScriptStepError, parseScriptSteps } from "./script-steps.js";
+/** A script name: letters, digits, dash and underscore, starting with a letter or digit. */
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** Directory holding the saved scripts. `DSH_BROWSER_SCRIPTS_DIR` overrides it (tests). */
+export function scriptsDir() {
+    const override = process.env.DSH_BROWSER_SCRIPTS_DIR;
+    if (override !== undefined && override !== '')
+        return override;
+    return path.join(os.homedir(), '.dsh', 'browser-scripts');
+}
+/** Validate a script name, returning the trimmed value. */
+export function validName(raw) {
+    const name = typeof raw === 'string' ? raw.trim() : '';
+    if (!NAME_RE.test(name)) {
+        throw new ScriptStepError(1, 'script name must be 1-64 characters of letters, digits, dash or underscore — got ' +
+            (name === '' ? '(empty)' : '"' + name + '"'));
+    }
+    return name;
+}
+/** Path of one script file. */
+function scriptPath(name) {
+    return path.join(scriptsDir(), name + '.json');
+}
+/**
+ * Write a script, replacing any file of the same name.
+ *
+ * @param name - Validated script name.
+ * @param steps - Steps already validated by `parseScriptSteps`.
+ * @returns The file path and how many steps were stored.
+ */
+export function saveScript(name, steps) {
+    const file = scriptPath(name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const body = JSON.stringify({ name, savedAt: new Date().toISOString(), steps }, null, 2);
+    // Write next to the target, then rename: a half-written file left by a crash
+    // would otherwise load as a script that silently lost its last steps.
+    const tmp = file + '.tmp';
+    fs.writeFileSync(tmp, body, 'utf8');
+    fs.renameSync(tmp, file);
+    return { path: file, steps: steps.length };
+}
+/**
+ * Read one script.
+ *
+ * @param name - Validated script name.
+ * @param maxSteps - Cap applied to the file's steps, so an edited file cannot
+ *   smuggle in a longer list than the tool accepts.
+ */
+export function loadScript(name, maxSteps) {
+    // Validated here as well as at the tool boundary: this is exported, and a
+    // name that reaches `path.join` unvalidated is the one way out of the folder.
+    const safe = validName(name);
+    const file = scriptPath(safe);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        throw new ScriptStepError(1, 'no saved script named "' + safe + '"; save one with the save tool, or pass steps inline');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ScriptStepError(1, 'the saved script "' + safe + '" is not valid JSON; save it again');
+    }
+    const record = parsed;
+    const steps = parseScriptSteps(record.steps, maxSteps);
+    return {
+        name: safe,
+        savedAt: typeof record.savedAt === 'string' ? record.savedAt : '',
+        steps,
+    };
+}
+/** Names of the saved scripts, sorted. Missing directory means none yet. */
+export function listScripts() {
+    try {
+        return fs
+            .readdirSync(scriptsDir())
+            .filter((entry) => entry.endsWith('.json'))
+            .map((entry) => entry.slice(0, -'.json'.length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}

package/lib/settings-card.js

@@ -62,7 +62,8 @@
 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 { homePatchPath, parseBrowserBlockProxy, parseGatesBlock, writeGates, writeProxy } from "./gates-patch.js";
+import { normalizeProxy } from "./proxy.js";
 import { onPersistPlayedChanged, resetPlayed } from "./swarm-intro.js";
 import { readFileSync } from 'node:fs';
 import { clean, isTargetId, resolvePaths, scan } from "./cache-clean.js";
@@ -90,6 +91,14 @@ function readGates() {
  * 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 managedBlockProxy() {
+    try {
+        return parseBrowserBlockProxy(readFileSync(homePatchPath(), 'utf8'));
+    }
+    catch {
+        return '';
+    }
+}
 function managedBlockGates() {
     try {
         const text = readFileSync(homePatchPath(), 'utf8');
@@ -391,6 +400,8 @@ export function apply(ctx) {
                 // 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,
+                // launch.proxy（设置页的「代理」输入框）。空 = 直连。
+                proxy: managedBlockProxy(),
             });
         },
     }));
@@ -523,5 +534,55 @@ export function apply(ctx) {
             sendJson(res, 200, { logins });
         },
     }));
+    // ---- launch.proxy：设置页里的「代理」输入框 ----
+    // 只改托管块里 `playwright.launch.proxy` 这一行（与三个闸门同一个模式），
+    // 其它键逐字节不动；空字符串 = 删掉那一行 = 直连。
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: `${PREFIX}/proxy`,
+        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.proxy !== 'string')
+                return sendJson(res, 400, { error: { code: 'INVALID_BODY', message: '`proxy` must be a string' } });
+            // 校验直接用 proxy.ts 的同一份实现：非法地址当场报错，文件一个字节不动。
+            let server = '';
+            try {
+                const normalized = normalizeProxy(payload.proxy);
+                server = normalized === undefined ? '' : normalized.server;
+            }
+            catch (error) {
+                return sendJson(res, 400, {
+                    error: { code: 'INVALID_PROXY', message: String(error?.message ?? error) },
+                });
+            }
+            try {
+                const written = await writeProxy(server);
+                sendJson(res, 200, {
+                    proxy: written.proxy,
+                    patch: written.patch,
+                    // 代理是浏览器启动参数：插件在加载时读配置，所以下次启动 DSH 才生效。
+                    appliedOn: 'restart',
+                });
+            }
+            catch (error) {
+                sendJson(res, 500, {
+                    error: { code: 'PATCH_WRITE', message: String(error?.message ?? error) },
+                });
+            }
+        },
+    }));
 }
 export default { name, inject, apply };

package/lib/tool.js

@@ -10,6 +10,9 @@ import { SCREENSHOT_SCHEMA, SNAPSHOT_SCHEMA, TABS_SCHEMA } from "./tool-schemas.
 import { parseJsonText, extractionPrompt } from "./extract.js";
 import { detectChallenge } from "./challenge.js";
 import { describeWait, normalizeWaitCondition } from "./wait-conditions.js";
+import { MAX_SCRIPT_STEPS, ScriptStepError, parseScriptSteps } from "./script-steps.js";
+import { runScript } from "./script-runner.js";
+import { listScripts, loadScript, saveScript, validName } from "./script-store.js";
 import { renderDiagnostics, renderScreenshotValue, renderSnapshotValue, renderTabsValue, snapshotValue, } from "./tool-render.js";
 export { detectChallenge };
 /** Cordis plugin name used by loader diagnostics. */
@@ -692,6 +695,146 @@ export function apply(ctx, config) {
             },
         }));
     }
+    ctx.tools.register(defineTool({
+        name: p('run_script'),
+        description: 'Run several browser steps in ONE call — the deterministic repeat of a flow the model already worked out. ' +
+            'Pass either a saved script by name or the steps inline. Steps: navigate, snapshot, click, fill, press, ' +
+            'hover, scroll, back, forward, wait. ' +
+            'A step names its element by `ref` (from the snapshot the previous step returned) or by a visible `text` label ' +
+            '(resolved against the freshest snapshot right before the action, so a label survives a re-render that would stale a ref). ' +
+            'IRON RULE: the run stops at the FIRST failing step and returns its index, its action, the failure text and the last good snapshot — ' +
+            'take over from there with the single-step tools; do NOT replay the whole script blind. ' +
+            'Use it for flows whose shape is known (login → open page → fill form → read result), not to explore: ' +
+            'explore with the single tools first, then save what worked. ' +
+            'Every step still passes the same URL policy, ref validation and credential refusal as its own tool.',
+        parameters: {
+            name: {
+                type: 'string',
+                description: 'Saved script to run (see ' + p('save_script') + '). Omit when passing `steps` inline.',
+            },
+            steps: {
+                type: 'array',
+                items: { type: 'object', additionalProperties: true },
+                description: 'Inline steps, used when `name` is omitted. Each: {action:"navigate",url} | {action:"snapshot"} | ' +
+                    '{action:"click",ref?|text?} | {action:"fill",ref?|text?,value} | {action:"press",ref?|text?,key} | ' +
+                    '{action:"hover",ref?|text?} | {action:"scroll",direction,amount?,ref?|text?} | {action:"back"} | ' +
+                    '{action:"forward"} | {action:"wait",ms?|text?|selector?|networkIdle?|urlContains?}. ' +
+                    'A step naming its element by `text` is retried once against a fresh snapshot before the run fails; ' +
+                    'a step naming it by `ref` is not (a ref belongs to the document that produced it). ' +
+                    'Max ' +
+                    String(MAX_SCRIPT_STEPS) +
+                    ' steps.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => {
+                const outcome = value;
+                const lines = [];
+                lines.push(String(outcome.ran) + '/' + String(outcome.total) + ' steps ran');
+                for (const entry of outcome.outcomes) {
+                    lines.push((entry.ok ? '✔ ' : '✖ ') +
+                        String(entry.index) +
+                        '. ' +
+                        entry.step +
+                        (entry.note === undefined ? '' : ' — ' + entry.note));
+                }
+                if (outcome.failedAt !== undefined) {
+                    lines.push('Stopped at step ' +
+                        String(outcome.failedAt) +
+                        ' (' +
+                        String(outcome.failedAction) +
+                        '): ' +
+                        String(outcome.failure) +
+                        (outcome.failureCode === undefined ? '' : ' [' + outcome.failureCode + ']'));
+                    lines.push('Fix that step and run again, or take over with the single-step tools from the snapshot below.');
+                }
+                if (outcome.snapshot !== undefined) {
+                    lines.push('Page: ' + outcome.snapshot.title + ' — ' + outcome.snapshot.url);
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(args, exec) {
+            let steps;
+            try {
+                if (args.steps !== undefined && String(args.name ?? '').trim() !== '') {
+                    throw new ScriptStepError(1, 'pass steps, or a saved name, not both');
+                }
+                steps =
+                    args.steps !== undefined
+                        ? parseScriptSteps(args.steps, MAX_SCRIPT_STEPS)
+                        : loadScript(validName(args.name), MAX_SCRIPT_STEPS).steps;
+            }
+            catch (error) {
+                const message = String(error.message ?? error);
+                throw new BrowserError('SCRIPT_INVALID', message);
+            }
+            const session = await acquire(exec);
+            const outcome = await runScript(session, steps, { signal: exec.signal });
+            return outcome;
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: p('save_script'),
+        description: 'Save a working step list under a name, so a later run costs one call instead of one call per action. ' +
+            'Save what actually worked in this session — the flow you just did with the single tools — not what you hope works. ' +
+            'Prefer `text` labels over refs in a saved script: refs belong to one snapshot and go stale on the next page load, ' +
+            'while a label is resolved fresh on every run. ' +
+            'Refuses to overwrite an existing name unless `overwrite` is true. ' +
+            'Scripts live in ~/.dsh/browser-scripts (one JSON file each) and never leave this machine.',
+        parameters: {
+            name: {
+                type: 'string',
+                required: true,
+                description: 'Script name: 1-64 letters, digits, dash or underscore (e.g. "login-and-read-orders").',
+            },
+            steps: {
+                type: 'array',
+                items: { type: 'object', additionalProperties: true },
+                required: true,
+                description: 'Steps to save, same shape as ' + p('run_script') + ' accepts. Max ' + String(MAX_SCRIPT_STEPS) + '.',
+            },
+            overwrite: { type: 'boolean', description: 'Replace an existing script of the same name. Defaults to false.' },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => {
+                const saved = value;
+                return [
+                    {
+                        type: 'text',
+                        text: 'Saved "' +
+                            saved.name +
+                            '" (' +
+                            String(saved.steps) +
+                            ' steps) → ' +
+                            saved.path +
+                            '. Run it with ' +
+                            p('run_script') +
+                            '({ name: "' +
+                            saved.name +
+                            '" }).',
+                    },
+                ];
+            },
+        },
+        async execute(args) {
+            try {
+                const name = validName(args.name);
+                if (args.overwrite !== true && listScripts().includes(name)) {
+                    throw new ScriptStepError(1, 'a script named "' + name + '" already exists; pass overwrite:true to replace it');
+                }
+                const steps = parseScriptSteps(args.steps, MAX_SCRIPT_STEPS);
+                const written = saveScript(name, steps);
+                return { name, path: written.path, steps: written.steps };
+            }
+            catch (error) {
+                const message = String(error.message ?? error);
+                throw new BrowserError('SCRIPT_INVALID', message);
+            }
+        },
+    }));
     ctx.tools.register(defineTool({
         name: p('close'),
         description: "Release this session's browser window. Persistent mode shares one window, so it closes only when the last session releases it; the profile keeps login state either way, so the next browser call reopens it still signed in (reset the profile to clear cookies).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Browser automation for DeepSeek Harness, one plugin: fill in forms, scrape lists and work across tabs in real pages, using the logins you already have. Runs in a visible window that stays quiet when minimised; native dialogs are parked instead of confirmed, CAPTCHA pages are flagged with a note that says stop and hand the page back, password / one-time-code / card fields are refused by browser_fill, and the Settings card (enable/disable, page-reading mode, capability gates) now lives inside this package.",
   "license": "MIT",
   "type": "module",