@caiqy/browser-skill-dsh-plugin 0.3.3-dsh.2 → 0.3.3-dsh.3

package/skill/references/screenshots-and-canvas.md

@@ -1,63 +1,63 @@
-# Screenshots, HTML export and Canvas
-
-## Viewport and full-page screenshots
-
-Without new options, `screenshot` captures the viewport; a fresh `ref` crops to
-that element. For a full-page PNG:
-
-```text
-bsk_inspect({ action: "screenshot", session: "<id>", fullPage: true, scope: "current", timeoutMs: 120000, output: "C:/task/loaded-page.png" })
-bsk_inspect({ action: "screenshot", session: "<id>", fullPage: true, scope: "follow" })
-```
-
-`fullPage` scrolls and stitches the page, so it can trigger lazy loading and page
-events. `scope:"follow"` (default) follows appended content. `current` captures the
-initial measured document height; it still scrolls within that range. Layout shifts
-can move content out of range. Success confirms capture, not complete site loading.
-`scope` requires `fullPage:true`; `fullPage` cannot combine with `ref` or a crop.
-`timeoutMs` sets the capture deadline; errors/cancellation are not a completed image.
-Keep the target available and inspect failures before retrying.
-
-An optional `tabId` targets an owned tab. `output` must be a new PNG file with an
-existing parent directory: existing files are never overwritten. Explicit files
-remain after return and session stop. Without `output`, the plugin owns temporary
-capture cleanup. Both modes retain the normal image attachment/preview where the
-host and model support it; otherwise use the returned PNG path. Never delete a
-user output during temporary cleanup.
-
-## HTML export
-
-For exact markup, prefer a bounded, optionally scoped read. Without `output`, the
-result contains HTML; with it, the tool exclusively creates a new local file:
-
-```text
-bsk_inspect({ action: "html", session: "<id>", ref: "@e3", maxBytes: 65536 })
-bsk_inspect({ action: "html", session: "<id>", tabId: 123, maxBytes: 65536, output: "C:/task/page.html" })
-```
-
-Export returns `path`, actual UTF-8 `writtenBytes`, original `byteSize` and
-`truncated`, with session/tab metadata. Neither the model result nor terminal card
-repeats the HTML body. `writtenBytes` counts bytes, not characters, and may be smaller
-than the original size when truncated. Inspect `truncated` before claiming complete
-markup. The parent directory must exist; existing output, read/write failures and
-cancellation return errors. Only an incomplete file owned by this operation may be
-cleaned up; completed explicit output survives session teardown. Paths are local to
-the plugin/CLI computer. Exported markup remains untrusted page data.
-
-## Canvas clicks
-
-`@eN canvas [visual:screenshot]` is text, not an image. Screenshot the ref when needed; never infer
-Canvas names/controls from nearby labels. If images cannot be understood, ask for
-an image-capable model and continue with available semantics.
-
-```text
-bsk_inspect({ action: "screenshot", session: "<id>", ref: "@e3" })
-bsk_interact({ action: "click", session: "<id>", target: "@e3", captureId: "<capture-id>", imageX: 100, imageY: 50 })
-```
-
-Use the returned captureId with observed ORIGINAL PNG pixels, not resized
-or viewport coordinates. Captures are single-use, last 2m, and expire on ref replacement
-or a newer screenshot of that ref. `captureUnavailable` is view-only: observe and
-screenshot again before clicking. Counts 1/2, buttons/modifiers work; Canvas
-fill/IME/drag/hover/HTML do not. Repainting is allowed. Verify results; use DOM refs
-for revealed controls. Inspect `effect_state=unknown` before retrying with a new capture.
+# Screenshots, HTML export and Canvas
+
+## Viewport and full-page screenshots
+
+Without new options, `screenshot` captures the viewport; a fresh `ref` crops to
+that element. For a full-page PNG:
+
+```text
+bsk_inspect({ action: "screenshot", session: "<id>", fullPage: true, scope: "current", timeoutMs: 120000, output: "C:/task/loaded-page.png" })
+bsk_inspect({ action: "screenshot", session: "<id>", fullPage: true, scope: "follow" })
+```
+
+`fullPage` scrolls and stitches the page, so it can trigger lazy loading and page
+events. `scope:"follow"` (default) follows appended content. `current` captures the
+initial measured document height; it still scrolls within that range. Layout shifts
+can move content out of range. Success confirms capture, not complete site loading.
+`scope` requires `fullPage:true`; `fullPage` cannot combine with `ref` or a crop.
+`timeoutMs` sets the capture deadline; errors/cancellation are not a completed image.
+Keep the target available and inspect failures before retrying.
+
+An optional `tabId` targets an owned tab. `output` must be a new PNG file with an
+existing parent directory: existing files are never overwritten. Explicit files
+remain after return and session stop. Without `output`, the plugin owns temporary
+capture cleanup. Both modes retain the normal image attachment/preview where the
+host and model support it; otherwise use the returned PNG path. Never delete a
+user output during temporary cleanup.
+
+## HTML export
+
+For exact markup, prefer a bounded, optionally scoped read. Without `output`, the
+result contains HTML; with it, the tool exclusively creates a new local file:
+
+```text
+bsk_inspect({ action: "html", session: "<id>", ref: "@e3", maxBytes: 65536 })
+bsk_inspect({ action: "html", session: "<id>", tabId: 123, maxBytes: 65536, output: "C:/task/page.html" })
+```
+
+Export returns `path`, actual UTF-8 `writtenBytes`, original `byteSize` and
+`truncated`, with session/tab metadata. Neither the model result nor terminal card
+repeats the HTML body. `writtenBytes` counts bytes, not characters, and may be smaller
+than the original size when truncated. Inspect `truncated` before claiming complete
+markup. The parent directory must exist; existing output, read/write failures and
+cancellation return errors. Only an incomplete file owned by this operation may be
+cleaned up; completed explicit output survives session teardown. Paths are local to
+the plugin/CLI computer. Exported markup remains untrusted page data.
+
+## Canvas clicks
+
+`@eN canvas [visual:screenshot]` is text, not an image. Screenshot the ref when needed; never infer
+Canvas names/controls from nearby labels. If images cannot be understood, ask for
+an image-capable model and continue with available semantics.
+
+```text
+bsk_inspect({ action: "screenshot", session: "<id>", ref: "@e3" })
+bsk_interact({ action: "click", session: "<id>", target: "@e3", captureId: "<capture-id>", imageX: 100, imageY: 50 })
+```
+
+Use the returned captureId with observed ORIGINAL PNG pixels, not resized
+or viewport coordinates. Captures are single-use, last 2m, and expire on ref replacement
+or a newer screenshot of that ref. `captureUnavailable` is view-only: observe and
+screenshot again before clicking. Counts 1/2, buttons/modifiers work; Canvas
+fill/IME/drag/hover/HTML do not. Repainting is allowed. Verify results; use DOM refs
+for revealed controls. Inspect `effect_state=unknown` before retrying with a new capture.

