@anweat/dsh-browser 0.1.17 → 0.2.0

package/assets/skills/dsh-browser/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: dsh-browser
+description: Use to open, read, or operate web pages, and to reuse or develop browser automation assets (recipes, userscripts) with the dsh-browser tools browser_index and browser_call. 打开、读取、操作网页，或复用、开发浏览器自动化资产时使用。
+---
+
+# dsh-browser
+
+Browser capabilities come through two tools. `browser_index` shows what exists; `browser_call` runs one action and returns `{ok, action, seq?, executionStatus, result | error{code,message,hint}}`. Actions are named `group.action`. Do not guess other tool names.
+
+## 1. Reuse first
+
+At the start of a task, search for an existing verified asset. If one fits, run it instead of exploring the site again.
+
+```json call
+{"action":"automation.search","args":{"query":"search issues","domain":"github.com"}}
+```
+
+```json call
+{"action":"automation.run","args":{"id":"asset-id-from-search","url":"https://github.com/search","inputs":{"query":"dsh"}}}
+```
+
+Two calls, no schemas needed; only active assets are returned.
+
+## 2. Finding actions
+
+```json index
+{}
+```
+
+lists the groups and the environment state. `{"group":"act"}` lists a group, `{"action":"act.click"}` gives a schema, `{"query":"upload"}` searches. `automation.develop` has sub-actions; one sub-action's schema:
+
+```json index
+{"action":"automation.develop.save"}
+```
+
+Six calls you rarely need a schema for:
+
+```json call
+{"action":"target.open","args":{"url":"https://example.com/"}}
+```
+
+```json call
+{"action":"observe.read","args":{}}
+```
+
+```json call
+{"action":"act.click","args":{"locator":{"role":"button","name":"Search"}}}
+```
+
+```json call
+{"action":"act.fill","args":{"locator":{"label":"Query"},"text":"dsh"}}
+```
+
+```json call
+{"action":"act.wait","args":{"locator":{"text":"Results"}}}
+```
+
+A wrong argument returns `INVALID_ARGS` with the schema attached: fix and resend.
+
+## 3. Locating elements
+
+- Prefer a `locator` with `role` + `name`, then `label`, `text`, `testId`; a CSS `selector` only if nothing semantic exists.
+- Locators are strict: one matching several elements does nothing and fails `LOCATOR_AMBIGUOUS` (`error.candidates` lists five). Narrow it (`exact`, a better name, `frame`/`framePath`); only if you must pick one, add `index` and `indexReason`.
+- `observe.read` with `sections` (`controls`, `links`, `tables`; `references/observe.md`) gives checked locators for `act.*`; `ambiguous:true` means none is unique.
+- Results carry `targetId` and `generation`. Pass `generation` as `expectGeneration` to `act.*`: if the page navigated since, it fails `TARGET_STALE` instead of acting.
+- `act.fill` replaces, `act.type` presses keys, `act.clear` empties. A popup joins `target.list`; switch with `target.select`.
+
+## 4. Side effects and failure
+
+`act.*` change the page and may need the user's approval in `standard` mode. Read `error.code` and `error.hint`:
+
+| code | what to do |
+|---|---|
+| `INVALID_ARGS` | fix the arguments using the attached schema |
+| `LOCATOR_NOT_FOUND` | read the page, adjust the locator, `act.wait` for dynamic content; nothing was done |
+| `LOCATOR_AMBIGUOUS` | several matched, nothing was done: choose from `error.candidates` |
+| `NOT_ACTIONABLE` | hidden, disabled, or covered: wait or dismiss the overlay; nothing was done |
+| `TARGET_CLOSED` | call `target.open` again |
+| `TARGET_STALE` | the page navigated (also when a read hit a navigation twice); nothing was done: `observe.read` again, use the new `generation` |
+| `DEADLINE` | with `executionStatus: "outcome_unknown"` it may have taken effect: verify with `observe.read`, never resubmit blindly |
+| `OUTCOME_UNKNOWN` | a page-changing step timed out mid-way: check with `observe.read` before any retry |
+| `VALIDATION_FAILED` | the steps ran but an assert or postcondition did not hold: read the page, fix the recipe; do not repeat submits |
+| `VALIDATION_MISSING` | a v2 draft has no `assert` or postcondition, so its test cannot pass: add one, save, test again |
+| `CANCELLED` | stopped; steps that already ran stay done (see `effects`) |
+| `POLICY_DENIED` / `CAPABILITY_UNAVAILABLE` | not allowed or not set up here (Chromium missing: `runtime.install`) |
+
+Recipe runs (`automation.run_recipe`, `automation.run`, `automation.develop` test) return the whole run in `result` even when `ok` is false: `executionStatus`, `validationStatus` (`not_checked`, `passed`, `failed`), `completedSteps`, `failedStep`, `effects` (`none`, `observed`, `unknown`), `outputs`. `completed` with `not_checked` means the steps ran, not that the result is right; nothing is rolled back (`references/recipes.md`).
+
+After a submit, purchase, or any irreversible step, confirm the result on the page (confirmation text, new URL, changed list) before telling the user it worked.
+
+## 5. Choosing a path (cheapest first)
+
+1. A saved asset: `automation.search` then `automation.run`.
+2. OpenCLI adapters if the platform is covered: `opencli.catalog`, `opencli.run` (`references/opencli.md`).
+3. Read-only extraction: `script.catalog`, `script.run_builtin`, a userscript (`references/userscripts.md`).
+4. Page interaction: `target.open`, `observe.read`, `act.*` (`references/observe.md`).
+5. Bounded multi-step work: `automation.run_recipe` (`references/recipes.md`); `crawl.crawl` for anonymous crawls.
+
+## 6. Turning a success into an asset
+
+When an exploration worked and will likely repeat, do not rewrite it by hand. Every page-touching call you made is in a session journal (its `seq` is in each reply); build the draft from it, then test it on other inputs:
+
+```json call
+{"action":"automation.develop","args":{"action":"draft_from_journal","name":"Keyword search","parameters":[{"seq":3,"field":"text","name":"keyword"}],"extract":[{"seq":7,"as":"items"}],"postconditions":[{"output":"items","allowEmpty":true},{"selector":"#status"}]}}
+```
+
+```json call
+{"action":"automation.develop","args":{"action":"test","id":"draft-id","url":"https://example.com/search","inputSets":[{"keyword":"alpha"},{"keyword":"beta"}]}}
+```
+
+`parameters` turns a typed value into an input, `extract` names the `observe.read` that is the result, `postconditions` check it; failed calls and plain observations are left out. Read `unmapped` (what a recipe cannot express: the draft is then incomplete and cannot be activated), `warnings`, `pendingDisambiguation`. `inputSets` (2 to 5) run each in a fresh context and all must pass; `PARAMETERIZATION_SUSPECT` means different inputs gave the same output. Details: `references/develop.md`.
+
+Write a recipe by hand (`save`, `validate`, `test`; schema v2 in `references/recipes.md`) only when the journal cannot cover it. `convert` turns a v1 asset into a v2 draft.
+
+Every save is a new revision and a test vouches only for the revision it ran on. A draft is not usable until the user activates a tested revision; never claim it is ready. To repair an active asset, `{"action":"fork","id":...}` gives an editable copy. Never put cookies, tokens, passwords, or page content in an asset.
+
+## 7. Boundaries
+
+- The user's automationMode decides what is exposed and what asks for approval. Do not route around a refusal.
+- Logged-in access uses a named AuthProfile (`authProfile` on `target.open`). Respect the site's rules and the usage buffer.

