dsh-browser-playwright-codex 0.5.1

package/lib/cdp-policy.js

@@ -0,0 +1,105 @@
+/**
+ * CDP allow-list policy for browser_cdp.
+ *
+ * Raw CDP is a kernel-level remote control: some commands are read-only
+ * inspection / input simulation (safe), while others mutate browser or
+ * network state (cookies, request interception, storage, security) — far
+ * beyond what an agent should reach through a web tool. This module answers
+ * one question: may an agent send this CDP method?
+ *
+ * Default-deny, by exact name. Every allowed entry is a full method name and
+ * matching is plain equality, so a method this list has never heard of — a
+ * future Chromium command, a forged suffix, a whole-domain prefix — is denied
+ * without anyone having to notice it was added. The earlier policy matched
+ * `DOM.get` / `DOM.query` as families, which quietly authorised nine more DOM
+ * calls than the reviewed list and would have authorised every future member of
+ * those families as well.
+ *
+ * What is allowed, and why:
+ *   - DOM reads: geometry (getBoxModel, getContentQuads, getNodeForLocation),
+ *     node lookup (querySelector[All], describeNode, resolveNode), markup and
+ *     attribute reads (getOuterHTML, getAttributes) and the root tree.
+ *   - One DOM action: focus. It moves focus, the same class of effect as the
+ *     input events below, so it is a deliberate allow rather than a read.
+ *   - Input simulation, four methods only: Input.dispatchMouseEvent,
+ *     Input.dispatchKeyEvent, Input.dispatchTouchEvent, Input.insertText —
+ *     CDP-native trusted events. The Input domain as a whole is NOT allowed:
+ *     no family prefix, so Input.setIgnoreInputEvents, the gesture
+ *     synthesizers and any future Input.* mutation stay denied by default.
+ *   - Read-only helpers: Page.getLayoutMetrics, Page.getNavigationHistory,
+ *     Page.getFrameTree, CSS.getComputedStyleForNode.
+ *
+ * Everything else — Network.*, Storage.*, Security.*, Fetch.*, Target.*,
+ * Browser.*, Emulation.*, Runtime.evaluate, Page.navigate,
+ * Page.getResourceContent (it reads any frame's resource body),
+ * DOM.setFileInputFiles, the debugger-internal DOM calls (getDetachedDomNodes,
+ * getNodeStackTraces, getRelayoutBoundary, the container-query and anchor
+ * helpers …) — is rejected with CDP_DENIED. Growing this list is meant to be
+ * work: add the name here, add it to the reviewed list in
+ * tests/cdp-policy.test.ts (which asserts the two are equal), and say why.
+ * @module dsh-browser-playwright-codex/cdp-policy
+ */
+/**
+ * The allowed CDP methods, as exact names. Keep this explicit and reviewable:
+ * nothing here may be a family or domain prefix, and every entry must also
+ * appear in the reviewed list in tests/cdp-policy.test.ts.
+ *
+ * Frozen as a speed bump against accidental in-place edits at runtime. It is
+ * not a security boundary — the boundary is the matching rule below plus the
+ * tests that pin it; freezing only stops a typo from widening the list.
+ */
+export const CDP_ALLOWED_METHODS = Object.freeze([
+    // DOM reads.
+    'DOM.getDocument',
+    'DOM.getBoxModel',
+    'DOM.getNodeForLocation',
+    'DOM.getContentQuads',
+    'DOM.getOuterHTML',
+    'DOM.getAttributes',
+    'DOM.querySelector',
+    'DOM.querySelectorAll',
+    'DOM.describeNode',
+    'DOM.resolveNode',
+    // The one allowed DOM action (moves focus).
+    'DOM.focus',
+    // Input simulation: method-explicit, no family prefix.
+    'Input.dispatchMouseEvent',
+    'Input.dispatchKeyEvent',
+    'Input.dispatchTouchEvent',
+    'Input.insertText',
+    // Read-only page layout / history helpers and computed style.
+    'Page.getLayoutMetrics',
+    'Page.getNavigationHistory',
+    'Page.getFrameTree',
+    'CSS.getComputedStyleForNode',
+]);
+/** Human summary for the tool description and denial diagnostics. */
+export const CDP_ALLOW_SUMMARY = 'DOM inspection (geometry / node lookup / attributes / markup) plus the four trusted input events (Input.dispatchMouseEvent / Input.dispatchKeyEvent / Input.dispatchTouchEvent / Input.insertText) and read-only Page / CSS helpers, matched by exact name with no family prefixes';
+/**
+ * Decide whether an agent may send the given CDP method.
+ *
+ * Exact equality only. The shape check comes first, so a non-string (an object
+ * with a toString, a number, a null) is denied without ever being evaluated.
+ * There is deliberately no prefix, family or suffix rule: a name that is not
+ * written out above does not pass, no matter who adds it to Chromium.
+ * @param method - CDP method name, e.g. "DOM.getNodeForLocation".
+ * @returns true when the method is exactly one of the allowed names.
+ */
+export function isCdpMethodAllowed(method) {
+    if (typeof method !== 'string' || method.length === 0)
+        return false;
+    return CDP_ALLOWED_METHODS.includes(method);
+}
+/**
+ * Describe a denied method for the error message: name the allow-list family
+ * so the model learns the boundary instead of guessing.
+ */
+export function cdpDenialMessage(method) {
+    return ('browser_cdp method ' +
+        JSON.stringify(method) +
+        ' is not in the allow-list (' +
+        CDP_ALLOW_SUMMARY +
+        '). ' +
+        'If you need it, it is intentionally blocked: raw CDP network/storage/security commands can mutate cookies, ' +
+        'intercept traffic or read stored data, which the agent must not do through this tool.');
+}

