dsh-browser-playwright-codex 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## 0.7.7 — 2026-10-28
+
+一句话摘要：**首页和 Releases 页能看见版本号了** —— README 顶部加四枚徽章（npm 版本 / 许可证 / 要求的 Node / 最新发布），并把漏掉的 v0.7.5、v0.7.6 补成 GitHub Releases；此前仓库只有 tag，Releases 页停在 v0.7.4。
+
+### Added
+
+- **README 顶部徽章行**：npm 版本、许可证、Node 要求、最新发布四个，数据都从 npm 与 GitHub 现取，不手写版本号。
+- **GitHub Releases 补齐**：v0.7.5、v0.7.6、v0.7.7 三份，各自的说明取自本文件的对应章节。此前 `v0.7.5` / `v0.7.6` 只有 tag 没有 Release，所以主页看不到版本号。
+
+### Changed
+
+- 无代码改动。本次 `npm publish` 唯一目的是让 npm 页上的 README 与仓库首页一致（npm 展示的是发布那一刻的 README）。
+
+## 0.7.6 — 2026-10-26
+
+一句话摘要：**等待从"猜时长"变成"等条件"，升级时旧配置不再静默降级** —— `browser_wait` 现在能等元素出现、等文字出现、等网络安静，条件达成那一刻就返回；同时 0.7.0 遗留的旧加载行第一次被主动报出来（此前它会让部署悄悄跑回默认值，两个强能力等于关着）。
+
+### Fixed
+
+- **旧加载行静默降级（升级坑）**：0.7.0 把三行 loader 并成一行 `- id: browser`，旧行不再被读取，但**没有任何提示**——补丁层里还写着 `- id: browser-tool` 的部署会直接按包内默认值运行（`allowEvaluate` / `allowCdp` 默认关闭），用户以为开着其实关着。实测在一个真实的 0.7.4 部署上就是这个状态：工具面只有 16 个，`evaluate` / `cdp` 全不在，而 YAML 里明明写着 `allowEvaluate: true`。新增 `src/legacy-config.ts`：启动时只读扫描 home 层与各 profile 层的 `cordis.patch.yml`，发现旧行就在宿主日志里报出**文件名 + 行号 + 改法**；同一个 DSH home 只报一次，读不到就静默跳过（这条检查永远不会阻止插件加载）。判据只认每行的 `name`（包名），**不认 `- id:`**——id 只是本地标签，别人的插件也可能把行叫成 `browser-tool`，按 id 报警会冤枉人。退役包（`dsh-browser-toggle` / `dsh-browser-playwright`）单独标一类：它们自带旧设置卡，会反复把配置改回旧写法，所以提示里点名"先去掉那一行"。
+- **报错文案还在教旧名字**：`EVALUATE_DISABLED` / `CDP_DISABLED` 的消息此前写"去 browser-tool 插件上打开 allowEvaluate"。那个插件 0.7.0 就没了，照着改还是改不到。现在指向真正的位置：`cordis.patch.yml` 里单行 `- id: browser` 的 `tool.allowEvaluate` / `tool.allowCdp`，并提示设置卡会自动重写这一行。
+- **快照工具的描述让模型去用一个不存在的工具**：合并 click / hover 之后描述里仍写着 `browser_hover`，模型照着调只会得到"没有这个工具"。改成 `browser_click` + `mode:"hover"`。
+- **设置卡写回的 YAML 里 `diagnostics` 键重复**：`renderBrowserBlock` 既按参数写一行、又硬写一行 `diagnostics: false`。解析方各自取第一条所以之前没炸，但重复键在严格 YAML 里是非法的。删掉多余那行。
+
+### Added
+
+- **`browser_wait` 支持条件等待**：`selector`（元素可见）、`text`（可见文字出现）、`networkIdle`（500ms 无请求），与旧的 `ms` 四选一。条件达成立刻返回，并回报"等了什么、花了多少毫秒"；超时报 `ACTION_TIMEOUT` 并提示先取快照看状态，而不是盲目重试。旧行为完整保留：`session.wait(ms)` 一个字没动，`browser_wait { ms }` 照常可用。
+- **`src/wait-conditions.ts`**：校验与执行分离，所以参数错误在**启动浏览器之前**就被拒；会话层自己也会校验一遍，程序化调用绕不过去。`timeoutMs` 默认 15000，上限由部署的 `maxWaitMs` 收紧。
+- **公开导出（只增不减）**：`normalizeWaitCondition`、`describeWait`、`DEFAULT_WAIT_TIMEOUT_MS`、类型 `WaitCondition` / `WaitOutcome`；方法 `PlaywrightSession.waitForCondition()`，以及 `BrowserSession` 接口里对应的声明。
+- **`tests/legacy-config.test.ts`（10 条）**：旧三行布局逐行报出、合并后的单行布局与注释掉的旧行都算干净、改名但沿用旧 `name` 的行也能抓、**别人的插件把行叫 `browser-tool` 不报**、退役包单独归类、警告文本含文件名/行号/替换写法与判据说明、home 与 profile 层都扫、干净的部署一声不响且同一 home 只报一次、home 不存在不抛错。
+- **`tests/wait-conditions.test.ts`（9 条）**：无条件/双条件被拒、`ms` 边界不变、默认 15s 与部署上限、超时文案指向快照、selector / text / networkIdle 三条执行路径各一条（用假页面，不需要真浏览器）。
+
+### Changed
+
+- **说明书瘦身**：新增 4 个参数的同时把常驻成本**净减**——16 工具 11,179 → **11,095** 字符（−84），全量注册 15,782 → 15,698（−84）；字符与 token 的对照见 README 的成本表。压缩的是重复与冗词：快照、填写、弹窗、导航、标签五处描述，加上点击工具的四个参数说明；点击工具那张"每条规则必须还在"的守卫表（30 条）一条没动。
+
+### Tests
+
+- 全套 255 → **274 条**（+19）：通过 271、跳过 3、失败 0。
+
 ## 0.7.5 — 2026-10-26
 
 一句话摘要：**两条安全洞补上，同时唤醒不再多开浏览器** —— 白名单从"门口打一次勾"变成"装在浏览器的请求上"，`allowEvaluate` / `allowCdp` 从工具层下沉到会话层（绕过工具直接拿服务也拒），两个任务同时要浏览器时共用一次启动，默认持久化模式下「最多几个会话」也真的算数了。

