dsh-browser-playwright-codex 0.7.4 → 0.7.6

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';
@@ -60,6 +60,32 @@ export declare class PlaywrightSession {
     /** Nonce of the baseline ref space; a change means navigation reset. */
     lastRefNonce: string | undefined;
     constructor(provider: PlaywrightProvider, owner: string, context: BrowserContext);
+    /**
+     * Turn a navigation the host guard refused into a named refusal.
+     *
+     * A page can navigate itself (location.href, meta refresh, a form submit, a
+     * 302) without passing any entry-point check. The guard stops the document
+     * request; this reports it, so "I clicked and nothing happened" becomes
+     * URL_NOT_ALLOWED naming the host. Consumed once: a later action must not
+     * inherit an earlier refusal.
+     */
+    throwIfNavigationBlocked(): void;
+    /**
+     * Refuse to go on driving a page that is outside the allow-list.
+     *
+     * The request-level guard (navigation-guard.ts) catches navigations started
+     * from inside the page, but NOT a redirect the browser follows on its own:
+     * measured 2026-10-26, `context.route()` never sees the hop after a
+     * `continue()`d request, so `127.0.0.1/x` answering `302 → localhost/y` lands
+     * on the disallowed host with no route event at all. So every action that
+     * settles a page also checks where it actually ended up.
+     *
+     * The off-list page is abandoned for about:blank (hostless, always allowed)
+     * instead of being left there: otherwise the session would wedge on a page it
+     * may never drive, and "navigate somewhere allowed" could not fix it.
+     * @param page - the page this action ran on.
+     */
+    assertCurrentUrlAllowed(page: Page): Promise<void>;
     /**
      * The session's cookies, reduced to what the login inference needs. `value` is dropped here,
      * at the only place cookies enter the summary path, so nothing downstream can leak it.
@@ -248,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;
@@ -278,9 +310,13 @@ export declare class PlaywrightSession {
      * Send one raw CDP command on the current page's session and return its
      * result. This is the "direct protocol" escape hatch behind every other
      * tool — the model can inspect geometry, dispatch trusted input events or
-     * query the DOM the same way Chrome DevTools does. Policy (which methods
-     * are allowed) lives in the tool layer via lib/cdp-policy.js; this method
-     * itself performs no filtering so internal callers keep full control.
+     * query the DOM the same way Chrome DevTools does.
+     *
+     * Both rules live here as well as in the tool layer, deliberately: the
+     * allow-list and the switch must hold for anything that reaches this method,
+     * not just for the registered tool. Before 2026-10-26 only `browser_cdp`
+     * checked them, so a caller working through the service could send
+     * `Runtime.evaluate` — arbitrary JavaScript — with the switch off (measured).
      */
     cdp(method: string, params: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
     close(): Promise<void>;

package/lib/session.js

@@ -1,11 +1,14 @@
 import { looksLikeToken, registrableDomain } from "./login-sites.js";
-import { BrowserError } from "./errors.js";
+import { BrowserError, cdpDisabled, evaluateDisabled } from "./errors.js";
+import { isCdpMethodAllowed, cdpDenialMessage } from "./cdp-policy.js";
+import { getGates } from "./runtime-state.js";
 import { asTimeoutError, isAbortError, isContextDestroyed, isCrashError } from "./page-diagnostics.js";
 import { consoleMessages, networkRequests, pageData, trackPage } from "./page-diagnostics.js";
 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 } from "./url-policy.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;
@@ -55,6 +58,66 @@ export class PlaywrightSession {
         this.owner = owner;
         this.context = context;
     }
+    /**
+     * Turn a navigation the host guard refused into a named refusal.
+     *
+     * A page can navigate itself (location.href, meta refresh, a form submit, a
+     * 302) without passing any entry-point check. The guard stops the document
+     * request; this reports it, so "I clicked and nothing happened" becomes
+     * URL_NOT_ALLOWED naming the host. Consumed once: a later action must not
+     * inherit an earlier refusal.
+     */
+    throwIfNavigationBlocked() {
+        const refused = this.provider.takeBlockedNavigation();
+        if (refused === undefined)
+            return;
+        throw new BrowserError('URL_NOT_ALLOWED', 'the page tried to navigate to ' +
+            refused.url +
+            ' and was blocked: host ' +
+            refused.host +
+            ' is not in allowedDomains. Nothing left this site — the request was stopped before it reached the network. ' +
+            'The page you were on is unchanged; tell the user the site tried to leave the allow-list.');
+    }
+    /**
+     * Refuse to go on driving a page that is outside the allow-list.
+     *
+     * The request-level guard (navigation-guard.ts) catches navigations started
+     * from inside the page, but NOT a redirect the browser follows on its own:
+     * measured 2026-10-26, `context.route()` never sees the hop after a
+     * `continue()`d request, so `127.0.0.1/x` answering `302 → localhost/y` lands
+     * on the disallowed host with no route event at all. So every action that
+     * settles a page also checks where it actually ended up.
+     *
+     * The off-list page is abandoned for about:blank (hostless, always allowed)
+     * instead of being left there: otherwise the session would wedge on a page it
+     * may never drive, and "navigate somewhere allowed" could not fix it.
+     * @param page - the page this action ran on.
+     */
+    async assertCurrentUrlAllowed(page) {
+        const raw = page.url();
+        if (raw === '')
+            return;
+        let target;
+        try {
+            target = new URL(raw);
+        }
+        catch {
+            return;
+        }
+        if (target.protocol !== 'http:' && target.protocol !== 'https:')
+            return;
+        const allowedDomains = this.provider.config.allowedDomains ?? [];
+        if (isHostAllowed(target.hostname, allowedDomains))
+            return;
+        await page.goto('about:blank').catch(() => { });
+        throw new BrowserError('URL_NOT_ALLOWED', 'the page ended up on host ' +
+            target.hostname +
+            ' (' +
+            raw +
+            '), which is not in allowedDomains — a redirect the browser followed on its own. ' +
+            'The tab has been reset to about:blank, so nothing outside the allow-list stays reachable. ' +
+            'Tell the user: the site tried to send this session off the allow-list.');
+    }
     /**
      * The session's cookies, reduced to what the login inference needs. `value` is dropped here,
      * at the only place cookies enter the summary path, so nothing downstream can leak it.
@@ -120,6 +183,9 @@ export class PlaywrightSession {
     }
     /** Run one operation under busy tracking: idle disposal defers until it settles. */
     run(operation) {
+        // Every action starts from a clean slate: a refusal recorded during an
+        // earlier action must not be reported as this one's outcome.
+        this.provider.blockedNavigation = undefined;
         this.provider.beginOp(this.owner);
         return Promise.resolve()
             .then(operation)
@@ -431,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();
@@ -491,6 +565,14 @@ export class PlaywrightSession {
         return pageData(this);
     }
     async evaluate(expression, signal) {
+        // The switch is enforced HERE, not only in the tool layer: browser_evaluate
+        // used to be guarded by tool.ts alone, so anything holding the service (a
+        // sibling plugin, a script) could run arbitrary page JavaScript with the
+        // user's logins while the setting said off (measured 2026-10-26). An
+        // unpublished gate set counts as OFF — a deployment that never said yes has
+        // not said yes.
+        if (!(getGates()?.allowEvaluate ?? false))
+            throw evaluateDisabled();
         return this.run(async () => {
             this.assertLive();
             this.provider.touch(this.owner);
@@ -511,11 +593,19 @@ export class PlaywrightSession {
      * Send one raw CDP command on the current page's session and return its
      * result. This is the "direct protocol" escape hatch behind every other
      * tool — the model can inspect geometry, dispatch trusted input events or
-     * query the DOM the same way Chrome DevTools does. Policy (which methods
-     * are allowed) lives in the tool layer via lib/cdp-policy.js; this method
-     * itself performs no filtering so internal callers keep full control.
+     * query the DOM the same way Chrome DevTools does.
+     *
+     * Both rules live here as well as in the tool layer, deliberately: the
+     * allow-list and the switch must hold for anything that reaches this method,
+     * not just for the registered tool. Before 2026-10-26 only `browser_cdp`
+     * checked them, so a caller working through the service could send
+     * `Runtime.evaluate` — arbitrary JavaScript — with the switch off (measured).
      */
     async cdp(method, params, signal) {
+        if (!(getGates()?.allowCdp ?? false))
+            throw cdpDisabled();
+        if (!isCdpMethodAllowed(method))
+            throw new BrowserError('CDP_DENIED', cdpDenialMessage(method));
         return this.run(async () => {
             this.assertLive();
             this.provider.touch(this.owner);

package/lib/settings-card.js

@@ -148,7 +148,9 @@ function registerDiskRoutes(ctx) {
                 sendJson(res, 200, { ...report, browserActive: getEnabled() === true });
             }
             catch (error) {
-                sendJson(res, 500, { error: { code: 'DISK_SCAN', message: String(error && error.message ? error.message : error) } });
+                sendJson(res, 500, {
+                    error: { code: 'DISK_SCAN', message: String(error && error.message ? error.message : error) },
+                });
             }
         },
     }));
@@ -177,15 +179,24 @@ function registerDiskRoutes(ctx) {
             const targets = [];
             for (const value of payload.targets) {
                 if (!isTargetId(value))
-                    return sendJson(res, 400, { error: { code: 'UNKNOWN_TARGET', message: 'unknown target: ' + String(value) } });
+                    return sendJson(res, 400, {
+                        error: { code: 'UNKNOWN_TARGET', message: 'unknown target: ' + String(value) },
+                    });
                 targets.push(value);
             }
             try {
-                const report = await clean({ ...diskPaths(), targets, dryRun: payload.dryRun, browserActive: getEnabled() === true });
+                const report = await clean({
+                    ...diskPaths(),
+                    targets,
+                    dryRun: payload.dryRun,
+                    browserActive: getEnabled() === true,
+                });
                 sendJson(res, 200, report);
             }
             catch (error) {
-                sendJson(res, 500, { error: { code: 'DISK_CLEAN', message: String(error && error.message ? error.message : error) } });
+                sendJson(res, 500, {
+                    error: { code: 'DISK_CLEAN', message: String(error && error.message ? error.message : error) },
+                });
             }
         },
     }));

package/lib/tool.js

@@ -1,7 +1,7 @@
 import z from '@deepseek-ai/schemastery';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm';
-import { BrowserError } from "./errors.js";
+import { BrowserError, cdpDisabled, evaluateDisabled } from "./errors.js";
 import { registeredSuffixes } from "./contract.js";
 import { getEnabled, publishGates, publishLoginSites } from "./runtime-state.js";
 import { summarizeLoginSites } from "./login-sites.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. */
@@ -58,12 +59,17 @@ export function apply(ctx, config) {
     // Tell the Settings page what is actually in effect. It cannot read this
     // config itself (the value may come from a bundle patch, a profile patch or a
     // home-level patch), so the tool family publishes it at registration and the
-    // switch shows the truth instead of a guess. Driven by the same values that
-    // decided which tools register, so the two can never disagree.
+    // switch shows the truth instead of a guess.
+    //
+    // These are the CAPABILITY values, not `registered.has(...)`: the session
+    // layer enforces the switch too, and `registerDisabledTools` deliberately
+    // registers a switched-off tool so the model can discover it. Reading
+    // registration as permission published "on" for a gate that was off — the
+    // settings card showed a switch that was not there.
     publishGates({
-        allowEvaluate: registered.has('evaluate'),
-        allowCdp: registered.has('cdp'),
-        diagnostics: registered.has('console_messages'),
+        allowEvaluate: config.allowEvaluate,
+        allowCdp: config.allowCdp,
+        diagnostics: config.diagnostics,
     });
     /** Register one gated tool only when this configuration keeps it live. */
     const registerMaybe = (suffix, definition) => {
@@ -119,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: {
@@ -140,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',
@@ -184,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',
@@ -205,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 },
@@ -237,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',
@@ -266,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: {
@@ -356,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) {
@@ -547,7 +572,7 @@ export function apply(ctx, config) {
         },
         async execute(args, exec) {
             if (!config.allowEvaluate) {
-                throw new BrowserError('EVALUATE_DISABLED', 'browser_evaluate is disabled; set allowEvaluate: true on the browser-tool plugin to enable arbitrary page JavaScript');
+                throw evaluateDisabled();
             }
             const session = await acquire(exec);
             return (await session.evaluate(args.expression, exec.signal));
@@ -583,7 +608,7 @@ export function apply(ctx, config) {
         },
         async execute(args, exec) {
             if (!config.allowCdp) {
-                throw new BrowserError('CDP_DISABLED', 'browser_cdp is disabled; set allowCdp: true on the browser-tool plugin to enable raw CDP inspection commands');
+                throw cdpDisabled();
             }
             if (!isCdpMethodAllowed(args.method)) {
                 throw new BrowserError('CDP_DENIED', cdpDenialMessage(args.method));

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/url-policy.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Is this host inside the allow-list? Empty list means "any host".
+ *
+ * Suffix matching is deliberately anchored one level down: `example.com`
+ * admits `example.com` and `a.example.com`, never `notexample.com` and never
+ * `example.com.evil.net`. A configured entry is compared after
+ * normalisation (lower case, leading dot dropped), because a user writing
+ * `.example.com` means the domain, not a subdomain literally named "example".
+ * @param host - hostname to test, e.g. "a.example.com".
+ * @param allowedDomains - configured suffixes; empty means everything passes.
+ * @returns true when the host is allowed.
+ */
+export declare function isHostAllowed(host: string, allowedDomains: readonly string[]): boolean;
 /** Validate one absolute URL against the navigation policy. */
 export declare function assertAllowedUrl(raw: string, allowedDomains: readonly string[]): URL;

package/lib/url-policy.js

@@ -3,6 +3,29 @@
  * @module dsh-browser-playwright-codex/url-policy
  */
 import { BrowserError } from "./errors.js";
+/**
+ * Is this host inside the allow-list? Empty list means "any host".
+ *
+ * Suffix matching is deliberately anchored one level down: `example.com`
+ * admits `example.com` and `a.example.com`, never `notexample.com` and never
+ * `example.com.evil.net`. A configured entry is compared after
+ * normalisation (lower case, leading dot dropped), because a user writing
+ * `.example.com` means the domain, not a subdomain literally named "example".
+ * @param host - hostname to test, e.g. "a.example.com".
+ * @param allowedDomains - configured suffixes; empty means everything passes.
+ * @returns true when the host is allowed.
+ */
+export function isHostAllowed(host, allowedDomains) {
+    if (allowedDomains.length === 0)
+        return true;
+    const target = host.toLowerCase();
+    return allowedDomains.some((raw) => {
+        const suffix = raw.trim().toLowerCase().replace(/^\.+/, '');
+        if (suffix === '')
+            return false;
+        return target === suffix || target.endsWith('.' + suffix);
+    });
+}
 /** Validate one absolute URL against the navigation policy. */
 export function assertAllowedUrl(raw, allowedDomains) {
     let parsed;
@@ -17,8 +40,7 @@ export function assertAllowedUrl(raw, allowedDomains) {
     }
     if (allowedDomains.length > 0) {
         const host = parsed.hostname.toLowerCase();
-        const allowed = allowedDomains.some((suffix) => host === suffix || host.endsWith('.' + suffix));
-        if (!allowed) {
+        if (!isHostAllowed(host, allowedDomains)) {
             throw new BrowserError('URL_NOT_ALLOWED', 'host ' + parsed.hostname + ' is not in allowedDomains');
         }
     }