package/lib/compat.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Boundary adapter for the branded identifiers this plugin borrows from the
+ * DeepSeek Harness. The harness ships a release every few days and renames
+ * freely — `CallId` became `ToolCallId`, brand constructors moved to
+ * `@deepseek-ai/dsh-brand` — and a renamed identifier used to break an import
+ * in the middle of the tests.
+ *
+ * Scope, stated honestly: this file owns the *identifier brands* (below).
+ * The harness API surface this plugin uses on purpose (cordis `Context`,
+ * `defineTool` / `ToolExecution`, `BlockAssembler`, `createUserMessage`) is
+ * still imported directly at its call site — a rename there is a load-time
+ * failure that `npm run doctor` reports as a missing export, which is the
+ * signal we want rather than a silent `undefined`.
+ *
+ * `CallId` / `ToolCallId` are nominal wrappers over a string whose runtime body
+ * is the identity function, so this plugin defines its own instead of importing
+ * theirs — a harness rename cannot break it, and no version range has to be
+ * chased.
+ * @module dsh-browser-playwright-codex/compat
+ */
+/**
+ * Correlates one model-issued tool call with its result. Structurally
+ * compatible with the harness brand, owned by this plugin so the harness
+ * cannot rename it out from under the tests.
+ */
+export type ToolCallId = string & {
+    readonly __brand?: 'ToolCallId';
+};
+/**
+ * Brand a string as a {@link ToolCallId}. Runtime identity, exactly like the
+ * harness brand constructor it replaces.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string, branded.
+ */
+export declare function toolCallId(id: string): ToolCallId;
+/** Historical alias: the 0.1.6-and-earlier name, kept so call sites read the same. */
+export declare const CallId: typeof toolCallId;

package/lib/compat.js

