dsh-browser-playwright-codex 0.7.4 → 0.7.6

package/lib/wait-conditions.d.ts

@@ -0,0 +1,55 @@
+import type { PlaywrightSession } from './session.ts';
+import type { WaitCondition, WaitOutcome } from './types.ts';
+/** Timeout used when the caller does not pass `timeoutMs`. */
+export declare const DEFAULT_WAIT_TIMEOUT_MS = 15000;
+/**
+ * Absolute ceiling for a goal wait at the session layer. The tool clamps to
+ * `tool.maxWaitMs` first; this only stops a programmatic caller from parking a
+ * session for an hour on a selector that will never appear.
+ */
+export declare const SESSION_WAIT_CAP_MS = 120000;
+/** One validated wait, ready to run. */
+export type NormalizedWait = {
+    readonly kind: 'ms';
+    readonly ms: number;
+} | {
+    readonly kind: 'selector';
+    readonly selector: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly timeoutMs: number;
+} | {
+    readonly kind: 'networkIdle';
+    readonly timeoutMs: number;
+};
+/**
+ * Validate and normalize one wait request.
+ *
+ * Exactly one condition is allowed per call. Accepting several would make the
+ * composed semantics ("all of them? in which order? what if the first never
+ * comes?") something the model has to guess, and the tool description would
+ * have to grow to explain it.
+ *
+ * @param condition - what the caller asked for
+ * @param maxWaitMs - deployment cap (`tool.maxWaitMs`)
+ * @returns the validated wait
+ * @throws Error with an actionable message when the request is malformed
+ */
+export declare function normalizeWaitCondition(condition: WaitCondition, maxWaitMs: number): NormalizedWait;
+/** Human name of what a normalized wait is waiting for. */
+export declare function describeWait(wait: NormalizedWait): string;
+/**
+ * Run one validated wait against the session's active page.
+ *
+ * A timeout is reported as `ACTION_TIMEOUT` naming what was awaited: the model
+ * then knows the page is still working rather than that its action failed, and
+ * its next move is a snapshot instead of a blind retry.
+ *
+ * @param session - the session whose active page to wait on
+ * @param wait - a value from {@link normalizeWaitCondition}
+ * @param signal - abort signal from the tool call
+ * @returns what was waited for and how long it took
+ */
+export declare function waitForCondition(session: PlaywrightSession, wait: NormalizedWait, signal?: AbortSignal): Promise<WaitOutcome>;

package/lib/wait-conditions.js