package/assets/skills/dsh-browser/references/develop.md

@@ -0,0 +1,48 @@
+# Developing a draft from an exploration
+
+The shortest path from "it worked once" to a reusable asset: explore with `browser_call`, `draft_from_journal`, test with `inputSets`. The user activates; you never do.
+
+## The journal
+
+Every page-touching call (`target.*`, `observe.*`, `act.*`, `script.*`, `automation.run_recipe`, `automation.run`) is recorded in this session's journal and its reply carries `seq`. The journal keeps the last 200 calls, lives in memory only, and is dropped with the session. A call refused for bad arguments is not recorded; a failed call is, with its error code.
+
+Each entry has the action, page `targetId`, `generationBefore` and `generationAfter`, the locator, scrubbed parameters, the outcome (`ok`, `executionStatus`, `errorCode`), `effects`, and a short summary. Typed text is never stored in an entry: `act.fill` and `act.type` text is a reference `{ref, length, sensitive?}`. The text itself is kept in memory only while it is short (200 characters or fewer) and does not look like a token or card number, and not at all when the page says the field is a password or the field is named like a secret. A `target.open` URL loses secret query values and userinfo. `observe.read` entries are observation points: they never become steps unless you name one in `extract`.
+
+## draft_from_journal
+
+```json call
+{"action":"automation.develop","args":{"action":"draft_from_journal","name":"Keyword search","fromSeq":1,"toSeq":9,"exclude":[4],"parameters":[{"seq":3,"field":"text","name":"keyword","type":"string"}],"extract":[{"seq":8,"as":"items","mode":"text","dedupe":true}],"postconditions":[{"output":"items","allowEmpty":true},{"selector":"#status"}]}}
+```
+
+- `fromSeq`, `toSeq`: the slice (default: the whole journal). `exclude`: more seq to leave out. Failed calls and observations are already left out.
+- `parameters`: `field` is `text` (act.fill, act.type), `values` (act.select) or `url` (a later target.open). Without it the typed text stays a literal, and `parameterCandidates` lists what you could parameterize. A value that was not kept (secret, too long) becomes a required input automatically (`SENSITIVE_VALUE_BECAME_INPUT`, or `VALUE_BECAME_INPUT` for a long value); pass it when testing and running.
+- `extract`: `seq` of an `observe.read` that read the result (with a `locator`); `as` names the output; `mode` text, html or links; `dedupe` removes repeated lines (text) or elements (links). `extractCandidates` lists the scoped reads you could use.
+- `postconditions`: written as given. Without them the reply only suggests some (`suggestedPostconditions`) and a test cannot pass (`NO_VERIFIER`). For a result that may legitimately be empty use `{"output":"items","allowEmpty":true}` together with a success marker such as `{"selector":"#status"}`: an empty result then passes, a missing container still fails.
+- `id`: replace the draft of an earlier call (a new revision). Each call is one draft write; a session has a few (3 by default), so pass `postconditions` the first time.
+- `domains` default to the hosts of the pages involved; `name` is required.
+
+The reply: `steps`, `complete`, `sourceMap` (seq to step number; the opening `target.open` maps to 0: it is the `url` of test and run, `suggestedTestUrl`), `observationPoints`, `excluded` (with reasons), `unmapped`, `inputSchema`, `pendingDisambiguation` (steps that pick a match by `index`), `parameterCandidates`, `extractCandidates`, `suggestedPostconditions`, `domains`, `warnings`.
+
+## What maps and what does not
+
+Mapped: `act.click`, `hover`, `fill`, `type`, `clear`, `press`, `check`, `scroll`, `select` (one value), `act.wait` for a visible locator, plain URL text, network idle or a delay, a later `target.open` (a `goto`), a named `observe.read` (an `extract`). Unmapped, each with its reason: `script.*`, `act.upload`, `target.select` and any step on another page (a v2 recipe runs on one page), multi-value select, wait for hidden or detached, glob URL patterns, a frame chosen by name or url, a `target.open` whose URL carried a secret, a whole recipe run.
+
+Any `unmapped` entry makes the draft `complete: false` (`INCOMPLETE_DRAFT`): it cannot be activated until you finish the recipe yourself and `save` it (that save replaces it). Warnings to act on: `GENERATION_JUMP` (the page moved between two calls without an action: add a wait or a goto), `EXCLUDED_NAVIGATION`, `NO_OPENING_STEP` (the test url must be the page the first step starts on), `FIXED_DELAY`, `NO_OUTPUT`, `FAILED_STEP_EXCLUDED` (the draft assumes later steps did not depend on it), `FAILED_STEP_EFFECTS_UNKNOWN`, `PARAMETER_NOT_APPLIED` and `EXTRACT_NOT_APPLIED` (the named seq is not a step), `JOURNAL_TRUNCATED` (the start of the exploration fell out of the 200 calls).
+
+## Testing with inputSets
+
+```json call
+{"action":"automation.develop","args":{"action":"test","id":"draft-id","url":"https://example.com/search","inputSets":[{"keyword":"alpha"},{"keyword":"beta"}]}}
+```
+
+`inputSets` takes 2 to 5 input objects, all valid for the `inputSchema` and different from each other (checked before anything runs). Each runs in a new BrowserContext, never in your session page, with its own cookies; the first failing set stops the test. All sets must pass for the credential to be `passed`; it records how many sets ran and a digest of each set's inputs and outputs, never the values. The reply has one entry per set (`outputs`, `validationStatus`, `failedStep`), not repeated steps.
+
+If different inputs gave identical outputs the test still passes but replies `warnings: [PARAMETERIZATION_SUSPECT]` with the set numbers, and the credential carries it: the input probably does not reach the page, or the output ignores it. Fix that before asking the user to activate. Without `inputSets` a test is one run on the session page, as before. An asset that declares inputs cannot be activated unless its passing test covered at least `automationAssets.minInputSetsForActivation` input sets (default 2): a single-input test cannot show the recipe does not hard-code that input, and activation is refused with `insufficient-input-sets`. Assets without inputs are not affected.
+
+## The whole path
+
+1. `automation.search`; reuse if an asset fits.
+2. Explore: `target.open`, `observe.read`, `act.*`, `act.wait`, `observe.read` with a `locator` for the result.
+3. `draft_from_journal` with `parameters`, `extract`, `postconditions`; read `unmapped` and `warnings`.
+4. `test` with `inputSets` (include a keyword with no result when an empty result is legitimate).
+5. Tell the user the draft and its tested revision; they activate it with that revision.