@@ -0,0 +1,31 @@
+/**
+ * Boundary adapter for the branded identifiers this plugin borrows from the
+ * DeepSeek Harness. The harness ships a release every few days and renames
+ * freely — `CallId` became `ToolCallId`, brand constructors moved to
+ * `@deepseek-ai/dsh-brand` — and a renamed identifier used to break an import
+ * in the middle of the tests.
+ *
+ * Scope, stated honestly: this file owns the *identifier brands* (below).
+ * The harness API surface this plugin uses on purpose (cordis `Context`,
+ * `defineTool` / `ToolExecution`, `BlockAssembler`, `createUserMessage`) is
+ * still imported directly at its call site — a rename there is a load-time
+ * failure that `npm run doctor` reports as a missing export, which is the
+ * signal we want rather than a silent `undefined`.
+ *
+ * `CallId` / `ToolCallId` are nominal wrappers over a string whose runtime body
+ * is the identity function, so this plugin defines its own instead of importing
+ * theirs — a harness rename cannot break it, and no version range has to be
+ * chased.
+ * @module dsh-browser-playwright-codex/compat
+ */
+/**
+ * Brand a string as a {@link ToolCallId}. Runtime identity, exactly like the
+ * harness brand constructor it replaces.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string, branded.
+ */
+export function toolCallId(id) {
+    return id;
+}
+/** Historical alias: the 0.1.6-and-earlier name, kept so call sites read the same. */
+export const CallId = toolCallId;

package/lib/contract.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The browser capability's wire contract in one place: the tool names it
+ * registers and the failure codes it can raise. Registration, the load-time
+ * guard, the regression suites and the standalone verify script all read this
+ * module, so a renamed tool or a changed code cannot drift apart silently.
+ * @module dsh-browser-playwright-codex/contract
+ */
+/**
+ * Tool name suffixes in registration order; a wire name is `prefix + suffix`.
+ * Gated suffixes are kept in the same list so the full surface stays visible.
+ */
+export declare const TOOL_SUFFIXES: readonly ["navigate", "snapshot", "click", "dialog", "click_at", "hover", "fill", "press", "scroll", "back", "forward", "wait", "tabs", "switch_tab", "open_tab", "close_tab", "screenshot", "extract", "evaluate", "cdp", "console_messages", "network_requests", "close"];
+/** One tool name suffix. */
+export type ToolSuffix = (typeof TOOL_SUFFIXES)[number];
+/**
+ * Suffixes registered unconditionally. They are always in the system prompt,
+ * so this list is also the resident schema cost of the plugin.
+ */
+export declare const ALWAYS_ON_SUFFIXES: readonly ["navigate", "snapshot", "click", "dialog", "click_at", "hover", "fill", "press", "scroll", "back", "forward", "wait", "tabs", "switch_tab", "open_tab", "close_tab", "screenshot", "console_messages", "network_requests", "close"];
+/**
+ * Suffixes registered only when their capability is enabled (or configured):
+ * a tool the deployment disabled can only error, so shipping its schema would
+ * spend prompt tokens on a capability that cannot run.
+ */
+export declare const GATED_SUFFIXES: readonly ["extract", "evaluate", "cdp"];
+/** Which gated capabilities are live for one configuration. */
+export interface ToolSurfaceConfig {
+    /** allowEvaluate: registers browser_evaluate when true. */
+    allowEvaluate: boolean;
+    /** allowCdp: registers browser_cdp when true. */
+    allowCdp: boolean;
+    /** extract.provider and extract.model both set: registers browser_extract. */
+    extractConfigured: boolean;
+    /** Force every gated tool to register even when its capability is off. */
+    registerDisabledTools: boolean;
+}
+/** Full wire names for every tool, in registration order. */
+export declare function toolNames(prefix: string): string[];
+/** Suffixes this configuration actually registers, in registration order. */
+export declare function registeredSuffixes(config: ToolSurfaceConfig): ToolSuffix[];
+/** Full wire names this configuration registers, in registration order. */
+export declare function registeredToolNames(prefix: string, config: ToolSurfaceConfig): string[];
+/**
+ * Stable machine-readable browser failure codes. Model-visible text never
+ * keys off these strings, so tests and tools can rely on them as an API.
+ */
+export declare const ERROR_CODES: {
+    readonly NO_PROVIDER: "NO_PROVIDER";
+    readonly AMBIGUOUS_PROVIDER: "AMBIGUOUS_PROVIDER";
+    readonly CONFIGURED_PROVIDER_MISSING: "CONFIGURED_PROVIDER_MISSING";
+    readonly CONFIGURED_PROVIDER_UNAVAILABLE: "CONFIGURED_PROVIDER_UNAVAILABLE";
+    readonly NO_BROWSER: "NO_BROWSER";
+    readonly BROWSER_LAUNCH_FAILED: "BROWSER_LAUNCH_FAILED";
+    readonly NAVIGATION_TIMEOUT: "NAVIGATION_TIMEOUT";
+    readonly ACTION_TIMEOUT: "ACTION_TIMEOUT";
+    readonly REF_NOT_FOUND: "REF_NOT_FOUND";
+    readonly URL_NOT_ALLOWED: "URL_NOT_ALLOWED";
+    readonly EVALUATE_DISABLED: "EVALUATE_DISABLED";
+    readonly SESSION_CLOSED: "SESSION_CLOSED";
+    readonly DISABLED: "DISABLED";
+    readonly BROWSER_CRASHED: "BROWSER_CRASHED";
+    readonly PARAM_MISSING: "PARAM_MISSING";
+    readonly ELEMENT_NOT_ACTIONABLE: "ELEMENT_NOT_ACTIONABLE";
+    readonly VALUE_NOT_SET: "VALUE_NOT_SET";
+    readonly CLICK_TARGET_NOT_FOUND: "CLICK_TARGET_NOT_FOUND";
+    readonly HOVER_TARGET_NOT_FOUND: "HOVER_TARGET_NOT_FOUND";
+    readonly DIALOG_PENDING: "DIALOG_PENDING";
+    readonly NO_DIALOG: "NO_DIALOG";
+    readonly CDP_DISABLED: "CDP_DISABLED";
+    readonly CDP_DENIED: "CDP_DENIED";
+    readonly CDP_ERROR: "CDP_ERROR";
+};
+/** One machine-readable failure code. */
+export type BrowserErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];

