fix(dsh): expose drag and saved observation workflows

crates/bsk-cli/skill/references/interaction-details.md

@@ -150,17 +150,19 @@ mutations or reuse one context across them. A known readiness selector can be
 waited on between that action and sync; check `satisfied`, without fixed sleeps
 or repeatedly returning a loading page to the model.
 
-For a known target on a large page, filter the **CLI presentation**, using literal
-text from a previous observation and enough surrounding lines for the decision:
+On pages with repeated numbered fallback buttons, fold controls outside a known
+target's surrounding lines in the **CLI presentation**. Use literal text from a
+previous observation and retain enough surrounding lines for the decision:
 
 ```sh
 bsk cooperate sync --session <id> --match-text 'known row label' \
   --context-lines 40 --save-full /absolute/new-observation.json
 ```
 
 `--match-text` is repeatable, literal and case-sensitive. This is a conservative
-presentation fold, not a semantic search or a row selector. Only plain numbered
-fallback controls (`button "item N"`) outside the matching windows may be omitted.
+presentation fold, not general text filtering, search or a row selector. Only
+plain stateless numbered fallback controls (`button "item N"`) outside the
+matching windows may be omitted.
 All business text, named controls, state/value/context hints, ancestors and the
 view/layer outline stay visible. Complete forms, dialogs, alerts and statuses
 are retained, including their numbered controls. This avoids guessing which
@@ -172,6 +174,12 @@ Every query must match; otherwise the full returned view is shown with
 views that would grow also fall back to the original text. This may produce less
 compression on some pages, including flight results with meaningful named controls.
 
+For general literal text search, inspect the saved observation locally:
+
+```sh
+bsk view /absolute/new-observation.json --find 'known row label' --line-count 80
+```
+
 When any lines are omitted, `observation.truncated` is true for legacy readers.
 `observation.capture_truncated` reports the original capture truncation, while
 `presentation.filtered` identifies local omissions. `presentation.complete` is

crates/bsk-cli/skill/references/step-and-cache.md

@@ -44,8 +44,11 @@ action result, never as evidence that the action did not occur.
 
 ## View existing evidence locally
 
-Save the complete reply before display filtering. Use `view` to read a different
-portion without another browser capture or a new ref map:
+Save the complete reply before display folding. The optional `--match-text` on
+`step` or `cooperate sync` only folds plain stateless numbered fallback buttons
+outside matching windows; business text, named/stateful controls and complete
+forms/dialogs remain visible. Use `view --find` for general literal text search,
+or read a different portion without another browser capture or a new ref map:
 
 ```sh
 bsk view /absolute/new-step.json --find 'known label' --line-count 80

crates/bsk-cli/src/cli/cooperate.rs

@@ -38,11 +38,14 @@ pub struct CooperateArgs {
     pub timeout_ms: Option<u64>,
     #[arg(long)]
     pub max_tokens: Option<u32>,
-    /// Show literal text matches with surrounding VOM lines (repeatable, sync only).
-    /// Filters CLI output only; refs and the full observation guard are unchanged.
+    /// Fold only plain numbered fallback buttons outside literal-match windows (repeatable, sync only).
+    ///
+    /// Only stateless `button "item N"` lines may be omitted. Keeps business text,
+    /// named/stateful controls and complete forms/dialogs. Use `bsk view <saved.json>
+    /// --find <text>` for text search. Changes CLI presentation only; refs and guards are unchanged.
     #[arg(long, value_parser = nonempty_text)]
     pub match_text: Vec<String>,
-    /// Lines before/after each match. Omitted VOM lines are explicitly marked.
+    /// Keep numbered fallback buttons within this many lines before/after each match.
     #[arg(long, requires = "match_text", value_parser = clap::value_parser!(u32).range(0..=200))]
     pub context_lines: Option<u32>,
     /// Save the unfiltered reply to a new local JSON file before presenting it (sync only).

crates/bsk-cli/src/cli/step.rs

@@ -54,9 +54,14 @@ pub struct StepArgs {
     /// Exact saved predecessor for an unchanged post-action sync.
     #[arg(long)]
     pub baseline: Option<PathBuf>,
-    /// Conservative presentation folding, applied only after saving the full reply.
+    /// Fold only plain numbered fallback buttons outside literal-match windows (repeatable).
+    ///
+    /// Only stateless `button "item N"` lines may be omitted. Keeps business text,
+    /// named/stateful controls and complete forms/dialogs. Use `bsk view <saved.json>
+    /// --find <text>` for text search. A requested full reply is saved before folding.
     #[arg(long)]
     pub match_text: Vec<String>,
+    /// Keep numbered fallback buttons within this many lines before/after each match.
     #[arg(long, default_value_t = 12, value_parser = clap::value_parser!(u32).range(0..=200))]
     pub context_lines: u32,
 }