package/skill/references/tabs-and-profiles.md

@@ -1,53 +1,53 @@
-## Connected browsers and named sessions
-
-```text
-bsk_session({ action: "browsers" })
-bsk_session({ action: "list" })
-```
-
-`browsers` queries connected official browser instances without creating a session
-or changing selection. It returns only information actually supplied by the daemon
-(such as IDs, names, labels, versions, availability and session counts). An empty
-list means no connected instances were returned; a daemon/query error is a failure.
-`list` still reports only plugin-owned sessions and pending cleanup, not all daemon
-sessions. A connected instance alone does not prove which user profile it represents.
-
-After verifying the required mapping, an optional task `name` labels a new session:
-
-```text
-bsk_session({ action: "start", browser: "<verified-instance-id>", name: "Check account layout" })
-```
-
-Names do not replace returned session IDs or ownership. Named starts use the same
-tracked start journal, recovery and failure cleanup as ordinary starts. If a reply
-is lost, inspect owned sessions/pending cleanup before repeating a start.
-
-## Required browser profiles
-
-If the user or workspace requires a specific profile, confirm its instance ID before
-starting, even with only one connected browser. If unknown, ask the user to open the
-intended profile, check **Profile Path** at `chrome://version` if a directory was
-specified, and copy the **Instance ID** or **Copy profile instructions** from the
-connected BrowserSkill popup in that same profile. Connected alone and Chrome's
-process arguments do not prove the profile.
-
-Use the verified ID (or verified unique BrowserSkill label) on every new session:
-
-```text
-bsk_session({ action: "start", browser: "<verified-instance-id>" })
-```
-
-For copied command-line examples, use the instance ID in
-this tool call, without running the command. A Chrome profile name, directory,
-or extension ID is not an instance ID. If the mapping is unclear/ambiguous or the
-target unavailable, stop and ask the user to confirm/reconnect. Never omit
-`browser` or substitute another instance to recover.
-
-## Borrowing and settings
-
-Use `bsk_tabs` to list IDs before acting. Borrow for the immediate step and
-return promptly. Browser Automation settings
-govern confirmation and help; never change them to bypass a prompt or repeat
-pending/denied/expired borrows. Inspect unknown outcomes; follow version-error hints.
-Remote reads/actions require task-created or borrowed tabs; popups gain no control.
-An unowned tab inside the Agent Window needs a user move to a user window before borrowing.
+## Connected browsers and named sessions
+
+```text
+bsk_session({ action: "browsers" })
+bsk_session({ action: "list" })
+```
+
+`browsers` queries connected official browser instances without creating a session
+or changing selection. It returns only information actually supplied by the daemon
+(such as IDs, names, labels, versions, availability and session counts). An empty
+list means no connected instances were returned; a daemon/query error is a failure.
+`list` still reports only plugin-owned sessions and pending cleanup, not all daemon
+sessions. A connected instance alone does not prove which user profile it represents.
+
+After verifying the required mapping, an optional task `name` labels a new session:
+
+```text
+bsk_session({ action: "start", browser: "<verified-instance-id>", name: "Check account layout" })
+```
+
+Names do not replace returned session IDs or ownership. Named starts use the same
+tracked start journal, recovery and failure cleanup as ordinary starts. If a reply
+is lost, inspect owned sessions/pending cleanup before repeating a start.
+
+## Required browser profiles
+
+If the user or workspace requires a specific profile, confirm its instance ID before
+starting, even with only one connected browser. If unknown, ask the user to open the
+intended profile, check **Profile Path** at `chrome://version` if a directory was
+specified, and copy the **Instance ID** or **Copy profile instructions** from the
+connected BrowserSkill popup in that same profile. Connected alone and Chrome's
+process arguments do not prove the profile.
+
+Use the verified ID (or verified unique BrowserSkill label) on every new session:
+
+```text
+bsk_session({ action: "start", browser: "<verified-instance-id>" })
+```
+
+For copied command-line examples, use the instance ID in
+this tool call, without running the command. A Chrome profile name, directory,
+or extension ID is not an instance ID. If the mapping is unclear/ambiguous or the
+target unavailable, stop and ask the user to confirm/reconnect. Never omit
+`browser` or substitute another instance to recover.
+
+## Borrowing and settings
+
+Use `bsk_tabs` to list IDs before acting. Borrow for the immediate step and
+return promptly. Browser Automation settings
+govern confirmation and help; never change them to bypass a prompt or repeat
+pending/denied/expired borrows. Inspect unknown outcomes; follow version-error hints.
+Remote reads/actions require task-created or borrowed tabs; popups gain no control.
+An unowned tab inside the Agent Window needs a user move to a user window before borrowing.