@@ -0,0 +1,141 @@
+/**
+ * Goal-directed waits behind `browser_wait`.
+ *
+ * The original tool could only sleep for a fixed number of milliseconds, which
+ * forces the model to guess: too short and the click lands on a half-rendered
+ * page, too long and every call burns wall-clock time for nothing. These three
+ * conditions replace the guess with the actual thing being waited for:
+ *
+ * - `selector`: an element matching a CSS selector becomes visible
+ * - `text`:     visible text containing a string appears
+ * - `networkIdle`: the page stops issuing requests for 500ms
+ *
+ * `ms` stays supported exactly as before, so every existing call keeps working
+ * (`session.wait(ms)` is untouched; this is a separate entry point).
+ *
+ * Validation is separate from execution on purpose: a malformed call must fail
+ * before a browser is launched.
+ *
+ * @module dsh-browser-playwright-codex/wait-conditions
+ */
+import { BrowserError } from "./errors.js";
+import { withAbort } from "./page-actions.js";
+/** Timeout used when the caller does not pass `timeoutMs`. */
+export const DEFAULT_WAIT_TIMEOUT_MS = 15_000;
+/**
+ * Absolute ceiling for a goal wait at the session layer. The tool clamps to
+ * `tool.maxWaitMs` first; this only stops a programmatic caller from parking a
+ * session for an hour on a selector that will never appear.
+ */
+export const SESSION_WAIT_CAP_MS = 120_000;
+/**
+ * Validate and normalize one wait request.
+ *
+ * Exactly one condition is allowed per call. Accepting several would make the
+ * composed semantics ("all of them? in which order? what if the first never
+ * comes?") something the model has to guess, and the tool description would
+ * have to grow to explain it.
+ *
+ * @param condition - what the caller asked for
+ * @param maxWaitMs - deployment cap (`tool.maxWaitMs`)
+ * @returns the validated wait
+ * @throws Error with an actionable message when the request is malformed
+ */
+export function normalizeWaitCondition(condition, maxWaitMs) {
+    const given = [
+        condition.ms === undefined ? undefined : 'ms',
+        condition.selector === undefined ? undefined : 'selector',
+        condition.text === undefined ? undefined : 'text',
+        condition.networkIdle === true ? 'networkIdle' : undefined,
+    ].filter((name) => name !== undefined);
+    if (given.length === 0) {
+        throw new Error('browser_wait: pass one of ms, selector, text or networkIdle — sleeping without a condition is the guess this tool exists to remove');
+    }
+    if (given.length > 1) {
+        throw new Error('browser_wait: pass only one condition per call (received ' +
+            given.join(', ') +
+            '); call it again for the next one');
+    }
+    const cap = Math.max(1, Math.floor(maxWaitMs));
+    if (condition.ms !== undefined) {
+        if (!Number.isSafeInteger(condition.ms) || condition.ms <= 0 || condition.ms > cap) {
+            throw new Error('browser_wait: ms must be a positive integer no larger than ' + String(cap));
+        }
+        return { kind: 'ms', ms: condition.ms };
+    }
+    const requested = condition.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(requested) || requested <= 0) {
+        throw new Error('browser_wait: timeoutMs must be a positive integer');
+    }
+    const timeoutMs = Math.min(requested, cap);
+    if (condition.selector !== undefined) {
+        const selector = condition.selector.trim();
+        if (selector === '')
+            throw new Error('browser_wait: selector must not be empty');
+        return { kind: 'selector', selector, timeoutMs };
+    }
+    if (condition.text !== undefined) {
+        const text = condition.text.trim();
+        if (text === '')
+            throw new Error('browser_wait: text must not be empty');
+        return { kind: 'text', text, timeoutMs };
+    }
+    return { kind: 'networkIdle', timeoutMs };
+}
+/** Human name of what a normalized wait is waiting for. */
+export function describeWait(wait) {
+    switch (wait.kind) {
+        case 'ms':
+            return 'a fixed ' + String(wait.ms) + 'ms';
+        case 'selector':
+            return 'selector ' + JSON.stringify(wait.selector) + ' to become visible';
+        case 'text':
+            return 'text ' + JSON.stringify(wait.text) + ' to become visible';
+        case 'networkIdle':
+            return 'the network to go idle (no request for 500ms)';
+    }
+}
+/**
+ * Run one validated wait against the session's active page.
+ *
+ * A timeout is reported as `ACTION_TIMEOUT` naming what was awaited: the model
+ * then knows the page is still working rather than that its action failed, and
+ * its next move is a snapshot instead of a blind retry.
+ *
+ * @param session - the session whose active page to wait on
+ * @param wait - a value from {@link normalizeWaitCondition}
+ * @param signal - abort signal from the tool call
+ * @returns what was waited for and how long it took
+ */
+export async function waitForCondition(session, wait, signal) {
+    const started = Date.now();
+    return session.run(async () => {
+        session.provider.touch(session.owner);
+        if (wait.kind === 'ms') {
+            await withAbort(new Promise((resolve) => setTimeout(resolve, wait.ms)), signal);
+            return { waitedFor: describeWait(wait), elapsedMs: Date.now() - started };
+        }
+        const page = await session.ensurePage();
+        try {
+            if (wait.kind === 'selector') {
+                await withAbort(page.waitForSelector(wait.selector, { state: 'visible', timeout: wait.timeoutMs }), signal);
+            }
+            else if (wait.kind === 'text') {
+                await withAbort(page.getByText(wait.text).first().waitFor({ state: 'visible', timeout: wait.timeoutMs }), signal);
+            }
+            else {
+                await withAbort(page.waitForLoadState('networkidle', { timeout: wait.timeoutMs }), signal);
+            }
+        }
+        catch (error) {
+            if (signal?.aborted === true)
+                throw error;
+            throw new BrowserError('ACTION_TIMEOUT', 'wait timed out after ' +
+                String(wait.timeoutMs) +
+                'ms waiting for ' +
+                describeWait(wait) +
+                '; the page may still be loading — take a snapshot to see where it stands instead of retrying blind');
+        }
+        return { waitedFor: describeWait(wait), elapsedMs: Date.now() - started };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "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",

package/scripts/dsh-browser-verify.mjs

@@ -28,7 +28,7 @@ import path from 'node:path'
 import { PlaywrightProvider } from '../lib/provider.js'
 import { Config as ConfigSchema } from '../lib/config.js'
 import { renderSnapshot } from '../lib/snapshot-render.js'
-import { getEffectiveEngine, setSnapshotEngine } from '../lib/runtime-state.js'
+import { getEffectiveEngine, publishGates, setSnapshotEngine } from '../lib/runtime-state.js'
 
 // 验收必须只看代码，不看这台机器上用户的选择。
 // 设置页的「页面识别方式」存在 ~/.dsh/dsh-browser-playwright.state.json，运行时状态层
@@ -128,6 +128,36 @@ const provider = new PlaywrightProvider(
 )
 const session = await provider.acquire('verify')
 
+// ---------------------------------------------------------------------------
+// [0] 门禁在代码层也成立（2026-10-26 之前的漏洞：开关只在工具层挡）
+// ---------------------------------------------------------------------------
+// 本脚本不经过工具层，直接调 session —— 正是当初绕过门禁的那条路。默认（没发布门禁）
+// 必须拒绝；确认之后再把门禁打开，好让后面的用例能读页面状态。
+console.log('[0] 门禁：没开门禁时代码层也拒绝')
+let evaluateGate = ''
+try {
+  await session.evaluate('1 + 1')
+} catch (e) {
+  evaluateGate = e.code
+}
+check('evaluate 未开门禁时报 EVALUATE_DISABLED', evaluateGate === 'EVALUATE_DISABLED', evaluateGate)
+let cdpGate = ''
+try {
+  await session.cdp('DOM.getDocument', { depth: 1 })
+} catch (e) {
+  cdpGate = e.code
+}
+check('cdp 未开门禁时报 CDP_DISABLED', cdpGate === 'CDP_DISABLED', cdpGate)
+publishGates({ allowEvaluate: true, allowCdp: true, diagnostics: true })
+let cdpDenied = ''
+try {
+  // 门禁打开也仍然要过白名单：Runtime.evaluate 是任意页面 JS，永远不在名单里。
+  await session.cdp('Runtime.evaluate', { expression: 'document.cookie', returnByValue: true })
+} catch (e) {
+  cdpDenied = e.code
+}
+check('开门禁后 Runtime.evaluate 仍报 CDP_DENIED', cdpDenied === 'CDP_DENIED', cdpDenied)
+
 console.log('[1] 快照取名与折叠')
 const s0 = await session.navigate(URL_, 'load')
 const tree = renderSnapshot(s0)
@@ -366,6 +396,9 @@ const expectedTools = contractMod.registeredToolNames(toolConfig.toolPrefix, {
   registerDisabledTools: toolConfig.registerDisabledTools,
 })
 const byName = (n) => reg.find((t) => t.name === n)
+// apply() 会把有效门禁刷成这份配置里的值（这里出厂默认是关），而下面的用例直接调
+// session 而不是走工具层，所以再打开一次。
+publishGates({ allowEvaluate: true, allowCdp: true, diagnostics: true })
 check('存在 browser_dialog', byName('browser_dialog') !== undefined)
 check(
   'browser_dialog 有 accept 参数',