package/assets/skills/dsh-browser/references/observe.md

@@ -0,0 +1,91 @@
+# Reading what the browser returns
+
+Load this when a page result is hard to interpret.
+
+## observe.read and action results
+
+`target.open`, `observe.read`, and the `act.*` actions return the page state in `result`:
+
+- `url`: the current address (check it after a click to see whether navigation happened).
+- `title`: the page title.
+- `text`: readable page text, bounded. Long pages are cut; if the part you need is missing, scroll with `act.scroll` and read again, or extract it with a recipe or built-in script.
+- `targetId` and `generation`: which page of your session this is and its version (see Page generations below).
+- `screenshotPath`: a file path on the host (only when a screenshot was taken, for example by `target.open`).
+
+A `truncation` field on the envelope means long text fields were shortened; the result is still valid JSON.
+
+## Reading structure: sections
+
+`observe.read` returns only `text` by default. Ask for more with `sections`, any of `content`, `controls`, `links`, `tables`:
+
+```json call
+{"action":"observe.read","args":{"sections":["controls"]}}
+```
+
+Narrow it to part of the page with a `locator` (everything below that element is read; it must match exactly one element) or a viewport `region`, and bound it with `maxItems` (per section) and `maxBytes` (whole result):
+
+```json call
+{"action":"observe.read","args":{"sections":["controls","tables"],"locator":{"role":"form"},"maxItems":20,"maxBytes":12000}}
+```
+
+Each control record has `role`, `name`, `type`, a `locator`, the `actions` that can work now, the states it has (`visible`, `disabled`, `readonly`, `checked`, `expanded`), `options` for a select or radio group, declared `constraints` (`required`, `min`, `max`, `step`, `pattern`, `minlength`, `maxlength`, `accept`, `multiple`), the browser's own `validity`, and a `source` (`dom` or `aria`). The full field list: `{"action":"observe.read.controls"}` in `browser_index`.
+
+- The `locator` was checked against the live page: it matches that element and no other. Pass it unchanged to `act.*`. Inside an iframe it carries `framePath`; open shadow DOM needs nothing extra.
+- `ambiguous: true`: nothing unique exists (two identical unlabeled buttons, say). `matches` says how many elements the locator hits and `nth` which one this is; acting on it as is returns `LOCATOR_AMBIGUOUS`. Pin it with `index: nth` and an `indexReason`, or scope the read to its container.
+- A field that is missing was not observed or does not apply (a range input has no `readonly`); `false` always means observed and not so. An empty list is an answer: `options: []` is a select with no options, `rows: []` with `totalRows: 0` an empty table, `controls: []` a page without controls. A scope that does not exist is `LOCATOR_NOT_FOUND`.
+- Values are not returned. `hasValue` says whether a field is empty. With `includeValues: true` plain fields return `value`, but never password, hidden, file, or token-like fields: those only carry `hasValue` and `sensitive: true`.
+- `frames` lists the iframes searched. A cross-origin or sandboxed one has `crossOrigin: true` and its content is not observed, and `limits` says so; you can still reach into it with `framePath` if you know the element. Closed shadow roots cannot be read.
+- `links` have `text`, absolute `href` (a secret-looking query value such as a token shows as `[redacted]`), and a `locator`. `tables` have `headers`, the first `maxItems` `rows`, `totalRows`, and `coverage`: `partial` (with a `reason`) means the page has more rows than the DOM shows, because of a virtualized list or a pager; scroll or use the pager, then read again.
+- Output is cut at item boundaries to fit `maxBytes` and is always valid JSON. `truncation: {omittedBySection, reason}` names what is missing and `counts` how many the page has. Ask for one section, raise the limits, or scope with a `locator`. Details: `{"action":"observe.read.truncation"}`.
+
+## Page generations
+
+Every page state has a `generation`. It changes when the page's main frame navigates: a new page load, reload, history back or forward, `location` change, `history.pushState` or `replaceState`, a hash change. It does not change for a DOM re-render or for an iframe navigating on its own. Values only grow within your session and never repeat, so a `generation` cannot match a different page.
+
+Pass the `generation` you observed as `expectGeneration` to an `act.*` call. If the page has moved on, the call fails with `TARGET_STALE` before doing anything, and `error.current` has the new `targetId` and `generation`: observe again and decide whether the page is still the one you meant.
+
+```json call
+{"action":"act.click","args":{"locator":{"role":"button","name":"Create account","exact":true},"expectGeneration":3}}
+```
+
+Recipes do not take it: they bind the page again on every run.
+
+## Screenshots
+
+```json call
+{"action":"observe.screenshot","args":{"locator":{"role":"heading","name":"Pricing"}}}
+```
+
+returns `{path}` inside `snapshotDir`. Without a locator it captures the full page. A `filename` must be a plain name ending in `.png`, `.jpg`, or `.jpeg`.
+
+## Console and failed requests
+
+Capture is off unless the page was opened with it:
+
+```json call
+{"action":"target.open","args":{"url":"https://example.com/","capture":["console","network"]}}
+```
+
+Then `inspect.console` (filter with `level`) and `inspect.requests` return bounded, redacted records: console text, and failed or HTTP 4xx/5xx requests (method, url, status). No bodies or headers are recorded. Records reset on the next `target.open`.
+
+## Waiting
+
+`act.wait` takes exactly one of: a `locator`/`selector` (with `state`), `urlPattern`, `networkIdle: true`, or `timeMs` (max 10000).
+
+## Several pages
+
+Each session has its own context; other sessions cannot see it. A link with `target=_blank` or `window.open` adds a popup to your page list without making it active. `target.list` shows every page (`id`, `url`, `title`, `active`); switch with `target.select`, then `observe.read` and `act.*` work on that page.
+
+```json call
+{"action":"target.list","args":{}}
+```
+
+```json call
+{"action":"target.select","args":{"id":"t2"}}
+```
+
+Ids are never reused in a session. A popup that closed gives `TARGET_CLOSED` on select; list again. If the active page closes, the session falls back to another open page of the same context. `target.close` discards all of the session's pages.
+
+## Typing and clearing
+
+`act.fill` replaces a value at once (no key events). `act.type` presses the keys one by one, for autocompletes and masked inputs. `act.clear` empties a field and fires the input event, so controlled inputs update their state; do not fill an empty string to clear.