packages/dsh-plugin-browserskill/README.md

@@ -89,8 +89,8 @@ capabilities. Updating the npm package does not update either component.
 | --- | --- | --- |
 | `bsk_session` | `start`, `stop`, `list`, `share`, `sync`, `wait-user`, `cooperation-status` | Manage owned sessions and shared-tab control. |
 | `bsk_page` | `navigate`, `back`, `forward`, `reload`, `wait`, `wait-for-element` | Navigate the active tab; wait for page lifecycle events or one element condition. |
-| `bsk_inspect` | `observe`, `snapshot`, `html`, `screenshot`, `console`, `network`, `debug`, `video`, `extract` | Inspect page state, debug websites, capture screenshots or requested task videos, and export structured tables/lists. |
-| `bsk_interact` | `click`, `hover`, `wheel`, `scroll-to`, `focus`, `blur`, `fill`, `select`, `press`, `evaluate`, `upload`, `download` | Interact with controls using fresh refs or selectors. |
+| `bsk_inspect` | `observe`, `snapshot`, `view`, `html`, `screenshot`, `console`, `network`, `debug`, `video`, `extract` | Inspect page state, read saved observations, debug websites, capture screenshots or requested task videos, and export structured tables/lists. |
+| `bsk_interact` | `click`, `hover`, `drag`, `step`, `wheel`, `scroll-to`, `focus`, `blur`, `fill`, `select`, `press`, `evaluate`, `upload`, `download` | Interact with controls using fresh refs or selectors. |
 | `bsk_tabs` | `list`, `create`, `select`, `close`, `borrow`, `return` | Manage Agent Window tabs and temporarily borrow user tabs. |
 | `bsk_assist` | `resize`, `emulate`, `request-help` | Resize or emulate the browser and pause for human-only steps. |
 
@@ -104,6 +104,23 @@ for signed deltas, optional targets, result semantics and interruption.
 For `bsk_interact` with `action: "scroll-to"`, see the
 [scroll-to reference](../../docs/scroll-to.md) for parameters, visible bounds and errors.
 
