browser-skill · diff

git:20260911.fd69d7d to git:20260911.0170852

28 added, 45 removed. Audit A to A.

---

name: browser-skill

description: Browser automation through six injected domain tools.

---

# browser-skill for DeepSeek Harness

- Drive the user's logged-in Chromium through this plugin's structured browser tools. Automation is

- isolated in an Agent Window; user-window tabs remain protected unless explicitly borrowed.

- Loading this skill reveals six tools for the rest of the conversation:

- - `browser_session` owns session lifecycle.

- - `browser_page` handles navigation and lifecycle waits.

- - `browser_inspect` reads semantic, visual, console, and network state.

- - `browser_interact` performs normal page interactions.

- - `browser_tabs` manages Agent Window tabs and temporary user-tab borrowing.

- - `browser_assist` handles human help, window size, and device emulation.

+ Drive the user's logged-in Chromium in an Agent Window. User-window tabs remain protected unless

+ explicitly borrowed.

- Every call includes an `action`. Treat each loaded tool schema as authoritative for its actions and

- parameters; do not guess fields. All browser work must use the injected tools directly so session

- ownership, cancellation, attachments, observation UI, and cleanup remain intact. Do not invoke

- another process to control the browser.

+ Use the loaded `action` schemas for `browser_session`, `browser_page`, `browser_inspect`,

+ `browser_interact`, `browser_tabs`, and `browser_assist`; do not guess parameters.

+ All browser work must use the injected tools directly to preserve ownership, cancellation,

+ attachments, observation UI, and cleanup. Do not invoke another process to control the browser.

## Mandatory workflow

Every task owns a bounded plugin session:

```text

browser_session({ action: "start", ... })

... use the returned sessionId for browser work ...

browser_session({ action: "stop", session: sessionId })

```

- Pass the session explicitly when more than one exists. Never guess or reuse an id owned by another

- program. Stop in a finally-style path on success and failure unless the user explicitly asks to keep

- the session open. Stopping also returns borrowed tabs.

+ Pass the session when more than one exists; never guess or use another program's id. Stop on

+ success and failure unless asked to keep it open. Stopping also returns borrowed tabs.

## Work toward one observable goal

- Derive a concrete success condition from the user's request.

- - Take the shortest purposeful path: observe, act, then make at most one observation to confirm an

- ambiguous result.

- - Once success is visible, do not click, refresh, navigate, switch tabs, or perform extra checks.

- - If a human-only step appears or two attempts make no progress, request help instead of

- brute-forcing.

+ - Observe, act, and check ambiguous results once.

+ - Stop acting once success is visible.

+ - With help enabled, request help for human-only steps or after two attempts make no progress.

+ With help disabled, use the autonomous handling rules below.

## Observe, act, observe

Use `browser_inspect` action `observe` as the primary semantic page view. It returns roles, states,

text, and `@eN` refs. Prefer fresh refs over raw selectors. Refs invalidate after navigation and may

also become stale after large DOM changes, so observe again before the next interaction.

Use `browser_interact` for click, hover, scroll-to, focus, blur, fill, select, press and wheel.

`scroll-to` reveals a target and returns its visible border-box bounds in top-level viewport CSS

pixels, clipped by ancestors. Partial visibility suffices; hidden/fully clipped targets fail.

This does not test occlusion. Use refs for iframe/shadow-root targets; selectors search the main document.

`wheel` takes signed `deltaX`/`deltaY` (one nonzero). Optional `target` is scrolled into view first;

otherwise input lands at the viewport centre. Results echo input, not completed scrolling; observe afterwards.

`focus`/`blur` enter or leave focus-triggered states. Hover-only surfaces appear as

`@e1 button "Products" [hover first: Shoes | Bags]`. Items are labels, not refs:

hover the trigger, observe, then use the revealed item's ref. Click the trigger only if its action is wanted.

Escalate reading only as needed:

1. `observe` for normal understanding and interaction refs.

2. `snapshot` when a stricter static accessibility tree is more useful.

3. `html` for exact markup or hidden metadata that semantic views cannot provide.

4. `screenshot` for layout, styling, canvas, images, or requested visual evidence.