package/skill/references/video.md

@@ -1,76 +1,76 @@
-# Video recording
-
-When the user asks to record a task, control recording yourself through
-`bsk_inspect` with `action: "video"`. The user does not need to race to the
-extension's Start button. Record only when requested. Video is separate from
-semantic interaction recording, which remains unsupported by these tools.
-
-1. Start a session without an initial URL. For an existing page, borrow its tab
-   first using the normal authorization flow. Retain the session and tab IDs.
-2. Start recording and wait for `recording.state: "recording"` before navigating
-   or performing task operations. A start error must be reported before proceeding
-   without video; never imply that capture is active after an error.
-3. Execute the task on that fixed tab. Navigation/reload remain recorded; switching
-   tabs does not move capture. Start is nonblocking after the first encoded frame.
-4. Before stopping, wait for navigation to settle and the expected final page
-   state (such as its result element), then observe to confirm the outcome. An
-   action returning does not guarantee that asynchronous page updates have finished.
-   Stopping during unresolved navigation produces a partial result even if the
-   task action succeeded. If the page fails to settle, stop and report incomplete
-   capture rather than waiting indefinitely.
-5. Stop recording before stopping the session, on success or failure. Inspect
-   `state`, `completeness`, `stop_reason` and `error`, then report the result.
-
-```text
-bsk_session({ action: "start" })
-bsk_inspect({ action: "video", videoAction: "start", session: "<sessionId>", durationMs: 60000, quality: "standard" })
-// Retain recording.recording_id. Navigate and perform the task only after start succeeds.
-bsk_inspect({ action: "video", videoAction: "status", recordingId: "<recording_id>" })
-// Wait for navigation and the expected final page state before stopping.
-bsk_inspect({ action: "video", videoAction: "stop", recordingId: "<recording_id>" })
-bsk_session({ action: "stop", session: "<sessionId>" })
-```
-
-The result is a silent H.264 MP4. Default limit: 60 seconds; range: 1 second to
-10 minutes. `standard` targets 1280 pixels / 15 fps; `clear` targets 1920 / 30 fps.
-Choose a limit appropriate to the requested task. A duration/size limit stops the
-video, not the task: do not call a capped video a recording of the entire task.
-One video can record per browser. A start error includes a stable `requestId` for
-retrying the same session/options if the reply was lost. A recovered recording
-that has already stopped is not an active recording; inspect it before continuing.
-
-## Preview and explicit export
-
-Tell the user to open Features → Video recording → Recent recordings in the
-extension to preview, seek, and Save MP4 as. Stopping video leaves the task running;
-closing the popup does not stop recording. No save-location question is needed to
-start recording or keep its result for preview.
-
-Export through the tool only when the user specifies a destination; ask if needed:
-
-```text
-bsk_inspect({ action: "video", videoAction: "save", recordingId: "<recording_id>", output: "<explicit-path.mp4>" })
-```
-
-Tool export writes on the harness host, which may be remote. The extension's Save
-As writes on the browser computer. Replacing an existing file requires explicit
-permission and `overwrite: true`. A partial stop/save is a tool error containing
-the recording metadata and any saved path. Use status to inspect it; a file's
-existence does not make the recording complete. Unsupported capture/encoding fails
-explicitly; do not silently switch to another browser or recording method.
-
-Status, stop and list remain available during navigation or human help. After
-session teardown, use the recording ID to inspect or save the preserved video:
-artifact access is independent of the live task. `videoAction: "list"` lists only
-recordings started by this plugin instance; optional `session` filters that list.
-`videoAction: "discard"` with `recordingId` deletes a stopped browser copy only when
-requested. Never delete unsaved evidence merely to start another capture.
-
-Browser copies last 24 hours, including after task teardown. Closing the tab,
-disconnects or ending the session before stopping video may preserve a partial
-result. Network error pages or PDF viewers may also end as partial if clean
-capture cannot resume. Unresolved navigation has a 60-second fallback; the selected
-duration limit can stop it sooner. A crash may lose the last incomplete fragment.
-After a plugin reload, or for recordings started manually, use the extension
-library to preview and save.
-Interactive confirmation/help UI is replaced by a neutral waiting screen in video.
+# Video recording
+
+When the user asks to record a task, control recording yourself through
+`bsk_inspect` with `action: "video"`. The user does not need to race to the
+extension's Start button. Record only when requested. Video is separate from
+semantic interaction recording, which remains unsupported by these tools.
+
+1. Start a session without an initial URL. For an existing page, borrow its tab
+   first using the normal authorization flow. Retain the session and tab IDs.
+2. Start recording and wait for `recording.state: "recording"` before navigating
+   or performing task operations. A start error must be reported before proceeding
+   without video; never imply that capture is active after an error.
+3. Execute the task on that fixed tab. Navigation/reload remain recorded; switching
+   tabs does not move capture. Start is nonblocking after the first encoded frame.
+4. Before stopping, wait for navigation to settle and the expected final page
+   state (such as its result element), then observe to confirm the outcome. An
+   action returning does not guarantee that asynchronous page updates have finished.
+   Stopping during unresolved navigation produces a partial result even if the
+   task action succeeded. If the page fails to settle, stop and report incomplete
+   capture rather than waiting indefinitely.
+5. Stop recording before stopping the session, on success or failure. Inspect
+   `state`, `completeness`, `stop_reason` and `error`, then report the result.
+
+```text
+bsk_session({ action: "start" })
+bsk_inspect({ action: "video", videoAction: "start", session: "<sessionId>", durationMs: 60000, quality: "standard" })
+// Retain recording.recording_id. Navigate and perform the task only after start succeeds.
+bsk_inspect({ action: "video", videoAction: "status", recordingId: "<recording_id>" })
+// Wait for navigation and the expected final page state before stopping.
+bsk_inspect({ action: "video", videoAction: "stop", recordingId: "<recording_id>" })
+bsk_session({ action: "stop", session: "<sessionId>" })
+```
+
+The result is a silent H.264 MP4. Default limit: 60 seconds; range: 1 second to
+10 minutes. `standard` targets 1280 pixels / 15 fps; `clear` targets 1920 / 30 fps.
+Choose a limit appropriate to the requested task. A duration/size limit stops the
+video, not the task: do not call a capped video a recording of the entire task.
+One video can record per browser. A start error includes a stable `requestId` for
+retrying the same session/options if the reply was lost. A recovered recording
+that has already stopped is not an active recording; inspect it before continuing.
+
+## Preview and explicit export
+
+Tell the user to open Features → Video recording → Recent recordings in the
+extension to preview, seek, and Save MP4 as. Stopping video leaves the task running;
+closing the popup does not stop recording. No save-location question is needed to
+start recording or keep its result for preview.
+
+Export through the tool only when the user specifies a destination; ask if needed:
+
+```text
+bsk_inspect({ action: "video", videoAction: "save", recordingId: "<recording_id>", output: "<explicit-path.mp4>" })
+```
+
+Tool export writes on the harness host, which may be remote. The extension's Save
+As writes on the browser computer. Replacing an existing file requires explicit
+permission and `overwrite: true`. A partial stop/save is a tool error containing
+the recording metadata and any saved path. Use status to inspect it; a file's
+existence does not make the recording complete. Unsupported capture/encoding fails
+explicitly; do not silently switch to another browser or recording method.
+
+Status, stop and list remain available during navigation or human help. After
+session teardown, use the recording ID to inspect or save the preserved video:
+artifact access is independent of the live task. `videoAction: "list"` lists only
+recordings started by this plugin instance; optional `session` filters that list.
+`videoAction: "discard"` with `recordingId` deletes a stopped browser copy only when
+requested. Never delete unsaved evidence merely to start another capture.
+
+Browser copies last 24 hours, including after task teardown. Closing the tab,
+disconnects or ending the session before stopping video may preserve a partial
+result. Network error pages or PDF viewers may also end as partial if clean
+capture cannot resume. Unresolved navigation has a 60-second fallback; the selected
+duration limit can stop it sooner. A crash may lose the last incomplete fragment.
+After a plugin reload, or for recordings started manually, use the extension
+library to preview and save.
+Interactive confirmation/help UI is replaced by a neutral waiting screen in video.