+For `bsk_interact` with `action: "drag"`, pass the source as `target` and either a
+destination `to` or relative `deltaX`/`deltaY`. The default holds the mouse button
+while moving; `dragMode: "click-move-click"` selects ranges using two clicks and
+requires a destination. Use current observed refs/selectors and inspect the result.
+
+Use `action: "step"` for one decided interaction, with `stepAction` and a `params`
+JSON string using that action's CLI protocol fields. It executes once, optionally
+waits for `untilVisible`, then synchronizes. Read action, readiness and sync outcomes
+separately; a failed follow-up does not mean the action should be repeated.
+
+Save complete observations with `saveFull` on `bsk_session action: "sync"` or
+`bsk_interact action: "step"`. Use `bsk_inspect action: "view"` with `file` and
+optional `find`, `startLine` or `lineCount` to inspect the saved file locally, even
+after the browser session ends. The view is historical, makes no browser calls,
+and needs no `session` or `contextId`. It never refreshes refs or authorizes an
+action. See [steps and saved observations](skill/references/interaction-details.md#steps-and-saved-observations).
+
 For `bsk_inspect` with `action: "extract"`, see
 [structured extraction](../../docs/structured-extraction.md) for discovery, list
 fields, JSON/CSV output and loaded-DOM completeness.
@@ -114,7 +131,8 @@ is not exposed by this plugin.
 
 Human/agent collaboration is enabled automatically for new sessions and owned task tabs.
 No `share` call is required. See [cooperation](skill/references/cooperation.md).
-Actions on shared tabs require the `contextId` returned by `sync`; each context is used once.
+Actions on shared tabs require the `contextId` returned by `sync` or a step's
+`post.context_id`; each context is used once.
 
 ### Activation failures
 
@@ -137,9 +155,9 @@ after fixing it.
 One agent conversation can drive several browser sessions at once:
 
 - `bsk_session` with `action: start` returns the session id and makes it the **current session**.
-- Every operation tool accepts an optional `session` argument. When omitted, the call acts on the
+- Browser operations accept an optional `session` argument. When omitted, the call acts on the
   current session (the one most recently started or used); when given, that session becomes current.
-- Every tool result echoes the session it actually acted on, so the model never has to guess.
+- Browser operation results echo the session they acted on; offline `view` reads only its local file.
 - The number of concurrent sessions started through the plugin is capped (`maxSessions`, default 5).
 - Unloading the plugin stops every session it started and kills in-flight bsk processes.
 

packages/dsh-plugin-browserskill/skill/SKILL.md

@@ -35,7 +35,8 @@ For remote setup/pairing, follow the [remote guide](https://github.com/Tencent/B
 
 2. For existing tabs, read [tab borrowing](references/tabs-and-profiles.md). Use actual IDs/refs.
    Pass `session` when several exist; never use foreign IDs.
-3. Pass the returned `context_id` as `contextId` to one action, then sync again.
+3. Pass the returned `context_id` as `contextId` to one action. Then sync, or read
+   the step's `post` result.
    On intervention, wait-user, sync and replan. Check ambiguous results once. Stop when success is
    visible. Stop requested video first, then on success or failure call
    `bsk_session({ action: "stop", session: "<id>" })` unless keeping the session
@@ -61,7 +62,7 @@ selectors search the main document. Sync before acting on visual or HTML finding
 Select options by value, not visible label.
 
 Inspect unknown effects before retrying. On an error or two attempts without progress,
-read [human help and recovery](references/help-and-recovery.md).
+read [human help and recovery](references/help-and-recovery.md) for `bsk_assist`.
 For scripts and files, see [cooperation](references/cooperation.md).
 Interaction recording is not exposed.
 
@@ -78,7 +79,7 @@ Resolve references from the harness-provided skill directory. Read only the matc
 | --- | --- |
 | Website failures, request/performance debugging, or HTTP experiments | [Website debugging](references/debugging.md) |
 | Required profile, borrowing/returning user tabs with `bsk_tabs`, or remote tab ownership | [Tabs and profiles](references/tabs-and-profiles.md) |
-| Hover menus, scrolling, `nextCursor`, console/network, or window/device settings with `bsk_assist` | [Interaction details](references/interaction-details.md) |
+| Drag, step, saved views, hover menus, scrolling, `nextCursor`, console/network, or window/device settings | [Interaction details](references/interaction-details.md) |
 | Screenshot or `[visual:screenshot]`/Canvas interaction | [Screenshots and Canvas](references/screenshots-and-canvas.md) |
 | Video recording or MP4 export | [Video](references/video.md) |
 | Login/CAPTCHA/OTP/consent/payment confirmation, disabled help, failed operations, or interrupted cleanup | [Human help and recovery](references/help-and-recovery.md) |

packages/dsh-plugin-browserskill/skill/references/interaction-details.md

@@ -41,6 +41,33 @@ unsupported wait. If blocked, follow [help and recovery](help-and-recovery.md).
 - `wheel` uses signed `deltaX`/`deltaY`, at least one nonzero. Optional `target` is
   scrolled into view first; otherwise it uses the viewport centre. It reports input,
   not scrolling success: observe afterwards. Focus/blur change focus states.
+- `drag` uses `target` as the source and either `to` or nonzero `deltaX`/`deltaY`.
+  Default mode holds the mouse button while moving. `dragMode: "click-move-click"`
+  requires `to` and zero `holdMs`; it clicks, moves with the button released, then
+  clicks the destination. Pass the observed `contextId` and verify the resulting
+  state. Input delivery does not prove application success.
+
+## Steps and saved observations
+
+`bsk_interact` with `action: "step"` executes one already-decided action, optionally
+waits for `untilVisible`, then synchronizes. Pass `stepAction` and a `params` JSON
+string using protocol fields, for example `params: "{\"ref\":\"e3\"}"` for a click.
+Session, tab, context and dependencies use the outer tool fields. Use only observed
+refs/selectors; the example ref is a placeholder. `waitTimeoutMs` is 1..25000.
+
+Read `ok`, `action`, `readiness` and `post` separately. A later wait, sync or save
+failure does not undo input. Never blindly replay a partial or cancelled step.
+Read `post.context_id` with its observation before planning the next action; if
+absent, wait-user or sync as indicated, then replan.
+
+Use `saveFull` on `bsk_session action: "sync"` or `step` to save a complete reply to
+a new local JSON path. `baseline` may reuse an exact unchanged predecessor.
+Optional `matchText` only folds plain stateless numbered `button "item N"` lines;
+business text, named/stateful controls and complete forms/dialogs remain visible.
+It may not shorten ordinary pages. Use `bsk_inspect action: "view"` with `file` and
+`find` for case-sensitive literal search, or `startLine`/`lineCount` for a bounded
+window. `view` is offline and accepts no session/tab/context/dependencies. Its
+historical refs and context never refresh or authorize a live action.
 
 ## Observation continuation