package/README.md

@@ -1,5 +1,7 @@
 # dsh-browser-playwright-codex
 
+[![npm 版本](https://img.shields.io/npm/v/dsh-browser-playwright-codex?label=npm)](https://www.npmjs.com/package/dsh-browser-playwright-codex) [![License](https://img.shields.io/npm/l/dsh-browser-playwright-codex)](LICENSE) [![Node](https://img.shields.io/node/v/dsh-browser-playwright-codex)](package.json) [![最新发布](https://img.shields.io/github/v/release/miqian-nomad/dsh-browser-playwright-codex)](https://github.com/miqian-nomad/dsh-browser-playwright-codex/releases)
+
 > [![dsh.so 安装验证 · harness 0.2.0-rc.1](https://www.dsh.so/badge/install/dsh-browser-playwright-codex@0.2.0-rc.1.svg)](https://www.dsh.so/zh/artifact/dsh-browser-playwright-codex/) [![dsh.so 风险](https://www.dsh.so/badge/dsh-browser-playwright-codex.svg)](https://www.dsh.so/zh/artifact/dsh-browser-playwright-codex/)
 
 **一句话**：让 AI 用你**已经登录的账号**在真实网页上干活 —— 填表、抓取列表、多标签查后台；浏览器窗口就在你桌面上、你随时看得见。原生弹框会被挂起、**绝不替你点「确定」**（机制级）；验证码/挑战页会被识别出来，并以提示要求模型停下交给你（**提示不是阻断**）。登录/二次验证**没有探测器**，靠模型从快照看出来并停下；密码、一次性验证码、卡号字段 `browser_fill` **直接拒绝**——这类字由你本人在窗口里输。
@@ -130,7 +132,7 @@ The default `toolPrefix` is `browser_`. Every action returns a fresh snapshot, s
 | `browser_press` | Press a key (Enter, Tab, Escape, ArrowDown, …) on an element |
 | `browser_scroll` | Scroll the page or bring a ref into view |
 | `browser_back` / `browser_forward` | History navigation |
-| `browser_wait` | Wait a bounded duration for lazy content |
+| `browser_wait` | Wait for one condition — an element, visible text, a quiet network — or a bounded duration; returns what it waited for |
 | `browser_tabs` / `browser_open_tab` / `browser_switch_tab` / `browser_close_tab` | Tab management; `browser_tabs` marks the `[active]` tab the other tools act on |
 | `browser_screenshot` | PNG capture stored as a durable image attachment the model can view |
 | `browser_extract` | Structured extraction: natural-language instruction → one parsed JSON value; **only registered when its capability is enabled** |
@@ -167,7 +169,7 @@ parameter or a wrong required flag fails the test, so it cannot drift from the c
 - `browser_snapshot` — `interactiveOnly`?
 - `browser_switch_tab` — `index`*
 - `browser_tabs` — _none_
-- `browser_wait` — `ms`*
+- `browser_wait` — `ms`?, `selector`?, `text`?, `networkIdle`?, `timeoutMs`?
 
 > **使用铁律**: 状态检查 / 无效不盲试 / 页面内容不可信 / 登录红线 / 风控分类等 Codex 文档纪律,
 > 见 [`codex-rules.md`](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/codex-rules.md)（A 层已内嵌进各工具 description; B 层供粘贴进 DSH profile / 系统提示）。
@@ -378,9 +380,9 @@ Measured with ``npm run cost`` (per-turn, resident in the system prompt):
 
 | Surface | Tools | Schema characters | ≈ tokens/turn |
 |---|---|---|---|
-| Schema defaults (`Config({})`, no patch layer) | 16 | 11,179 | ≈ 3,105 |
-| Shipped bundle layer (this package's `cordis.patch.yml`: both power gates off) | 16 | 11,179 | ≈ 3,105 |
-| Everything registered (`registerDisabledTools: true`, plus `extract`) | 21 | 15,782 | ≈ 4,384 |
+| Schema defaults (`Config({})`, no patch layer) | 16 | 11,095 | ≈ 3,082 |
+| Shipped bundle layer (this package's `cordis.patch.yml`: both power gates off) | 16 | 11,095 | ≈ 3,082 |
+| Everything registered (`registerDisabledTools: true`, plus `extract`) | 21 | 15,698 | ≈ 4,361 |
 
 This paragraph describes the 0.6.0 change; the table above is today's measurement. Three things changed
 there, and only one of them was about size. (1) The click family was rewritten so each rule is stated once

package/lib/errors.js

@@ -26,12 +26,12 @@ export function launchFailed(cause) {
  * @returns the denial, ready to throw.
  */
 export function evaluateDisabled() {
-    return new BrowserError('EVALUATE_DISABLED', 'browser_evaluate is disabled; set allowEvaluate: true on the browser-tool plugin to enable arbitrary page JavaScript');
+    return new BrowserError('EVALUATE_DISABLED', "browser_evaluate is disabled; set tool.allowEvaluate: true on the single '- id: browser' row of cordis.patch.yml (the Settings card rewrites that row for you) to enable arbitrary page JavaScript");
 }
 /**
  * "browser_cdp is switched off". Same two-layer rule as {@link evaluateDisabled}.
  * @returns the denial, ready to throw.
  */
 export function cdpDisabled() {
-    return new BrowserError('CDP_DISABLED', 'browser_cdp is disabled; set allowCdp: true on the browser-tool plugin to enable raw CDP inspection commands');
+    return new BrowserError('CDP_DISABLED', "browser_cdp is disabled; set tool.allowCdp: true on the single '- id: browser' row of cordis.patch.yml (the Settings card rewrites that row for you) to enable raw CDP inspection commands");
 }

package/lib/gates-patch.js

@@ -75,7 +75,6 @@ export function renderBrowserBlock(allowEvaluate, allowCdp, diagnostics) {
         '      allowCdp: ' + (allowCdp ? 'true' : 'false'),
         '      diagnostics: ' + (diagnostics ? 'true' : 'false'),
         '      registerDisabledTools: false',
-        '      diagnostics: false',
         '      maxWaitMs: 60000',
         END,
         '',

package/lib/index.d.ts

@@ -18,9 +18,10 @@ export { PlaywrightProvider } from './provider.ts';
 export { assertAllowedUrl, isHostAllowed } from './url-policy.ts';
 export { installHostGuard } from './navigation-guard.ts';
 export type { BlockedRequest } from './navigation-guard.ts';
+export { DEFAULT_WAIT_TIMEOUT_MS, describeWait, normalizeWaitCondition } from './wait-conditions.ts';
 export { Config as PlaywrightConfigSchema } from './config.ts';
 export type { PlaywrightConfig, PageData } from './config.ts';
-export type { BrowserNode, BrowserProvider, BrowserSession, BrowserSnapshot, LoadState, ScreenshotCapture, TabInfo, } from './types.ts';
+export type { BrowserNode, BrowserProvider, BrowserSession, BrowserSnapshot, LoadState, ScreenshotCapture, TabInfo, WaitCondition, WaitOutcome, } from './types.ts';
 export type { ToolConfig } from './tool.ts';
 export { Config as BrowserPluginConfigSchema, apply, name } from './plugin.ts';
 export type { BrowserPluginConfig } from './plugin.ts';

package/lib/index.js

@@ -12,6 +12,7 @@ export { default as BrowserRuntime } from "./service.js";
 export { PlaywrightProvider } from "./provider.js";
 export { assertAllowedUrl, isHostAllowed } from "./url-policy.js";
 export { installHostGuard } from "./navigation-guard.js";
+export { DEFAULT_WAIT_TIMEOUT_MS, describeWait, normalizeWaitCondition } from "./wait-conditions.js";
 export { Config as PlaywrightConfigSchema } from "./config.js";
 // Single loader row (2026-10-19): the package root is the plugin. The three
 // sub-entries below stay importable, but the loader mounts this one.

package/lib/legacy-config.d.ts

@@ -0,0 +1,93 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Row ids that 0.7.0 stopped reading. */
+export declare const LEGACY_ROW_IDS: readonly ["browser-playwright", "browser-tool", "browser-playwright-service"];
+/**
+ * Subpath entries that 0.7.0 stopped mounting. Rows naming one of these are
+ * stale even when the user gave them some other id.
+ */
+export declare const LEGACY_ENTRY_NAMES: readonly ["dsh-browser-playwright-codex/tool", "dsh-browser-playwright-codex/playwright", "dsh-browser-playwright-codex/service"];
+/**
+ * Retired package names this project owns on npm. A row mounting one of them
+ * keeps a second, older settings card alive — and that card rewrites the patch
+ * layer in the pre-0.7.0 shape, so the fix keeps reverting.
+ *
+ * Matching is by package NAME, never by row id: `- id:` is a local label the
+ * user picks, so another plugin may legitimately call its row `browser-tool`.
+ * Only a row whose `name:` is one of ours is reported.
+ */
+export declare const RETIRED_PACKAGES: readonly ["dsh-browser-playwright", "dsh-browser-toggle"];
+/** One loader row that no longer takes effect. */
+export interface LegacyRow {
+    /** The row id, or `(no id)` when the row only carried a legacy `name`. */
+    readonly id: string;
+    /** The row's `name:` value when it had one. */
+    readonly name?: string;
+    /** 1-based line number of the row's `- id:` line. */
+    readonly line: number;
+    /**
+     * `entry`: a row mounting a subpath entry this package no longer exposes.
+     * `package`: a row mounting a whole package that 0.7.0 retired.
+     */
+    readonly target: 'entry' | 'package';
+}
+/**
+ * Find loader rows in one patch file's text that 0.7.0 stopped reading.
+ *
+ * The evidence is always the row's `name:` — never its `- id:`, which is just a
+ * local label. A patch layer that happens to call some unrelated plugin's row
+ * `browser-tool` is not reported.
+ *
+ * Pure and text-only so the rule can be tested without touching a real patch
+ * layer. Comments are ignored naturally: a commented row fails the anchored
+ * `- id:` / `  name:` patterns.
+ *
+ * @param text - contents of a cordis.patch.yml layer
+ * @returns every stale row, in file order
+ */
+export declare function findLegacyRowsIn(text: string): LegacyRow[];
+/**
+ * The operator-facing warning for one patch file.
+ *
+ * Written as one self-contained paragraph pair on purpose: it lands in a log
+ * line, so it has to name the file, the rows, and the fix without the reader
+ * opening documentation first.
+ *
+ * @param file - absolute path of the patch layer
+ * @param rows - stale rows found in it
+ * @returns the warning text
+ */
+export declare function legacyRowWarning(file: string, rows: readonly LegacyRow[]): string;
+/**
+ * Patch layers that can hold a browser row: the home layer plus every profile
+ * layer. Missing files and unreadable directories are skipped silently — this
+ * check must never be the reason a plugin fails to load.
+ *
+ * @param env - environment (`DSH_HOME` override, as the rest of the package uses)
+ * @returns candidate file paths, home layer first
+ */
+export declare function patchLayers(env?: NodeJS.ProcessEnv): Promise<string[]>;
+/** Stale rows found in one patch file. */
+export interface LegacyHit {
+    /** Absolute path of the patch layer. */
+    readonly file: string;
+    /** Stale rows inside it. */
+    readonly rows: readonly LegacyRow[];
+}
+/**
+ * Scan every patch layer for stale rows.
+ *
+ * @param env - environment (`DSH_HOME` override)
+ * @returns one entry per file that still lists a retired row; empty when clean
+ */
+export declare function scanLegacyRows(env?: NodeJS.ProcessEnv): Promise<LegacyHit[]>;
+/**
+ * Warn about stale loader rows, once per DSH home, never throwing.
+ *
+ * Call it from the plugin entry: it is advisory only, so a failure here must
+ * never affect mounting the capability.
+ *
+ * @param ctx - plugin context (its logger carries the message to the host log)
+ * @param env - environment (`DSH_HOME` override, as tests use)
+ * @param report - sink for the text (defaults to the context logger, then console)
+ */
+export declare function warnLegacyRows(ctx: Context, env?: NodeJS.ProcessEnv, report?: (text: string) => void): Promise<void>;

package/lib/legacy-config.js

@@ -0,0 +1,238 @@
+/**
+ * Legacy loader-row detection (2026-10-19 merge follow-up).
+ *
+ * 0.7.0 collapsed three loader rows (`browser-playwright`, `browser-tool`, and
+ * the `/service` entry) into one `- id: browser` row with nested
+ * `service` / `playwright` / `tool` config. The loader simply stops reading the
+ * old rows, so an upgraded deployment whose patch layer still lists them starts
+ * with the package defaults — and the package ships both power gates OFF.
+ *
+ * That failure is silent: nothing errors, the tools that the old row would have
+ * published are simply absent, and the user believes a capability is still on.
+ * A real 0.7.4 deployment was found in exactly this state (16 tools, no
+ * `evaluate` / `cdp`, `allowEvaluate: true` sitting in a row nobody reads).
+ *
+ * This module reads the patch layers (read-only, never writes) and reports the
+ * stale rows once per DSH home so the operator can fix the config instead of
+ * discovering the downgrade through a missing tool.
+ *
+ * @module dsh-browser-playwright-codex/legacy-config
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Row ids that 0.7.0 stopped reading. */
+export const LEGACY_ROW_IDS = ['browser-playwright', 'browser-tool', 'browser-playwright-service'];
+/**
+ * Subpath entries that 0.7.0 stopped mounting. Rows naming one of these are
+ * stale even when the user gave them some other id.
+ */
+export const LEGACY_ENTRY_NAMES = [
+    'dsh-browser-playwright-codex/tool',
+    'dsh-browser-playwright-codex/playwright',
+    'dsh-browser-playwright-codex/service',
+];
+/**
+ * Retired package names this project owns on npm. A row mounting one of them
+ * keeps a second, older settings card alive — and that card rewrites the patch
+ * layer in the pre-0.7.0 shape, so the fix keeps reverting.
+ *
+ * Matching is by package NAME, never by row id: `- id:` is a local label the
+ * user picks, so another plugin may legitimately call its row `browser-tool`.
+ * Only a row whose `name:` is one of ours is reported.
+ */
+export const RETIRED_PACKAGES = ['dsh-browser-playwright', 'dsh-browser-toggle'];
+/** A `- id:` at column 0 starts a loader row. */
+const ROW_ID = /^- id:\s*['"]?([A-Za-z0-9._-]+)['"]?\s*$/;
+/** `name:` at exactly two spaces belongs to the row, not to a nested config block. */
+const ROW_NAME = /^ {2}name:\s*['"]?([^'"\s#]+)['"]?\s*$/;
+/**
+ * Find loader rows in one patch file's text that 0.7.0 stopped reading.
+ *
+ * The evidence is always the row's `name:` — never its `- id:`, which is just a
+ * local label. A patch layer that happens to call some unrelated plugin's row
+ * `browser-tool` is not reported.
+ *
+ * Pure and text-only so the rule can be tested without touching a real patch
+ * layer. Comments are ignored naturally: a commented row fails the anchored
+ * `- id:` / `  name:` patterns.
+ *
+ * @param text - contents of a cordis.patch.yml layer
+ * @returns every stale row, in file order
+ */
+export function findLegacyRowsIn(text) {
+    const rows = [];
+    const lines = text.split(/\r?\n/);
+    let current;
+    const finish = () => {
+        const name = current?.name;
+        if (name !== undefined && LEGACY_ENTRY_NAMES.includes(name)) {
+            rows.push({
+                id: current?.id ?? '(no id)',
+                name,
+                line: current?.line ?? 0,
+                target: 'entry',
+            });
+        }
+        else if (name !== undefined && RETIRED_PACKAGES.includes(name)) {
+            rows.push({
+                id: current?.id ?? '(no id)',
+                name,
+                line: current?.line ?? 0,
+                target: 'package',
+            });
+        }
+        current = undefined;
+    };
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const id = ROW_ID.exec(line);
+        if (id !== null) {
+            finish();
+            const value = id[1];
+            if (value !== undefined)
+                current = { id: value, line: index + 1 };
+            continue;
+        }
+        if (current === undefined)
+            continue;
+        const name = ROW_NAME.exec(line);
+        const label = name?.[1];
+        if (label !== undefined && current.name === undefined)
+            current.name = label;
+    }
+    finish();
+    return rows;
+}
+/**
+ * The operator-facing warning for one patch file.
+ *
+ * Written as one self-contained paragraph pair on purpose: it lands in a log
+ * line, so it has to name the file, the rows, and the fix without the reader
+ * opening documentation first.
+ *
+ * @param file - absolute path of the patch layer
+ * @param rows - stale rows found in it
+ * @returns the warning text
+ */
+export function legacyRowWarning(file, rows) {
+    const listed = rows
+        .map((row) => `  - 第 ${String(row.line)} 行: - id: ${row.id} (name: ${row.name ?? '?'})` +
+        (row.target === 'package' ? '  ← 退役包' : '  ← 本插件 0.7.0 之前的入口'))
+        .join('\n');
+    const retired = rows.some((row) => row.target === 'package');
+    return [
+        'browser 插件发现 0.7.0 之前的旧加载行，当前版本不再读取它们 —— 那几行里的 config 全部不生效，',
+        '插件按包内默认值运行（allowEvaluate / allowCdp 默认关闭，等于你以为开着其实关着）。',
+        `文件: ${file}`,
+        listed,
+        ...(retired
+            ? [
+                '标了「退役包」的行挂的是本项目的旧包（dsh-browser-toggle / dsh-browser-playwright）：它们自带一张旧设置卡，',
+                '还会按旧写法改写这个文件，所以只改下面这几行会反复被改回去 —— 先把那一行去掉或禁用。',
+            ]
+            : []),
+        '改法：按 name 删掉这些旧行，然后打开一次设置页的「浏览器」卡片（它会整块重写成一行），',
+        "或手写一行 `- id: browser` + `name: 'dsh-browser-playwright-codex'`，并把 service / playwright / tool 三节写全。",
+        '判断依据是每行的 name（包名），不是 id —— id 只是本地标签，别人的插件也可能叫 browser-tool。',
+        '如果你确认某个 name 不是本插件的包，那它跟这条提示无关，忽略即可。',
+    ].join('\n');
+}
+/**
+ * Patch layers that can hold a browser row: the home layer plus every profile
+ * layer. Missing files and unreadable directories are skipped silently — this
+ * check must never be the reason a plugin fails to load.
+ *
+ * @param env - environment (`DSH_HOME` override, as the rest of the package uses)
+ * @returns candidate file paths, home layer first
+ */
+export async function patchLayers(env = process.env) {
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME !== '' ? env.DSH_HOME : join(homedir(), '.dsh');
+    const files = [join(home, 'cordis.patch.yml')];
+    const profiles = join(home, 'profiles');
+    let entries = [];
+    try {
+        entries = await readdir(profiles);
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries.sort())
+        files.push(join(profiles, entry, 'cordis.patch.yml'));
+    return files;
+}
+/**
+ * Scan every patch layer for stale rows.
+ *
+ * @param env - environment (`DSH_HOME` override)
+ * @returns one entry per file that still lists a retired row; empty when clean
+ */
+export async function scanLegacyRows(env = process.env) {
+    const hits = [];
+    for (const file of await patchLayers(env)) {
+        let text = '';
+        try {
+            text = await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const rows = findLegacyRowsIn(text);
+        if (rows.length > 0)
+            hits.push({ file, rows });
+    }
+    return hits;
+}
+/** DSH homes already scanned in this process, so one load logs once. */
+const scannedHomes = new Set();
+/**
+ * Warn about stale loader rows, once per DSH home, never throwing.
+ *
+ * Call it from the plugin entry: it is advisory only, so a failure here must
+ * never affect mounting the capability.
+ *
+ * @param ctx - plugin context (its logger carries the message to the host log)
+ * @param env - environment (`DSH_HOME` override, as tests use)
+ * @param report - sink for the text (defaults to the context logger, then console)
+ */
+export async function warnLegacyRows(ctx, env = process.env, report) {
+    if (env.DSH_BROWSER_SKIP_LEGACY_SCAN === '1')
+        return;
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME !== '' ? env.DSH_HOME : join(homedir(), '.dsh');
+    if (scannedHomes.has(home))
+        return;
+    scannedHomes.add(home);
+    let hits = [];
+    try {
+        hits = await scanLegacyRows(env);
+    }
+    catch {
+        return;
+    }
+    if (hits.length === 0)
+        return;
+    const warn = report ?? loggerWarn(ctx);
+    for (const hit of hits) {
+        try {
+            warn(legacyRowWarning(hit.file, hit.rows));
+        }
+        catch {
+            // A logger that is not mounted yet must not break the load.
+        }
+    }
+}
+/** Best-effort warn sink: the context logger when it exists, otherwise console. */
+function loggerWarn(ctx) {
+    return (text) => {
+        try {
+            if (ctx.logger !== undefined) {
+                ctx.logger.warn(text);
+                return;
+            }
+        }
+        catch {
+            // fall through to console
+        }
+        console.warn(text);
+    };
+}

package/lib/plugin.js

@@ -5,6 +5,7 @@ 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";
+import { warnLegacyRows } from "./legacy-config.js";
 /** Schemastery validation for {@link BrowserPluginConfig}. */
 export const Config = z.object({
     service: ServiceConfig,
@@ -21,6 +22,10 @@ export const name = 'browser';
  * @param config - nested config for each concern; the loader fills defaults
  */
 export function apply(ctx, config) {
+    // 0.7.0 stopped reading the three legacy rows, and a stale row downgrades the
+    // deployment to package defaults (both power gates off) without an error.
+    // Advisory only: it reads the patch layers and never blocks the mount.
+    void warnLegacyRows(ctx).catch(() => { });
     ctx.plugin(BrowserRuntime, config.service ?? {});
     ctx.plugin(playwright, config.playwright);
     ctx.plugin(tool, config.tool);

package/lib/session.d.ts

@@ -5,7 +5,7 @@
  */
 import type { BrowserContext, CDPSession, Locator, Page, Request } from 'playwright-core';
 import type { PlaywrightProvider } from './provider.ts';
-import type { BrowserNode, BrowserSnapshot, DiagnosticsEntry, DocumentResponse, LoadState } from './types.ts';
+import type { BrowserNode, BrowserSnapshot, DiagnosticsEntry, DocumentResponse, LoadState, WaitCondition, WaitOutcome } from './types.ts';
 import type { RefSignature } from './page-snapshot.ts';
 import { type CookieRow } from './login-sites.ts';
 import type { ActionResult, PendingDialogRecord } from './provider.ts';
@@ -274,6 +274,12 @@ export declare class PlaywrightSession {
     back(signal?: AbortSignal): Promise<BrowserSnapshot>;
     forward(signal?: AbortSignal): Promise<BrowserSnapshot>;
     wait(ms: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Wait for a goal instead of a duration: an element, a piece of text, or a
+     * quiet network. Validated here as well, so a programmatic caller gets the
+     * same refusals the tool layer gives instead of a raw Playwright timeout.
+     */
+    waitForCondition(condition: WaitCondition, signal?: AbortSignal): Promise<WaitOutcome>;
     tabs(): Promise<{
         index: number;
         url: string;

package/lib/session.js

@@ -8,6 +8,7 @@ import { elementStabilityProbe, pageStabilityProbe } from "./page-probes.js";
 import { assertActionable, back, clickAt, clickAtRef, clickLocator, clickText, closeTab, fill, forward, hoverLocator, hoverText, navigate, openTab, press, resolveClickPoint, runAction, scroll, switchTab, verifyFill, withAbort, } from "./page-actions.js";
 import { assertLive, attachDiff, attachDocResponse, attachNoProgress, buildRefSignatures, captureAria, captureLegacy, refLocator, resolveSnapshotEngine, settleAndSnapshot, snapshot, } from "./page-snapshot.js";
 import { assertAllowedUrl, isHostAllowed } from "./url-policy.js";
+import { normalizeWaitCondition, SESSION_WAIT_CAP_MS, waitForCondition as runWait } from "./wait-conditions.js";
 /** Live session over one browser context owned by one caller. */
 export class PlaywrightSession {
     provider;
@@ -496,6 +497,14 @@ export class PlaywrightSession {
             await withAbort(new Promise((resolve) => setTimeout(resolve, ms)), signal);
         });
     }
+    /**
+     * Wait for a goal instead of a duration: an element, a piece of text, or a
+     * quiet network. Validated here as well, so a programmatic caller gets the
+     * same refusals the tool layer gives instead of a raw Playwright timeout.
+     */
+    async waitForCondition(condition, signal) {
+        return runWait(this, normalizeWaitCondition(condition, SESSION_WAIT_CAP_MS), signal);
+    }
     async tabs() {
         return this.run(async () => {
             this.assertLive();

package/lib/tool.js

@@ -9,6 +9,7 @@ import { isCdpMethodAllowed, cdpDenialMessage } from "./cdp-policy.js";
 import { SCREENSHOT_SCHEMA, SNAPSHOT_SCHEMA, TABS_SCHEMA } from "./tool-schemas.js";
 import { parseJsonText, extractionPrompt } from "./extract.js";
 import { detectChallenge } from "./challenge.js";
+import { describeWait, normalizeWaitCondition } from "./wait-conditions.js";
 import { renderDiagnostics, renderScreenshotValue, renderSnapshotValue, renderTabsValue, snapshotValue, } from "./tool-render.js";
 export { detectChallenge };
 /** Cordis plugin name used by loader diagnostics. */
@@ -124,10 +125,9 @@ export function apply(ctx, config) {
     };
     ctx.tools.register(defineTool({
         name: p('navigate'),
-        description: 'Navigate the persistent browser to a URL and return the new page snapshot. ' +
-            'The snapshot lists visible elements with stable ref= identifiers for later click/fill calls. ' +
-            'IRON RULE: if the page is already on the target URL, do NOT navigate to it again — re-navigating the ' +
-            'same URL reloads the page and can discard in-progress user input; only navigate when the URL must actually change.',
+        description: 'Navigate the persistent browser to a URL and return the new snapshot: visible elements with stable refs for later click/fill. ' +
+            'IRON RULE: if the page is already on that URL, do NOT navigate again — a re-navigation reloads it and can ' +
+            'discard input the user has typed; only navigate when the URL must actually change.',
         parameters: {
             url: { type: 'string', required: true, description: 'Absolute http(s) URL to open.' },
             waitFor: {
@@ -145,21 +145,17 @@ export function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: p('snapshot'),
-        description: 'Return the current page snapshot: URL, title, and visible elements with stable ref= identifiers. ' +
-            'Use this after dynamic content changes to refresh refs before clicking. ' +
-            'An element shown with a name but NO [ref=...] has no ref handle of its own — ' +
+        description: 'Snapshot the current page: URL, title, visible elements with stable ref= ids. ' +
+            'Take one after dynamic changes to refresh refs before clicking. ' +
+            'A named element with NO [ref=...] has no handle of its own: ' +
             p('click') +
-            ' and ' +
-            p('hover') +
-            ' still reach it by passing its exact label as text, as long as the element is visible at that moment. ' +
-            'An effect can be real even when the URL does not change and no tab opens (a same-page overlay or popup): compare refs and content between snapshots instead of trusting the URL. ' +
-            'A native dialog (alert / confirm / prompt / beforeunload) is not part of the page: it is left PENDING and blocks the page, reported at the top of the result as [dialog] type "message"; answer it with ' +
+            ' reaches it by exact label text (also with mode:"hover") while it is visible. ' +
+            'A real effect can leave the URL and tab count unchanged (same-page overlay): compare refs and content between snapshots, not the URL. ' +
+            'A native dialog (alert / confirm / prompt / beforeunload) is not page content: it stays PENDING, blocks the page, and is reported as [dialog] type "message"; answer it with ' +
             p('dialog') +
-            '({ accept }) and accept only when the user authorized exactly that action. ' +
-            'IRON RULE: a snapshot is the cheapest state check after any click/type/scroll — confirm the previous ' +
-            'action actually took effect here (URL change, selection, toast, new content) before your next action. ' +
-            'Pick ONE verification channel per step: prefer a snapshot for DOM/locator ground truth or a screenshot ' +
-            'when visual confirmation matters, but avoid requesting both by default.',
+            '({ accept }) — only when the user authorized exactly that action. ' +
+            'IRON RULE: after any click/type/scroll this is the cheapest check that the action took effect (URL, selection, toast, new content). ' +
+            'Use one verification channel per step: snapshot for DOM truth, screenshot when visuals matter — not both by default.',
         parameters: {
             interactiveOnly: {
                 type: 'boolean',
@@ -189,19 +185,19 @@ export function apply(ctx, config) {
         parameters: {
             ref: {
                 type: 'string',
-                description: 'Element ref (e.g. e12) from the latest snapshot. Preferred whenever the snapshot has one.',
+                description: 'Ref from the latest snapshot (e.g. e12); preferred when the snapshot has one.',
             },
             text: {
                 type: 'string',
-                description: 'Visible label of a target shown WITHOUT a ref, copied exactly as the snapshot renders it; the first visible element whose own text matches is used and the note names it.',
+                description: 'Visible label of a target shown WITHOUT a ref, copied exactly; the first visible match is used and the note names it.',
             },
             x: {
                 type: 'integer',
-                description: 'Viewport x in CSS pixels, with y: a raw click, mode "click" only, last resort.',
+                description: 'Viewport x in CSS px; with y, a raw click — mode "click" only, last resort.',
             },
             y: {
                 type: 'integer',
-                description: 'Viewport y in CSS pixels, with x: a raw click, mode "click" only, last resort.',
+                description: 'Viewport y in CSS px; with x, a raw click — mode "click" only, last resort.',
             },
             mode: {
                 type: 'string',
@@ -210,7 +206,7 @@ export function apply(ctx, config) {
             },
             precise: {
                 type: 'boolean',
-                description: 'Ref clicks only: click the geometric centre through native input instead of the standard click.',
+                description: 'Ref clicks only: click the geometric centre through native input.',
             },
         },
         output: { schema: SNAPSHOT_SCHEMA, render: renderSnapshotValue },
@@ -242,12 +238,12 @@ export function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: p('dialog'),
-        description: 'Answer the native dialog currently blocking the page — alert, confirm, prompt or beforeunload — and return the fresh snapshot. ' +
-            'A dialog is NEVER auto-answered: it stays PENDING until this call. The call that raised it and ' +
+        description: 'Answer the dialog blocking the page (alert / confirm / prompt / beforeunload) and return the fresh snapshot. ' +
+            'Never auto-answered: it stays PENDING until this call; the raising call and ' +
             p('snapshot') +
-            ' report it as a note; every other tool refuses to act and fails with DIALOG_PENDING. ' +
-            'accept: true confirms it (OK / leave page), false cancels it (Cancel / stay on page). Accept only when the user has explicitly authorized exactly this action (delete / pay / submit / overwrite); never confirm on your own initiative, and state in your reply which dialog you answered and how. ' +
-            'A prompt takes its value through promptText. Without a pending dialog this errors with NO_DIALOG — there is no way to accept a dialog the page never raised.',
+            ' report it, every other tool fails with DIALOG_PENDING. ' +
+            'accept: true confirms (OK / leave page), false cancels. Only when the user explicitly authorized exactly this action (delete / pay / submit / overwrite) — never on your own initiative; say in your reply which dialog you answered and how. ' +
+            'A prompt takes promptText. With no dialog pending this errors NO_DIALOG: a dialog the page never raised cannot be accepted.',
         parameters: {
             accept: {
                 type: 'boolean',
@@ -271,19 +267,16 @@ export function apply(ctx, config) {
     ctx.tools.register(defineTool({
         name: p('fill'),
         description: 'Replace the value of the input or select referenced by the latest snapshot. ' +
-            '`value` is accepted as an alias of `text`. ' +
-            'For <select> elements the text selects the matching option label. ' +
+            '`value` is an alias of `text`; for <select> the text selects the matching option label. ' +
             'Credential fields (password, one-time code, card number) are refused with CREDENTIAL_FIELD: ' +
-            'a human types secrets in the visible window, so ask them and re-snapshot instead. ' +
-            'IRON RULE: after filling, verify in the returned snapshot that the field actually holds the value. ' +
-            'Frameworks can silently reject or transform input (controlled components, contenteditable editors, ' +
-            'input-mask/currency fields). If the value is wrong or missing, do NOT blindly re-fill or append — ' +
-            'inspect the field DOM first — ' +
+            'a human types secrets in the visible window, so ask them and re-snapshot. ' +
+            'IRON RULE: verify in the returned snapshot that the field holds the value — frameworks can ' +
+            'silently reject or transform input (controlled components, contenteditable, input-mask/currency). ' +
+            'If it is wrong or missing, do NOT re-fill or append: inspect the field DOM first (' +
             p('evaluate') +
             ' reading value/outerHTML, or ' +
             p('cdp') +
-            ' Input.insertText for contenteditable (both are gated — when one is missing from your tool list, ' +
-            'say so) — understand why it was ignored, then act.',
+            ' Input.insertText for contenteditable; both are gated, so say so when one is missing), understand why it was ignored, then act.',
         parameters: {
             ref: { type: 'string', required: true, description: 'Input or select ref (e.g. e7) from the latest snapshot.' },
             text: {
@@ -361,27 +354,54 @@ export function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: p('wait'),
-        description: 'Wait a fixed duration for slow pages or lazy content to settle.',
+        description: 'Wait for ONE condition: `selector` (element becomes visible), `text` (visible text appears), ' +
+            '`networkIdle` (no request for 500ms) or `ms` (plain sleep). Prefer a goal over `ms` — it returns ' +
+            'the moment the page is ready, neither too early nor wasteful. Reports what it waited for and how long.',
         parameters: {
             ms: {
                 type: 'integer',
-                required: true,
-                description: 'Milliseconds to wait, up to ' + String(config.maxWaitMs) + '.',
+                description: 'Fixed sleep in milliseconds, up to ' +
+                    String(config.maxWaitMs) +
+                    '. Use it only when nothing observable marks the end of the wait.',
+            },
+            selector: { type: 'string', description: 'Wait until an element matching this CSS selector is visible.' },
+            text: { type: 'string', description: 'Wait until visible text containing this string appears.' },
+            networkIdle: { type: 'boolean', description: 'Wait until the page stops issuing requests for 500ms.' },
+            timeoutMs: {
+                type: 'integer',
+                description: 'Upper bound for goal conditions: default 15000, max ' + String(config.maxWaitMs) + '.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => {
+                const outcome = value;
+                return [{ type: 'text', text: 'Waited for ' + outcome.waitedFor + ' (' + String(outcome.elapsedMs) + 'ms).' }];
             },
         },
-        output: { schema: { type: 'null' }, render: (_args, _value) => [{ type: 'text', text: 'Waited.' }] },
         async execute(args, exec) {
-            if (!Number.isSafeInteger(args.ms) || args.ms <= 0 || args.ms > config.maxWaitMs) {
-                throw new Error('browser_wait: ms must be a positive integer no larger than ' + String(config.maxWaitMs));
-            }
+            const condition = {
+                ...(args.ms === undefined ? {} : { ms: args.ms }),
+                ...(args.selector === undefined ? {} : { selector: args.selector }),
+                ...(args.text === undefined ? {} : { text: args.text }),
+                ...(args.networkIdle === undefined ? {} : { networkIdle: args.networkIdle }),
+                ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
+            };
+            // Validate before acquiring: a malformed call must not launch a browser.
+            const normalized = normalizeWaitCondition(condition, config.maxWaitMs);
             const session = await acquire(exec);
-            await session.wait(args.ms, exec.signal);
-            return null;
+            if (normalized.kind === 'ms') {
+                const started = Date.now();
+                await session.wait(normalized.ms, exec.signal);
+                return { waitedFor: describeWait(normalized), elapsedMs: Date.now() - started };
+            }
+            const outcome = await session.waitForCondition(condition, exec.signal);
+            return { waitedFor: outcome.waitedFor, elapsedMs: outcome.elapsedMs };
         },
     }));
     ctx.tools.register(defineTool({
         name: p('tabs'),
-        description: 'List the open tabs of this session with their indexes, URLs, and titles. The tab marked [active] is the page every other browser tool acts on.',
+        description: 'List open tabs: index, URL, title. [active] marks the tab every other tool acts on.',
         parameters: {},
         output: { schema: TABS_SCHEMA, render: renderTabsValue },
         async execute(_args, exec) {

package/lib/types.d.ts

@@ -117,6 +117,29 @@ export interface TabInfo {
     /** True for the tab the session currently drives. */
     readonly active: boolean;
 }
+/**
+ * What `browser_wait` should wait for. Exactly one of `ms`, `selector`, `text`
+ * or `networkIdle` per call; `timeoutMs` bounds the three goal conditions.
+ */
+export interface WaitCondition {
+    /** Fixed sleep in milliseconds (the pre-0.7.6 behaviour, unchanged). */
+    readonly ms?: number;
+    /** Wait until an element matching this CSS selector is visible. */
+    readonly selector?: string;
+    /** Wait until visible text containing this string appears. */
+    readonly text?: string;
+    /** Wait until the page stops issuing requests for 500ms. */
+    readonly networkIdle?: boolean;
+    /** Upper bound for a goal condition; defaults to 15000 and is capped by the deployment. */
+    readonly timeoutMs?: number;
+}
+/** What a completed wait reports back. */
+export interface WaitOutcome {
+    /** Human description of the satisfied condition. */
+    readonly waitedFor: string;
+    /** Wall-clock milliseconds the wait actually took. */
+    readonly elapsedMs: number;
+}
 /** PNG capture of a page or element. */
 export interface ScreenshotCapture {
     readonly mime: 'image/png';
@@ -200,6 +223,11 @@ export interface BrowserSession {
     forward(signal?: AbortSignal): Promise<BrowserSnapshot>;
     /** Wait a bounded duration, letting lazy content arrive. */
     wait(ms: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Wait for a goal instead of a duration: an element, a piece of text, or a
+     * quiet network. `wait(ms)` stays as it was, so this is purely additive.
+     */
+    waitForCondition(condition: WaitCondition, signal?: AbortSignal): Promise<WaitOutcome>;
     /** List open tabs. */
     tabs(): Promise<readonly TabInfo[]>;
     /** Activate the tab at the given index. */

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.5",
+  "version": "0.7.7",
   "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",