package/assets/skills/dsh-browser/references/opencli.md

@@ -0,0 +1,25 @@
+# OpenCLI site adapters
+
+OpenCLI ships adapters for many platforms (for example Reddit, Xiaohongshu) that can be cheaper and more robust than driving pages by hand.
+
+## Flow
+
+1. `opencli.status` checks the daemon, extension, and Browser Bridge. Do not infer connectivity from `runtime.status` alone: it only shows the config switch.
+2. `opencli.catalog` finds exact command names. Filter instead of dumping everything.
+
+```json call
+{"action":"opencli.catalog","args":{"site":"reddit","access":"read","limit":10}}
+```
+
+3. `opencli.run` runs one command with verbatim arguments after `opencli`.
+
+```json call
+{"action":"opencli.run","args":{"args":["reddit","search","dsh","-f","json"]}}
+```
+
+## Notes
+
+- `access` in the catalog is the adapter's own declaration, not a guarantee. Treat `write` commands (post, delete) as irreversible and expect an approval prompt.
+- `opencli.run` can reuse the logged-in Chrome profile, so it asks for approval unless the user chose `unrestricted`.
+- Pass `-f json` where supported so the output is easy to read.
+- Chinese community sites usually need a domain-scoped AuthProfile configured by the user; if a command reports a login problem, tell the user rather than trying to log in.