package/lib/contract.js

@@ -0,0 +1,117 @@
+/**
+ * The browser capability's wire contract in one place: the tool names it
+ * registers and the failure codes it can raise. Registration, the load-time
+ * guard, the regression suites and the standalone verify script all read this
+ * module, so a renamed tool or a changed code cannot drift apart silently.
+ * @module dsh-browser-playwright-codex/contract
+ */
+/**
+ * Tool name suffixes in registration order; a wire name is `prefix + suffix`.
+ * Gated suffixes are kept in the same list so the full surface stays visible.
+ */
+export const TOOL_SUFFIXES = [
+    'navigate',
+    'snapshot',
+    'click',
+    'dialog',
+    'click_at',
+    'hover',
+    'fill',
+    'press',
+    'scroll',
+    'back',
+    'forward',
+    'wait',
+    'tabs',
+    'switch_tab',
+    'open_tab',
+    'close_tab',
+    'screenshot',
+    'extract',
+    'evaluate',
+    'cdp',
+    'console_messages',
+    'network_requests',
+    'close',
+];
+/**
+ * Suffixes registered unconditionally. They are always in the system prompt,
+ * so this list is also the resident schema cost of the plugin.
+ */
+export const ALWAYS_ON_SUFFIXES = [
+    'navigate',
+    'snapshot',
+    'click',
+    'dialog',
+    'click_at',
+    'hover',
+    'fill',
+    'press',
+    'scroll',
+    'back',
+    'forward',
+    'wait',
+    'tabs',
+    'switch_tab',
+    'open_tab',
+    'close_tab',
+    'screenshot',
+    'console_messages',
+    'network_requests',
+    'close',
+];
+/**
+ * Suffixes registered only when their capability is enabled (or configured):
+ * a tool the deployment disabled can only error, so shipping its schema would
+ * spend prompt tokens on a capability that cannot run.
+ */
+export const GATED_SUFFIXES = ['extract', 'evaluate', 'cdp'];
+/** Full wire names for every tool, in registration order. */
+export function toolNames(prefix) {
+    return TOOL_SUFFIXES.map((suffix) => prefix + suffix);
+}
+/** Suffixes this configuration actually registers, in registration order. */
+export function registeredSuffixes(config) {
+    const live = new Set(ALWAYS_ON_SUFFIXES);
+    if (config.allowEvaluate || config.registerDisabledTools)
+        live.add('evaluate');
+    if (config.allowCdp || config.registerDisabledTools)
+        live.add('cdp');
+    if (config.extractConfigured || config.registerDisabledTools)
+        live.add('extract');
+    return TOOL_SUFFIXES.filter((suffix) => live.has(suffix));
+}
+/** Full wire names this configuration registers, in registration order. */
+export function registeredToolNames(prefix, config) {
+    return registeredSuffixes(config).map((suffix) => prefix + suffix);
+}
+/**
+ * Stable machine-readable browser failure codes. Model-visible text never
+ * keys off these strings, so tests and tools can rely on them as an API.
+ */
+export const ERROR_CODES = {
+    NO_PROVIDER: 'NO_PROVIDER',
+    AMBIGUOUS_PROVIDER: 'AMBIGUOUS_PROVIDER',
+    CONFIGURED_PROVIDER_MISSING: 'CONFIGURED_PROVIDER_MISSING',
+    CONFIGURED_PROVIDER_UNAVAILABLE: 'CONFIGURED_PROVIDER_UNAVAILABLE',
+    NO_BROWSER: 'NO_BROWSER',
+    BROWSER_LAUNCH_FAILED: 'BROWSER_LAUNCH_FAILED',
+    NAVIGATION_TIMEOUT: 'NAVIGATION_TIMEOUT',
+    ACTION_TIMEOUT: 'ACTION_TIMEOUT',
+    REF_NOT_FOUND: 'REF_NOT_FOUND',
+    URL_NOT_ALLOWED: 'URL_NOT_ALLOWED',
+    EVALUATE_DISABLED: 'EVALUATE_DISABLED',
+    SESSION_CLOSED: 'SESSION_CLOSED',
+    DISABLED: 'DISABLED',
+    BROWSER_CRASHED: 'BROWSER_CRASHED',
+    PARAM_MISSING: 'PARAM_MISSING',
+    ELEMENT_NOT_ACTIONABLE: 'ELEMENT_NOT_ACTIONABLE',
+    VALUE_NOT_SET: 'VALUE_NOT_SET',
+    CLICK_TARGET_NOT_FOUND: 'CLICK_TARGET_NOT_FOUND',
+    HOVER_TARGET_NOT_FOUND: 'HOVER_TARGET_NOT_FOUND',
+    DIALOG_PENDING: 'DIALOG_PENDING',
+    NO_DIALOG: 'NO_DIALOG',
+    CDP_DISABLED: 'CDP_DISABLED',
+    CDP_DENIED: 'CDP_DENIED',
+    CDP_ERROR: 'CDP_ERROR',
+};

