dsh-browser-playwright-codex 0.8.2 → 0.9.0

package/lib/gates-patch.js

@@ -323,3 +323,152 @@ export async function writeGates(allowEvaluate, allowCdp, diagnostics, env = pro
     }
     return { patch: file, allowEvaluate, allowCdp, diagnostics };
 }
+/** 在块的文本里找 `launch:` 与它的 `proxy:` 子行。认不出结构就抛错（拒绝写入）。 */
+function findLaunchSection(lines) {
+    let launchAt = -1;
+    let launchIndent = '';
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = /^(\s*)launch\s*:\s*(#.*)?$/.exec(lines[i] ?? '');
+        if (m !== null) {
+            launchAt = i;
+            launchIndent = m[1] ?? '';
+            break;
+        }
+    }
+    if (launchAt === -1) {
+        throw new Error('the managed block has no `playwright.launch:` section, so launch.proxy cannot be edited safely; ' +
+            'nothing was written. Fix the block by hand (or remove it and save a gate once to rebuild it).');
+    }
+    const baseIndent = launchIndent.length;
+    let childIndent = '';
+    let proxy;
+    for (let i = launchAt + 1; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        const indent = (/^\s*/.exec(line)?.[0] ?? '').length;
+        if (indent <= baseIndent)
+            break; // 出了 launch 这一节
+        if (trimmed.startsWith('#'))
+            continue;
+        if (childIndent === '')
+            childIndent = ' '.repeat(indent);
+        const p = /^(\s*)proxy\s*:/.exec(line);
+        if (p !== null)
+            proxy = { at: i, indent: p[1] ?? '' };
+    }
+    return {
+        at: launchAt,
+        indent: baseIndent,
+        childIndent: childIndent === '' ? ' '.repeat(baseIndent + 2) : childIndent,
+        ...(proxy === undefined ? {} : { proxy }),
+    };
+}
+/**
+ * 改写块里的 proxy 行：有就改、没有就插、空字符串就删。其它行逐字节保留。
+ *
+ * @param body - 托管块全文（含标记）
+ * @param proxy - 已经过 normalizeProxy 校验的地址；'' 表示删掉这一行
+ * @returns 改好的块
+ */
+export function patchBlockProxy(body, proxy) {
+    const nl = body.includes('\r\n') ? '\r\n' : '\n';
+    const lines = body.split(/\r?\n/);
+    const section = findLaunchSection(lines);
+    const value = proxy.trim();
+    const rendered = section.childIndent + 'proxy: ' + JSON.stringify(value);
+    if (section.proxy !== undefined) {
+        if (value === '')
+            lines.splice(section.proxy.at, 1);
+        else
+            lines[section.proxy.at] = rendered;
+        return lines.join(nl);
+    }
+    if (value === '')
+        return lines.join(nl); // 本来就没有，删空是幂等的
+    lines.splice(section.at + 1, 0, rendered);
+    return lines.join(nl);
+}
+/** 读托管块里的 proxy 值；没有就是 ''（= 直连）。 */
+export function parseBrowserBlockProxy(text) {
+    const found = findBlock(text);
+    if (found === undefined)
+        return '';
+    const body = text.slice(found.start, found.after);
+    const lines = body.split(/\r?\n/);
+    let section;
+    try {
+        section = findLaunchSection(lines);
+    }
+    catch {
+        return '';
+    }
+    if (section?.proxy === undefined)
+        return '';
+    const raw = (lines[section.proxy.at] ?? '').replace(/^\s*proxy\s*:\s*/, '');
+    const withoutComment = raw.replace(/\s+#.*$/, '').trim();
+    if (withoutComment === '')
+        return '';
+    if ((withoutComment.startsWith('"') && withoutComment.endsWith('"')) ||
+        (withoutComment.startsWith("'") && withoutComment.endsWith("'"))) {
+        return withoutComment.slice(1, -1);
+    }
+    return withoutComment;
+}
+/**
+ * 把 proxy 合并进文件内容：没有托管块就先按模板建一个，再改这一行。
+ *
+ * @param original - 原文件内容
+ * @param proxy - 已校验的地址；'' = 删掉
+ * @returns 新文件内容
+ */
+export function mergeBrowserBlockProxy(original, proxy) {
+    const value = proxy.trim();
+    let base = original;
+    let found = findBlock(base);
+    if (found === undefined) {
+        base = (base === '' || base.endsWith('\n') ? base : base + '\n') + '\n' + renderBrowserBlock(false, false, false);
+        found = findBlock(base);
+    }
+    if (found === undefined)
+        throw new Error('could not create the managed block; nothing was written');
+    const edited = patchBlockProxy(base.slice(found.start, found.after), value);
+    if (parseBrowserBlockProxy(edited) !== value) {
+        throw new Error('proxy line self-check failed; nothing was written');
+    }
+    return base.slice(0, found.start) + edited + base.slice(found.after);
+}
+/**
+ * 写 proxy：备份 → 原子替换 → 读回校验；校验失败恢复原文件。
+ *
+ * @param proxy - 已校验的地址；'' 表示删掉这一行（= 直连）
+ * @param env - 环境（测试用 DSH_HOME 覆盖）
+ * @returns 写到的文件与现在的值
+ */
+export async function writeProxy(proxy, env = process.env) {
+    const file = homePatchPath(env);
+    const value = proxy.trim();
+    let original = '';
+    try {
+        original = await readFile(file, 'utf8');
+    }
+    catch {
+        original = '';
+    }
+    const next = mergeBrowserBlockProxy(original, value);
+    if (original !== '')
+        await copyFile(file, file + '.bak-browser-toggle').catch(() => { });
+    const tmp = file + '.tmp-browser-toggle';
+    await writeFile(tmp, next, 'utf8');
+    await rename(tmp, file);
+    const check = await readFile(file, 'utf8');
+    if (parseBrowserBlockProxy(check) !== value) {
+        if (original !== '') {
+            await writeFile(file, original, 'utf8');
+            throw new Error('proxy self-check failed after write; previous content restored');
+        }
+        throw new Error('proxy self-check failed after write');
+    }
+    return { patch: file, proxy: value };
+}

package/lib/provider.d.ts

@@ -35,6 +35,12 @@ export declare class PlaywrightProvider {
     browser: Browser | undefined;
     /** Window mode the live process was launched with (undefined = nothing running). */
     launchedHeadless: boolean | undefined;
+    /**
+     * True when this host refused the renderer sandbox and the browser had to be
+     * launched without it. Kept as state rather than a log line so a later
+     * "why is Chrome showing that warning bar" question has an answer on disk.
+     */
+    sandboxFallback: boolean;
     /** Persistent-mode shared profile-backed context (the personal window). */
     context: BrowserContext | undefined;
     entries: Map<string, OwnerEntry>;

package/lib/provider.js

@@ -17,6 +17,7 @@ import { swarmBootScript } from "./swarm-curtain.js";
 import { forgetOnBrowserClose } from "./swarm-intro.js";
 import { isWindowMinimized } from "./window-focus.js";
 import { installHostGuard } from "./navigation-guard.js";
+import { normalizeProxy } from "./proxy.js";
 export class PlaywrightProvider {
     config;
     id = 'playwright';
@@ -24,6 +25,12 @@ export class PlaywrightProvider {
     browser;
     /** Window mode the live process was launched with (undefined = nothing running). */
     launchedHeadless = undefined;
+    /**
+     * True when this host refused the renderer sandbox and the browser had to be
+     * launched without it. Kept as state rather than a log line so a later
+     * "why is Chrome showing that warning bar" question has an answer on disk.
+     */
+    sandboxFallback = false;
     /** Persistent-mode shared profile-backed context (the personal window). */
     context;
     entries = new Map();
@@ -62,6 +69,9 @@ export class PlaywrightProvider {
     blockedNavigation = undefined;
     constructor(config) {
         this.config = config;
+        // Fail at load time, not at launch time: a bad proxy address must produce the one
+        // message that explains it (src/proxy.ts), not a wrapped "tried channel …" failure.
+        normalizeProxy(config.launch.proxy);
         // Tell the settings card which page-reading mode this deployment was
         // configured with, so it can show "当前：X（默认）" truthfully instead of
         // assuming the built-in default.

package/lib/proxy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Proxy support for the browser launch (2026-11-12).
+ *
+ * The plugin starts its own Chromium-family browser, so a proxy has to go into the
+ * **launch** options (`launchOptions.proxy`) — request headers cannot route a whole
+ * browser. Measured here: Wikipedia through a proxy answered in 4.4 s; direct it timed
+ * out at 15 s, which is what every proxied site looked like before this.
+ *
+ * Three rules, each with a reason:
+ *
+ * 1. **Empty means direct.** No configured proxy keeps today's behaviour exactly.
+ * 2. **`bypass` always includes the local addresses.** Without it the plugin's own
+ *    `127.0.0.1` pages (verify, the MiniWoB sweep, any local server) would be pushed
+ *    through the proxy and fail. Playwright passes `bypass` straight to Chromium's
+ *    proxy bypass list.
+ * 3. **A bad address is an error, never a silent fallback to direct.** Quietly going
+ *    direct would look like "the site is down" and send the user debugging the wrong thing.
+ *
+ * Authentication is deliberately **not** supported in this version: a password in the
+ * config would be stored in plain text in the user's `cordis.patch.yml`, and Playwright
+ * refuses SOCKS5 authentication outright (`Browser does not support socks5 proxy
+ * authentication`). Rather than ship a plaintext password path, credentials are rejected
+ * here with a message that says why.
+ *
+ * @module dsh-browser-playwright-codex/proxy
+ */
+/** The shape Playwright accepts in `launchOptions.proxy`. */
+export interface LaunchProxy {
+    /** `http://host:port`, `https://host:port` or `socks5://host:port`. */
+    server: string;
+    /** Local addresses bypass the proxy, so the plugin's own local pages keep working. */
+    bypass: string;
+}
+/** Hosts that must never be proxied (the plugin's own local pages live there). */
+export declare const PROXY_BYPASS = "localhost,127.0.0.1";
+/**
+ * Turn a configured proxy address into Playwright's proxy object.
+ *
+ * Accepted shapes: `host:port` (treated as HTTP, like Playwright does), `http://host:port`,
+ * `https://host:port`, `socks5://host:port`. The port is required and must be 1–65535.
+ *
+ * @param raw - the configured value; empty/undefined means "connect directly"
+ * @returns the proxy settings (server + local bypass), or undefined for a direct connection
+ * @throws Error with an actionable message when the address cannot be used
+ */
+export declare function normalizeProxy(raw: string | undefined | null): LaunchProxy | undefined;
+/**
+ * The spread-in fragment for Playwright's launch options: `{}` when direct,
+ * `{ proxy: … }` when configured. Every launch path uses this so they cannot drift.
+ *
+ * @param raw - the configured proxy value
+ * @returns an object to spread into the launch options
+ */
+export declare function proxyLaunchOption(raw: string | undefined | null): {
+    proxy?: LaunchProxy;
+};

package/lib/proxy.js

@@ -0,0 +1,131 @@
+/**
+ * Proxy support for the browser launch (2026-11-12).
+ *
+ * The plugin starts its own Chromium-family browser, so a proxy has to go into the
+ * **launch** options (`launchOptions.proxy`) — request headers cannot route a whole
+ * browser. Measured here: Wikipedia through a proxy answered in 4.4 s; direct it timed
+ * out at 15 s, which is what every proxied site looked like before this.
+ *
+ * Three rules, each with a reason:
+ *
+ * 1. **Empty means direct.** No configured proxy keeps today's behaviour exactly.
+ * 2. **`bypass` always includes the local addresses.** Without it the plugin's own
+ *    `127.0.0.1` pages (verify, the MiniWoB sweep, any local server) would be pushed
+ *    through the proxy and fail. Playwright passes `bypass` straight to Chromium's
+ *    proxy bypass list.
+ * 3. **A bad address is an error, never a silent fallback to direct.** Quietly going
+ *    direct would look like "the site is down" and send the user debugging the wrong thing.
+ *
+ * Authentication is deliberately **not** supported in this version: a password in the
+ * config would be stored in plain text in the user's `cordis.patch.yml`, and Playwright
+ * refuses SOCKS5 authentication outright (`Browser does not support socks5 proxy
+ * authentication`). Rather than ship a plaintext password path, credentials are rejected
+ * here with a message that says why.
+ *
+ * @module dsh-browser-playwright-codex/proxy
+ */
+const ALLOWED_SCHEMES = new Set(['http:', 'https:', 'socks5:']);
+/** Hosts that must never be proxied (the plugin's own local pages live there). */
+export const PROXY_BYPASS = 'localhost,127.0.0.1';
+/** One clear sentence for every rejection; the value is echoed so a typo is visible. */
+function reject(value, why) {
+    throw new Error('launch.proxy is not a usable proxy address (' +
+        why +
+        '): "' +
+        value +
+        '". ' +
+        'Write it as scheme://host:port (or just host:port) — e.g. http://proxy.example:8080, ' +
+        'https://proxy.example:8443 or socks5://proxy.example:1080. ' +
+        'Leave it empty to connect directly. Authenticated proxies are not supported in this version.');
+}
+/**
+ * Turn a configured proxy address into Playwright's proxy object.
+ *
+ * Accepted shapes: `host:port` (treated as HTTP, like Playwright does), `http://host:port`,
+ * `https://host:port`, `socks5://host:port`. The port is required and must be 1–65535.
+ *
+ * @param raw - the configured value; empty/undefined means "connect directly"
+ * @returns the proxy settings (server + local bypass), or undefined for a direct connection
+ * @throws Error with an actionable message when the address cannot be used
+ */
+export function normalizeProxy(raw) {
+    const value = (raw ?? '').trim();
+    if (value === '')
+        return undefined;
+    // Credentials would have to live in plain text in the user's patch file, and SOCKS5
+    // authentication is not supported by the browser anyway — refuse before launch.
+    if (/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/i.test(value) || /^[^/?#]*@/.test(value)) {
+        throw new Error('launch.proxy must not carry a username or password (found a credential in "' +
+            value +
+            '"). ' +
+            'This version supports proxies WITHOUT authentication only: a password in the config ' +
+            'would be stored in plain text in your patch file, and SOCKS5 authentication is not ' +
+            'supported by Chromium/Playwright at all. Configure an unauthenticated proxy, or leave ' +
+            'this empty to connect directly.');
+    }
+    // Short form: Playwright itself reads `host:port` as HTTP, so accept it the same way.
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : 'http://' + value;
+    // Check the port by hand first: `new URL('http://host:abc')` throws a generic message,
+    // and "the port is not a number" is what the user needs to read.
+    const hostPart = withScheme.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').split('/')[0] ?? '';
+    const hostOnly = hostPart.split('?')[0] ?? '';
+    const portText = (() => {
+        if (hostOnly.startsWith('[')) {
+            const close = hostOnly.indexOf(']');
+            if (close === -1)
+                return '';
+            const rest = hostOnly.slice(close + 1);
+            return rest.startsWith(':') ? rest.slice(1) : '';
+        }
+        const colon = hostOnly.lastIndexOf(':');
+        return colon === -1 ? '' : hostOnly.slice(colon + 1);
+    })();
+    if (portText === '')
+        reject(value, 'the port is missing');
+    if (!/^\d+$/.test(portText ?? ''))
+        reject(value, 'the port is not a number');
+    // Check the range before `new URL` does: an out-of-range port makes the constructor
+    // throw a generic error, and the useful sentence is "the port must be 1–65535".
+    const portNumber = Number(portText);
+    if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {
+        reject(value, 'the port must be 1–65535');
+    }
+    let url;
+    try {
+        url = new URL(withScheme);
+    }
+    catch {
+        return reject(value, 'it does not parse as a URL');
+    }
+    if (!ALLOWED_SCHEMES.has(url.protocol.toLowerCase())) {
+        reject(value, 'only http, https and socks5 are supported');
+    }
+    if (url.hostname === '')
+        reject(value, 'the host is empty');
+    if (url.port === '' || !/^\d+$/.test(url.port))
+        reject(value, 'the port is not a number');
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        reject(value, 'the port must be 1–65535');
+    // A non-special scheme (socks5) parses with an EMPTY pathname while http/https give '/',
+    // so both are "no path". Anything else means the user appended something.
+    if ((url.pathname !== '' && url.pathname !== '/') || url.search !== '' || url.hash !== '') {
+        reject(value, 'a proxy address has no path, query or fragment');
+    }
+    return {
+        server: url.protocol + '//' + url.hostname + ':' + url.port,
+        // Never proxy the plugin's own local pages.
+        bypass: PROXY_BYPASS,
+    };
+}
+/**
+ * The spread-in fragment for Playwright's launch options: `{}` when direct,
+ * `{ proxy: … }` when configured. Every launch path uses this so they cannot drift.
+ *
+ * @param raw - the configured proxy value
+ * @returns an object to spread into the launch options
+ */
+export function proxyLaunchOption(raw) {
+    const proxy = normalizeProxy(raw);
+    return proxy === undefined ? {} : { proxy };
+}

package/lib/script-runner.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Runs a saved script's steps against a live browser session.
+ *
+ * Shape of a run, and why:
+ *  - A step list is executed in order, and the first failure ends the run. A
+ *    script that continued past a failed click would act on a page that never
+ *    got to where the script assumed, and every later step would be noise.
+ *  - Each step uses the same session methods the individual tools call, so the
+ *    URL policy, ref validation and credential refusal stay in force; a step
+ *    cannot do anything the model could not do one call at a time.
+ *  - A `text` target is resolved against the freshest snapshot immediately
+ *    before the action, never against a snapshot taken at the start: that is
+ *    the ref-staleness failure every mature runner designs around.
+ *  - The failure result carries the index, the action and the snapshot from
+ *    the last good step, so the model can take over from there instead of
+ *    replaying the whole script blind.
+ * @module dsh-browser-playwright-codex/script-runner
+ */
+import type { BrowserSession, BrowserSnapshot } from './types.ts';
+import { type ScriptStep } from './script-steps.ts';
+/** One step's result. */
+export interface ScriptStepOutcome {
+    /** 1-based index, as the model numbered the steps. */
+    readonly index: number;
+    /** Human-readable line, e.g. `click "登录"`. */
+    readonly step: string;
+    readonly ok: boolean;
+    /** What the step did, on success. */
+    readonly note?: string;
+}
+/** Everything one run produced. */
+export interface ScriptRunOutcome {
+    /** Steps attempted, including the one that failed. */
+    readonly ran: number;
+    /** Steps in the script. */
+    readonly total: number;
+    /** 1-based index of the failed step; absent when the whole script ran. */
+    readonly failedAt?: number;
+    /** Action name of the failed step. */
+    readonly failedAction?: string;
+    /** Failure message, unchanged from the underlying action. */
+    readonly failure?: string;
+    /** Machine-readable code when the failure was a BrowserError. */
+    readonly failureCode?: string;
+    /** Snapshot from the last step that succeeded (or the failed one's page). */
+    readonly snapshot?: BrowserSnapshot;
+    /** Per-step log, oldest first. */
+    readonly outcomes: readonly ScriptStepOutcome[];
+}
+/** Options for {@link runScript}. */
+export interface RunScriptOptions {
+    /** Cancellation from the calling tool execution. */
+    readonly signal?: AbortSignal;
+    /** Called with the last working snapshot; used to publish login sites. */
+    readonly onSnapshot?: (snapshot: BrowserSnapshot) => void;
+}
+/**
+ * Execute every step in order, stopping at the first failure.
+ *
+ * @param session - The calling session's live browser.
+ * @param steps - Steps already validated by `parseScriptSteps`.
+ * @param options - Cancellation and the snapshot callback.
+ * @returns What ran, what failed, and the last working snapshot.
+ */
+export declare function runScript(session: BrowserSession, steps: readonly ScriptStep[], options?: RunScriptOptions): Promise<ScriptRunOutcome>;