package/assets/skills/dsh-browser/references/recipes.md

@@ -0,0 +1,149 @@
+# Recipes: bounded multi-step browser work
+
+A recipe is 1 to 25 declarative steps run on the current page. Run one inline with `automation.run_recipe`, or save it as a draft with `automation.develop` so it can be tested, activated by the user, and reused with `automation.run`.
+
+There are two schemas. **Write new recipes as v2** (`"schemaVersion":2`): locators are strict, so a step never silently acts on the wrong element. v1 (the default for an inline recipe without `schemaVersion`, and for every asset saved before v2) keeps its old behaviour: CSS `selector`, always the first match.
+
+## v2 steps
+
+Each step has a `type` and a `locator` where it acts on an element. A locator is one of `{"role":"button","name":"Save"}` (optional `exact`), `{"label":"Query"}`, `{"text":"More"}`, `{"testId":"save"}`, `{"css":"#id"}`, plus optional `framePath` (iframe selectors, outermost first).
+
+| type | fields |
+|---|---|
+| `wait` | `condition`: `locator` (with `locator`), `text` or `url` (with `value`), `load`, or `time` (with `waitMs`); optional `timeoutMs` |
+| `click`, `hover`, `clear` | `locator` |
+| `fill` | `locator`, `value` (non-empty; to set `""` write `allowEmpty: true`, or use `clear`) |
+| `type` | `locator`, `value` (key by key) |
+| `press` | `key`, optional `locator` |
+| `select` | `locator`, `value` |
+| `check` | `locator`, optional `checked` (false unchecks) |
+| `scroll` | `deltaY`, `waitMs` |
+| `goto` | `url`: absolute http(s), inside the recipe's domains (see below) |
+| `extract` | optional `locator` (default: the page), `mode`: `text`, `html`, `links`, `attribute` (with `attribute`), `limit`, optional `as` (names the output) |
+| `assert` | `locator`, `text`, or `urlIncludes` that must become true |
+| `screenshot` | none |
+
+`extract` and `assert` wait at most 5 s unless `timeoutMs` says otherwise, so a selector that is not there fails fast with `LOCATOR_NOT_FOUND`. Every other step waits 15 s. Read-only steps (`wait`, `goto`, `extract`, `assert`, `screenshot`) run without approval; anything else may ask the user.
+
+```json call
+{"action":"automation.run_recipe","args":{"url":"https://example.com/","schemaVersion":2,"steps":[{"type":"click","locator":{"role":"link","name":"More information"}},{"type":"assert","urlIncludes":"iana.org"},{"type":"extract","locator":{"css":"main"},"as":"body"}],"postconditions":[{"output":"body","nonEmpty":true}]}}
+```
+
+### When a locator is ambiguous
+
+A v2 locator must match exactly one element. If it matches several, the step is **not executed** (no click, no typing; `effects` stays as it was) and the reply is `LOCATOR_AMBIGUOUS` with `error.candidates`: `total` and the first five matches (`role`, `name`, `text`, `visible`). Fix the locator, do not guess:
+
+1. Make it specific: `exact: true`, a fuller `name`, a `label`, a `testId`, or a `framePath`.
+2. Only if the elements really are interchangeable, pick one with `"index": 1` **and** an `"indexReason": "why this one"`. An `index` without a reason is rejected.
+
+A step that finds no element at all (`LOCATOR_NOT_FOUND`) did nothing either: `executionStatus` is `failed` and `effects` does not become `unknown`. Only a step that found its element, started, and then timed out is `outcome_unknown`.
+
+## Reading the result
+
+A recipe never fails by throwing away what it did. `result` always holds:
+
+| field | meaning |
+|---|---|
+| `executionStatus` | `completed`; `failed` (a step failed or the deadline passed); `cancelled`; `outcome_unknown` (a step that changes the page was being performed when it timed out) |
+| `validationStatus` | `passed`: there is at least one `assert` or postcondition and every one held. `failed`: one did not hold. `not_checked`: nothing verified the result |
+| `completedSteps` | the steps that finished: `step`, `action`, `ok`, and for extract/screenshot `output`, the index into `outputs` (the value is stored once, there) |
+| `failedStep` | `index` (1-based), `action`, `errorCode`, the original `message`, and `candidates` for `LOCATOR_AMBIGUOUS`; for a cancel or deadline, the step that did not start. A failed postcondition is reported as a step after the last one with `action: "postcondition"` |
+| `effects` | `none`: nothing changed. `observed`: fill, type, clear, click, press, select or check steps completed. `unknown`: one of those failed in flight, so it may have happened |
+| `outputs` | values from extract and screenshot steps, each with `step`, `action`, `value`, and `name` when the extract had `as`; an existing but empty element gives `""`, a missing element is `LOCATOR_NOT_FOUND` |
+| `legacyFallback` | only on stored v1 assets: an unknown extract `mode` ran as `links` |
+
+`ok` is true only when `executionStatus` is `completed` and `validationStatus` is not `failed`. Next steps:
+
+- `OUTCOME_UNKNOWN`: do not run the recipe again. Read the page (`observe.read`) to see whether the click, fill or submit took effect, then continue from the real state.
+- `VALIDATION_FAILED`: the page did not show the expected result. Read it, then correct the recipe, the assert or the postcondition. Steps before the failure already ran; do not repeat a submit.
+- `failed` with `effects: observed`: the earlier steps are done. Resume from `failedStep.index`, not from the start.
+- `failed` with `NOT_ACTIONABLE` and `effects: none`: the element was found but stayed disabled, hidden or moving until the timeout, so the step never ran. Wait for the page state it needs (`wait`), then retry.
+- `cancelled`: the step that was running finished before the call returned; the page stays open and usable.
+
+A test or run counts as passed only when it completed and nothing failed validation.
+
+## Verifying the result: assert and postconditions
+
+`assert` steps check in the middle of a recipe; **postconditions** are checked after all steps and belong to the asset. Use exactly one kind per entry:
+
+- `{"selector":"#done"}`: a CSS selector that is visible. `{"text":"Saved"}`: text that is visible. `{"urlIncludes":"/inbox"}`: the final URL contains it. Each waits up to `timeoutMs` (default 5000).
+- `{"output":"results","nonEmpty":true}`: the named extract output is not empty. `{"output":"results","allowEmpty":true}`: it only has to have been produced (an empty result is legitimate).
+
+`validationStatus` is `passed` only when every `assert` and every postcondition holds. **A v2 draft with no `assert` and no postcondition can be saved, but its test cannot pass**: the reply is `ok: false` with `error.code: "VALIDATION_MISSING"` and `testStatus: "failed"`. Add a check that proves the business result (confirmation text, new URL, a non-empty output).
+
+## Inputs and outputs
+
+`{{name}}` in any string of a step or postcondition becomes an input. For v2, declare each one in `inputSchema` and the caller's values are checked and converted before the browser is touched:
+
+```json call
+{"action":"automation.develop","args":{"action":"save","kind":"recipe","schemaVersion":2,"name":"Catalog apply","domains":["example.com"],"recipe":[{"type":"fill","locator":{"label":"Limit"},"value":"{{limit}}"},{"type":"select","locator":{"label":"Sort"},"value":"{{sort}}"},{"type":"click","locator":{"role":"button","name":"Apply"}},{"type":"extract","locator":{"css":"#rows"},"as":"rows"}],"inputSchema":[{"name":"limit","type":"number","example":"3"},{"name":"sort","type":"enum","enumValues":["new","top"]}],"outputSchema":[{"name":"rows","type":"string"}],"postconditions":[{"text":"Sorted by {{sort}}, limit {{limit}}"},{"output":"rows","nonEmpty":true}]}}
+```
+
+- `type`: `string`, `number` (a number or numeric text; stored canonically), or `enum` (must be one of `enumValues`). `required` defaults to true; an omitted optional input becomes an empty string. Wrong or missing inputs fail with `INVALID_ARGS` before anything runs.
+- `outputSchema` names and types the outputs: each entry needs an `extract` with the same `as`. `number` parses the text (thousands commas allowed), `json` parses JSON (use it with `links`); a value that does not convert fails validation. `"dedupe":true` (string or json) removes repeated lines or elements, keeping the first of each, before the postconditions are checked.
+- `requiredCapabilities` is recorded for later; it is not enforced.
+- `automation.search` shows a v2 asset's `inputSchema`, so you can call `automation.run` without opening the recipe.
+
+## goto
+
+`goto` navigates the recipe's page. For a saved asset the URL must be inside its `domains` (the host or a subdomain), checked when saving and again when running, including where a redirect lands. For an inline recipe it may stay on the origin the recipe started on, or go to hosts listed in `allowedDomains`. A URL outside that fails with `POLICY_DENIED` before any step runs.
+
+```json call
+{"action":"automation.develop","args":{"action":"save","kind":"recipe","schemaVersion":2,"name":"Reset filter","domains":["example.com"],"recipe":[{"type":"goto","url":"https://example.com/search"},{"type":"clear","locator":{"label":"Filter"}},{"type":"assert","text":"All items"}]}}
+```
+
+## Saving a draft
+
+Save (`automation.develop`, `save`) replaces the whole draft, so send every field each time; `browser_index({action:"automation.develop.save"})` has its schema. Then `{"action":"validate","id":...}` and `{"action":"test","id":...,"url":...,"inputs":{...}}`. Test with realistic inputs, and when the recipe takes any, with `inputSets` (2 to 5 different inputs, each in a fresh context; `references/develop.md`), checking that the outputs differ. A draft explored with `browser_call` is built with `draft_from_journal` instead of by hand (`references/develop.md`). Activation is the user's decision. Do not put page content, cookies or passwords into an asset.
+
+**Revisions.** Every save makes a new `revision` (with a `contentHash` over the steps and schema fields) and clears the test result. A test is recorded as a credential for the revision and content it ran on, with only a digest of the inputs; the test reply carries `revision` and `contentHash`. After any edit, test again. The user can activate only a revision whose latest test passed on exactly that content.
+
+## Repairing an active asset
+
+An active asset cannot be edited. When it stops working (the page changed), copy it, change the copy, test the copy:
+
+```json call
+{"action":"automation.develop","args":{"action":"fork","id":"active-asset-id"}}
+```
+
+The draft records `sourceAssetId` and `sourceRevision`. Failing tests of the draft never touch the active asset, which keeps running (`automation.run`). Once the draft passes with realistic inputs, tell the user it is ready; their activation archives the old asset and makes the draft the active one.
+
+## Converting a v1 asset
+
+```json call
+{"action":"automation.develop","args":{"action":"convert","id":"v1-asset-id"}}
+```
+
+creates a **new** v2 draft and leaves the original (even if active) exactly as it was; the draft records `sourceAssetId` and `sourceRevision`. Every CSS selector becomes `{"css": ...}` marked `explicitFirst`: it still takes the first match, as in v1, and is listed in `pendingDisambiguation`. To finish the migration: edit each listed step to a locator that matches one element (or an `index` with a reason), add an `assert` or a postcondition, save, and test. The `notes` in the reply list what else changed (shorter default timeouts, string inputs). An unknown `extract` mode or `wait` condition in the source refuses the conversion and says which step.
+
+## v1 steps (existing assets)
+
+A v1 step has a `type` and the fields it needs. Selectors are CSS and always use the first match.
+
+| type | fields |
+|---|---|
+| `wait` | `condition`: `selector` or `text` (with `value`), `load`, or `time` (with `waitMs`); optional `timeoutMs` |
+| `click` | `selector` |
+| `fill`, `type` | `selector`, `value` (`fill` replaces the value; `type` presses keys) |
+| `press` | `key`, optional `selector` |
+| `select` | `selector`, `value` |
+| `check` | `selector`, optional `checked` (false unchecks) |
+| `hover` | `selector` |
+| `scroll` | `deltaY`, `waitMs` |
+| `extract` | optional `selector`, `mode`: `text`, `html`, `links`, `attribute` (with `attribute`), `limit` |
+| `assert` | `selector` or `text` that must become visible |
+| `screenshot` | none |
+
+```json call
+{"action":"automation.run_recipe","args":{"url":"https://example.com/","steps":[{"type":"wait","condition":"selector","value":"main"},{"type":"extract","selector":"main","mode":"text","limit":20}]}}
+```
+
+A v1 recipe with no `assert` still passes a test, but is stored as `legacy-unverified` (`evidenceLevel`): add an `assert` that proves the business result to get `verified`.
+
+## Known limits
+
+- A step that fails stops the recipe. Earlier steps have already run and are not rolled back, so do not retry a recipe that already submitted something without checking the page.
+- A step that is already running cannot be interrupted. Cancel and deadline take effect between steps, so a long `wait` or a slow click delays the return by up to its own timeout.
+- `extract.mode` must be `text`, `html`, `links` or `attribute`, and a `wait` condition one of those listed above; other values are rejected when a recipe is run inline or saved.
+- A recipe passing a test with no `assert` (v1) means the steps ran, not that the business result was correct.
+- An inline v2 recipe is not offered as a reusable candidate; save it as a draft if it should be reused.