package/lib/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Error taxonomy for the browser capability. Every failure the model can
+ * encounter carries a stable, provider-neutral code plus a human-readable
+ * message; tools translate these onto the wire without exposing internals.
+ * The code list lives in `contract.ts` so registration, tests and the verify
+ * script share one source of truth.
+ * @module dsh-browser-playwright-codex/errors
+ */
+import type { BrowserErrorCode } from './contract.ts';
+/** Stable machine-readable browser failure codes. */
+export type { BrowserErrorCode };
+/**
+ * Error thrown by every browser-capability operation. Tools surface the
+ * code as structured diagnostics; the message stays model-visible prose.
+ */
+export declare class BrowserError extends Error {
+    readonly code: BrowserErrorCode;
+    /**
+     * @param code - stable machine-readable failure code.
+     * @param message - non-empty human-readable failure summary.
+     */
+    constructor(code: BrowserErrorCode, message: string);
+}
+/** Wrap an unknown cause into a launch failure with the code preserved. */
+export declare function launchFailed(cause: unknown): BrowserError;

package/lib/errors.js

@@ -0,0 +1,21 @@
+/**
+ * Error thrown by every browser-capability operation. Tools surface the
+ * code as structured diagnostics; the message stays model-visible prose.
+ */
+export class BrowserError extends Error {
+    code;
+    /**
+     * @param code - stable machine-readable failure code.
+     * @param message - non-empty human-readable failure summary.
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = 'BrowserError';
+        this.code = code;
+    }
+}
+/** Wrap an unknown cause into a launch failure with the code preserved. */
+export function launchFailed(cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return new BrowserError('BROWSER_LAUNCH_FAILED', 'failed to launch the browser: ' + detail);
+}

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * dsh-browser-playwright-codex: Playwright-powered browser capability for
+ * DeepSeek Harness. Snapshot-first interaction with stable element refs,
+ * session-scoped browser contexts, screenshots as attachments.
+ * @module dsh-browser-playwright-codex
+ */
+export { BrowserError, launchFailed } from './errors.ts';
+export type { BrowserErrorCode } from './errors.ts';
+export { ALWAYS_ON_SUFFIXES, ERROR_CODES, GATED_SUFFIXES, TOOL_SUFFIXES, registeredSuffixes, registeredToolNames, toolNames, } from './contract.ts';
+export type { ToolSuffix, ToolSurfaceConfig } from './contract.ts';
+export { CallId, toolCallId } from './compat.ts';
+export type { ToolCallId } from './compat.ts';
+export { SNAPSHOT_SCRIPT } from './injected.ts';
+export type { SnapshotOptions, PageDataOptions } from './injected.ts';
+export { default as BrowserRuntime } from './service.ts';
+export type { BrowserRuntimeConfig } from './service.ts';
+export { PlaywrightProvider, assertAllowedUrl, Config as PlaywrightConfigSchema } from './playwright.ts';
+export type { PlaywrightConfig, PageData } from './playwright.ts';
+export type { BrowserNode, BrowserProvider, BrowserSession, BrowserSnapshot, LoadState, ScreenshotCapture, TabInfo, } from './types.ts';
+export type { ToolConfig } from './tool.ts';

package/lib/index.js

@@ -0,0 +1,12 @@
+/**
+ * dsh-browser-playwright-codex: Playwright-powered browser capability for
+ * DeepSeek Harness. Snapshot-first interaction with stable element refs,
+ * session-scoped browser contexts, screenshots as attachments.
+ * @module dsh-browser-playwright-codex
+ */
+export { BrowserError, launchFailed } from "./errors.js";
+export { ALWAYS_ON_SUFFIXES, ERROR_CODES, GATED_SUFFIXES, TOOL_SUFFIXES, registeredSuffixes, registeredToolNames, toolNames, } from "./contract.js";
+export { CallId, toolCallId } from "./compat.js";
+export { SNAPSHOT_SCRIPT } from "./injected.js";
+export { default as BrowserRuntime } from "./service.js";
+export { PlaywrightProvider, assertAllowedUrl, Config as PlaywrightConfigSchema } from "./playwright.js";

package/lib/injected.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Injected page-context snapshot engine, installed through addInitScript.
+ * It is plain JavaScript: it runs inside the page, never in Node. Each
+ * snapshot call assigns stable data-dsh-ref attributes to actionable
+ * elements in document order and returns a pruned role/name tree. Names come
+ * from the element itself first, then from its descendants for actionable
+ * elements whose own text is empty (so a label one level down still lands on
+ * the line that carries the ref). A child that merely repeats an ancestor
+ * name is folded, and container roles (select options, table rows) are never
+ * named from their content.
+ * @module dsh-browser-playwright-codex/injected
+ */
+/** Options passed from the provider into one snapshot call. */
+export interface SnapshotOptions {
+    /** Include only actionable (ref-carrying) elements. */
+    readonly interactiveOnly?: boolean;
+    /** Maximum nodes in the returned tree. */
+    readonly maxNodes?: number;
+    /** Maximum characters kept per accessible name. */
+    readonly maxNameLength?: number;
+    /** Maximum characters kept per text block. */
+    readonly maxTextLength?: number;
+}
+/** Options for the bounded page-data extraction. */
+export interface PageDataOptions {
+    readonly maxTextChars?: number;
+    readonly maxLinks?: number;
+    readonly maxInputs?: number;
+}
+/**
+ * The browser-side snapshot script. Installed with page.addInitScript and
+ * invoked as window.__dshSnapshot(opts). The returned value crosses the
+ * evaluate boundary as plain JSON.
+ */
+export declare const SNAPSHOT_SCRIPT: string;