Do not start with raw HTML or screenshots merely to discover ordinary controls. When interaction is

needed, obtain a fresh observation before acting on screenshot or HTML findings.

Use `browser_page` for purposeful navigation, history, reload, or a lifecycle wait. Avoid speculative

waits when no navigation is expected. After any page change, discard old refs and observe again.

## Respect the Agent Window boundary

Use `browser_tabs` to list returned tab ids before selecting, closing, borrowing, or returning tabs.

Borrow a user tab only for the immediate task, and return it as soon as that step is complete. Never

invent a tab id or keep a personal tab borrowed across unrelated work.

+ The extension enforces its Automation settings on received requests; old CLIs/daemons may end help locally.

+ Update all components for full support.

+ Do not change settings to bypass a prompt. Never repeat denied or expired borrows; inspect unknown outcomes.

## Ask the human when needed

- Use `browser_assist` action `request-help` for login, captcha, OTP, payment confirmation, consent, or

- another step the user must complete. Give a precise prompt and highlight fresh targets when concrete

- controls are involved. Use completion criteria only for a clear stable success signal.

+ With human help enabled, use `browser_assist` action `request-help` for login, captcha, OTP,

+ payment confirmation, consent, or other human steps. Give a precise prompt and fresh targets;

+ use completion criteria only for a stable success signal. Resume on continuation or completion;

+ cancellation and timeout block the step. Observe again before using refs.

- Resume only after the user continues or the criteria complete. Treat cancellation as rejection and

- timeout as a blocker rather than retrying. Observe again after control returns before reasoning about

- the new state or using refs.

+ With help disabled, task/host rules and borrow confirmation still apply; no new permission is granted.

+ `disabled` confirms no human action: re-observe, use existing login state and authorized

+ inputs, and continue. Where task/host rules allow, models with vision may attempt graphical

+ verification using screenshots and supported interactions. Phone-only QR scans, face verification,

+ unavailable SMS codes, and image-only CAPTCHAs for text-only models may remain blocked. Try viable

+ alternatives and verify results; block only for missing inputs/capability or exhausted options.

+ Do not repeat unknown effects, request help again, or switch backends. Continue independent work.

- The same tool can resize the Agent Window or emulate a device when the task requires visual or

- responsive testing. Emulation is scoped to one tab.

+ `browser_assist` also resizes the Agent Window or emulates a device for one tab.

## Debug and recover without wandering

Use `browser_inspect` console or network actions only for relevant, bounded, read-only diagnostics.

Continue from returned sequence cursors instead of rereading the same buffer.

- Stale ref: observe again and retry the intended action once.

- Unknown tab: list tabs instead of guessing.

- Unknown session: list owned sessions or start one; never try foreign ids.

- Timeout: inspect current state before deciding whether one longer purposeful wait is useful.

- Fill result unconfirmed: observe the field first; the page may have formatted the value. Continue

if the visible result satisfies the user's intent. Otherwise correct the remaining difference;

do not blindly repeat fill or immediately request human help. For other fill errors, follow the

returned hint and inspect current state before retrying.

- Unrecoverable failure: report the blocker and stop the owned session.

Arbitrary page-script evaluation and interaction recording are intentionally unsupported. Do not

invent tools or route around those limits.

- ## Canvas and continuation

- [visual:screenshot] means screenshot that ref first; names are optional, not inferred from

- nearby controls. If needed images cannot be understood, ask to switch models and use semantics.

- Click via browser_interact(action=click,target=ref,captureId=...,imageX=...,imageY=...), using

- ORIGINAL PNG pixels. Captures are single-use, last two minutes, and expire on ref replacement

- or a new screenshot of that ref. captureUnavailable means view only; observe and screenshot

- again. Counts 1/2 and buttons/modifiers work, not Canvas fill/IME/drag/hover. Repainting is allowed:

- verify results; use DOM refs for revealed controls. Inspect before retrying effect_state=unknown.

- No default token cap. With maxTokens, follow nextCursor via observe(cursor=...); each page can

- contain many Canvas refs and replaces previous refs. This reads the same observation without

- recapture or depth changes. New observe/snapshot or DOM identity changes invalidate continuation.