package/assets/skills/dsh-browser/references/userscripts.md

@@ -0,0 +1,44 @@
+# Userscripts and built-in scripts
+
+For extraction that is awkward through clicking, run JavaScript in a fresh page context.
+
+## Built-in scripts first
+
+They are trusted and read-only. `script.catalog` lists them (`article-clean`, `links`, `jsonld`, `forms`).
+
+```json call
+{"action":"script.run_builtin","args":{"url":"https://example.com/","scriptId":"links"}}
+```
+
+## Your own userscript
+
+Format: a Tampermonkey-style metadata block, then a function body that returns a JSON-serializable value. Only `@grant none` is supported (no `GM_*` APIs, no `@require`), and `@match` must cover the target URL. Declared inputs arrive in `__DSH_INPUTS__`.
+
+```
+// ==UserScript==
+// @name Read Heading
+// @match https://example.com/*
+// @grant none
+// ==/UserScript==
+return { heading: document.querySelector('h1')?.textContent || '', input: __DSH_INPUTS__.query || '' }
+```
+
+Validate before running; validation does not execute anything and reports the hash and capabilities.
+
+```json call
+{"action":"script.validate","args":{"source":"// ==UserScript==\n// @name Read Heading\n// @match https://example.com/*\n// @grant none\n// ==/UserScript==\nreturn document.title","url":"https://example.com/"}}
+```
+
+```json call
+{"action":"script.run_userscript","args":{"url":"https://example.com/","source":"// ==UserScript==\n// @name Read Heading\n// @match https://example.com/*\n// @grant none\n// ==/UserScript==\nreturn document.title"}}
+```
+
+Running external code asks the user for approval unless the mode is `unrestricted`. If the page redirects outside the `@match`, the run is rejected.
+
+## One-off expressions
+
+`script.evaluate` runs a single JavaScript expression (up to 20,000 characters) on the current page with its origin and login state, so it can read cookies and storage that are not HttpOnly. Use it sparingly; it also asks for approval.
+
+```json call
+{"action":"script.evaluate","args":{"expression":"document.title"}}
+```

package/cordis.patch.yml

@@ -3,11 +3,19 @@
 #   dsh plugin --profile <name> add @anweat/dsh-browser
 # then boot the profile (the web profile has HMR disabled, so a restart applies it).
 #
+# Supports DSH 0.2.0-rc.2 only (see the peer ranges in package.json).
+#
 # Login state: prefer named `authProfiles` with explicit `allowedDomains` (see
 # README). `storageStatePath` remains as a legacy global fallback.
-# DSH 0.1.7-rc.2 persists editable config in a separate top-level profile row;
-# placing config inside insert can make settings writes appear successful but
-# disappear on restart. Config schema defaults supply the initial values.
+#
+# The Host's Settings service saves editable config as a separate top-level row of
+# the profile's own patch (`- id: browser` with `config`), and a patch replaces its
+# target row's whole `config`. So this insert row carries no config: the Config schema
+# defaults supply the initial values and the profile row holds the saved settings.
+#
+# Model-facing text (tool descriptions, root guide/note, summaries, error hints, skill) can be
+# overridden under `prompts` in that config row; the settings card's "Export default text" (or `pnpm prompts:dump` in a
+# repository checkout) prints every default in the exact structure. See README "自定义提示文本".
 - insert:
     - id: browser
       name: '@anweat/dsh-browser'

package/lib/actions/act.d.ts

@@ -0,0 +1,3 @@
+/** `act` group: interact with the page. @module dsh-browser/actions/act */
+import type { ActionDef } from './types.ts';
+export declare const ACT_ACTIONS: ActionDef[];