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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tencent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,301 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# BrowserSkill for DeepSeek Harness
+
+[![npm version](https://img.shields.io/npm/v/@caiqy/browser-skill-dsh-plugin)](https://www.npmjs.com/package/@caiqy/browser-skill-dsh-plugin)
+
+Use [BrowserSkill](https://github.com/Tencent/BrowserSkill) in
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) to browse
+websites, fill forms, and capture screenshots through native `bsk_*` tools.
+Browser tasks run in Agent Windows, with a live view in the dsh Web UI.
+
+This fork publishes `0.3.3-dsh.2` as `@caiqy/browser-skill-dsh-plugin`, carrying
+the local enhancements over official `0.3.3`. The official package remains
+`@wxg-prc-cpg/browser-skill-dsh-plugin`. Install only one of the two packages in a
+profile: they register the same `bsk_*` tools and observation routes.
+See [DSH enhancement delivery notes](https://github.com/caiqy/BrowserSkill/blob/dsh/plugin-parity-0.3.3/packages/dsh-plugin-browserskill/docs/dsh-enhancement.md)
+for the baseline, structured examples and actual verification boundaries.
+
+## Installation
+
+Before installing the plugin:
+
+- Install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and
+  [pnpm](https://pnpm.io/installation), which dsh uses to manage plugins.
+- Install the `bsk` CLI and connect the BrowserSkill extension in Chrome or Edge.
+  Follow the [BrowserSkill setup guide](https://github.com/Tencent/BrowserSkill#quick-start).
+- Make sure `bsk` is on the `PATH` used to start dsh, or set `bskPath` in the plugin configuration.
+
+Install the plugin into the `web` profile, then start it:
+
+```sh
+dsh plugin --profile web add @caiqy/browser-skill-dsh-plugin@0.3.3-dsh.2
+dsh --profile web
+```
+
+Replace `web` with your profile name if you use a different profile. The plugin
+includes the complete `browser-skill` package; no separate `bsk install-skill` step is needed.
+Its compact entry point loads first; references ship with the plugin and are read only
+when needed. Relative paths resolve from the packaged skill directory, not your project.
+
+In a conversation, try:
+
+```text
+/browser-skill open example.com and summarize the page.
+```
+
+By default, the browser tools become available when the skill is invoked.
+
+The plugin declares support for DSH `^0.1.5-rc.3 || ^0.2.0-rc.1`.
+DSH 0.2 checks these peer requirements before loading the plugin; versions outside
+this range are not declared compatible. The range preserves the existing 0.1.x
+baseline and admits 0.2.x without opting into future 0.3.x hosts.
+
+## Updating
+
+Installed plugins do not update automatically. Install this exact fork release:
+
+```sh
+dsh plugin --profile web add @caiqy/browser-skill-dsh-plugin@0.3.3-dsh.2
+```
+
+To follow the fork's current release, install `@caiqy/browser-skill-dsh-plugin@dsh`.
+The fork publishes prereleases under the npm `dsh` dist-tag.
+See the [manual update/rollback procedure](https://github.com/caiqy/BrowserSkill/blob/dsh/plugin-parity-0.3.3/packages/dsh-plugin-browserskill/docs/dsh-enhancement.md#更新与回退).
+Restart that dsh profile after upgrading. This command updates the plugin; update
+the `bsk` CLI and browser extension separately when a release requires it.
+
+### Breaking tool API migration (0.3.3)
+
+The coordinated 0.3.3 release replaces all six `browser_*` tool names with stable
+BrowserSkill-specific names. This avoids collisions with other browser plugins
+such as `dsh-builtin-browser`; both plugins keep their own tools and sessions.
+
+| Previous name | New name |
+| --- | --- |
+| `browser_session` | `bsk_session` |
+| `browser_page` | `bsk_page` |
+| `browser_inspect` | `bsk_inspect` |
+| `browser_interact` | `bsk_interact` |
+| `browser_tabs` | `bsk_tabs` |
+| `browser_assist` | `bsk_assist` |
+
+The tool-name migration leaves actions, parameters, results and `/browser-skill`
+unchanged. The old tool
+names are not registered as aliases. After upgrading, restart the DSH profile and
+invoke `/browser-skill` again in existing conversations to load the new instructions.
+Update hardcoded tool calls, allow/deny lists, and `toolOrder` entries to the new
+names. Do not replay old calls unchanged: another plugin may own those names.
+
+Existing conversation logs and screenshot attachments are left intact. New
+`bsk_inspect` results use the screenshot view; old `browser_inspect` cards may use
+DSH's generic renderer and do not retain the custom thumbnail/preview interaction.
+This is a breaking change from 0.3.2. Upgrade the CLI and browser extension to
+0.3.3 before upgrading this plugin to use the new video, extraction and element-wait
+capabilities. Updating the npm package does not update either component.
+
+## Tools
+
+| Tool | Actions | Purpose |
+| --- | --- | --- |
+| `bsk_session` | `start`, `stop`, `list`, `browsers` | Manage plugin-owned sessions; query connected browser instances. |
+| `bsk_page` | `navigate`, `back`, `forward`, `reload`, `wait`, `wait-for-element`, `wait-ms` | Navigate; wait for lifecycle events, an element condition, or a fixed delay. |
+| `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, evaluate page scripts and transfer local files. |
+| `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. |
+
+For `bsk_page` with `action: "wait-for-element"`, see the
+[element-wait reference](skill/references/interaction-details.md#element-waits) for
+supported conditions, timeout results and recovery with existing single actions.
+
+For native wheel input (`action: "wheel"`), see the [wheel reference](../../docs/wheel.md)
+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_inspect` with `action: "extract"`, see
+[structured extraction](../../docs/structured-extraction.md) for discovery, list
+fields, JSON/CSV output and loaded-DOM completeness.
+
+Page-script evaluation is available through `bsk_interact` with `action: "evaluate"`.
+The local enhancement also adds full-page screenshots, HTML file export, hover
+probes, extended emulation and named sessions; see the [structured examples](docs/dsh-enhancement.md#结构化工具示例).
+User interaction trace recording remains unsupported; existing task video is separate.
+
+### Activation failures
+
+The six tools register as a complete suite. If any registration fails, the plugin
+rolls back that attempt and reports the failing tool through DSH's logger. A model
+invocation of `skill` returns an error instead of claiming successful activation;
+slash-command and restored conversations receive a scoped notice. Unrelated
+conversations continue normally, and repeated identical failures do not flood logs.
+
+Resolve the reported registration error, then invoke `/browser-skill` again or
+start the next turn to retry. Session entry and service discovery also retry a
+pending activation; streaming events do not. The affected conversation receives
+one recovery notice. If the failed model call never delivered the skill body,
+the notice asks the model to load it before using the tools. With `lazyTools: false`,
+a registration failure fails plugin startup and releases its resources; reload
+after fixing it.
+
+## Multi-session model
+
+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
+  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.
+- 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.
+
+Starts are journaled before creating a window. Lost replies and failed cleanup remain
+recoverable on reload; `bsk_session action=list` reports `pendingCleanup`, and stop
+can retry it even when there is no current session. This requires a CLI and daemon
+that support recoverable starts. See [the lifecycle contract](../../docs/recoverable-session-starts.md).
+
+Stops also retain their target and cleanup intent. A failed or interrupted stop can be
+retried without accidentally stopping the next current session. Once the intent is saved,
+cancelling the call only stops waiting; cleanup continues in the background. If it finishes
+before a retry, that retry acknowledges the original result. With several unacknowledged
+stops, pass `session` or the owned `requestId` explicitly (not both). List exposes request
+IDs; stop results include `requestId` and `alreadyClosed`. Completed receipts survive reload
+until acknowledged and do not occupy browser capacity.
+
+**Ownership boundary**: the bsk daemon may be shared with other agents, terminals, or dsh
+instances. The plugin therefore only ever sees and operates on sessions it created itself —
+an explicit `session` argument naming a foreign or unknown id is rejected, the `list` action on
+`bsk_session` shows plugin-created sessions only (no daemon-wide view), and stop/unload cleanup
+can never touch a session owned by another program.
+
+## Configuration
+
+After installing the plugin, edit your profile's `cordis.patch.yml`. For the `web`
+profile, the default location is `~/.dsh/profiles/web/cordis.patch.yml`. If you set
+`DSH_HOME`, use `$DSH_HOME/profiles/web/cordis.patch.yml` instead. Replace `web` with
+your profile name as needed.
+
+If the file contains only comments and `[]`, keep the comments and replace `[]`
+with the YAML below. If it already contains patch entries, add this entry to the
+existing list or edit its existing `id: browserskill` entry. Keep a single
+top-level YAML list. This overrides the plugin registered by the installed bundle:
+
+```yaml
+- id: browserskill
+  config:
+    bskPath: bsk
+    defaultTimeoutMs: 120000
+    maxSessions: 5
+    observationEnabled: true
+    thumbnailIntervalMs: 1500
+    idleIntervalMs: 8000
+    lazyTools: true
+```
+
+Change `bskPath` to the full path of your CLI binary if it is not on dsh's `PATH`.
+A patch replaces the entry's entire `config` object, so keep all overrides you need
+together in that object.
+
+Configuration changes follow `dsh.profile.patchReload` in the profile's
+`package.json`: `live` (the default for `web`) applies changes when you save the
+patch file; `startup` requires restarting the profile. Restart after upgrading
+the plugin in either case.
+
+All fields are optional; omitted fields use the defaults below:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `bskPath` | `bsk` | Path to the CLI binary. |
+| `sessionStateDirectory` | Scoped under `$BSK_HOME/dsh-starts` (or `~/.bsk/dsh-starts`) | Durable recovery records; optionally isolate by host/profile. |
+| `defaultTimeoutMs` | `120000` | Default command execution timeout in milliseconds; output collection after exit has a separate 2-second limit. |
+| `maxSessions` | `5` | Maximum concurrent sessions started by this plugin. |
+| `observationEnabled` | `true` | Enable live browser observation. |
+| `thumbnailIntervalMs` | `1500` | Screenshot interval for active sessions, in milliseconds. |
+| `idleIntervalMs` | `8000` | Screenshot interval for idle sessions and the recent-activity window, in milliseconds. |
+| `lazyTools` | `true` | Reveal the browser tools when the skill is invoked. Set `false` to register them at startup. |
+
+With `lazyTools: true`, only the skill's catalog entry is initially advertised to
+the model. A successful model `skill` call makes the six `bsk_*` schemas available
+in the next step. A user `/browser-skill` gesture activates them when the host
+claims the input, before prompt assembly, so the first request includes both the
+skill instructions and tool schemas. Set `lazyTools: false` to register at startup.
+
+After a plugin reload, a live or resumed conversation's successful skill invocation
+restores the tools from its stored history. If an older plugin reports
+`unknown tool "bsk_session"`, invoke `skill browser-skill` again, or set
+`lazyTools: false` in the profile patch as a temporary workaround.
+
+## Live browser view
+
+The dsh Web UI prefers a **Browser Skill** tab in DSH's native right sidebar.
+The native tab opens when the current conversation first has a browser session;
+ordinary screenshot and action updates do not switch tabs or reopen a tab you
+closed. You can reopen it from the sidebar's guide.
+
+The native sidebar is optional. Profiles without its services use a floating
+panel, and a failed native integration falls back to that panel. No
+`dsh-better-sidebar` installation is required; it can coexist with BrowserSkill,
+which registers directly with DSH rather than with the third-party sidebar.
+
+- See the current action, elapsed time, and recent screenshot for each session.
+- Select a session to focus on it. The sidebar view follows the current conversation.
+- Use **Use floating view** to move observation into a floating panel, and
+  **Move to sidebar** (or **Show here** in the tab) to return. This choice lasts
+  only until the page reloads; it is not saved in your profile or browser storage.
+- Use **Interrupt** to cancel the current browser command. The agent may continue
+  with another action afterward.
+- Drag or resize the floating panel, or use **Pop out** to open a Picture-in-Picture
+  window in browsers that support it.
+- Periodic screenshots are requested while a browser observation view is visible.
+  Configure the active and idle intervals with the options above.
+
+The floating panel shows all browser sessions managed by this plugin instance;
+the native tab shows the current conversation's browsers and those of its subagents.
+
+The observation endpoints require a loopback address such as `localhost` or
+`127.0.0.1`. Access through a LAN hostname or non-loopback reverse proxy is not supported.
+
+## Development
+
+```sh
+pnpm install
+pnpm --filter @caiqy/browser-skill-dsh-plugin typecheck
+pnpm --filter @caiqy/browser-skill-dsh-plugin test     # unit tests mock bsk; no browser needed
+pnpm --filter @caiqy/browser-skill-dsh-plugin build    # tsdown -> lib/
+```
+
+See the [development notes](https://github.com/Tencent/BrowserSkill/blob/main/packages/dsh-plugin-browserskill/docs/development.md)
+for skill registration, tool results, and observation APIs in the current source.
+
+## Publishing
+
+This fork is published manually from the independent BrowserSkill workspace.
+Run the package's typecheck, build and tests, then `node scripts/check-dsh-package.mjs`.
+Pack the built package with `npm pack --ignore-scripts` and publish the inspected
+archive with `npm publish <archive.tgz> --access public --tag dsh --registry=https://registry.npmjs.org/`.
+
+Publish only `@caiqy/browser-skill-dsh-plugin`; the official
+`@wxg-prc-cpg/browser-skill-dsh-plugin` package is maintained upstream.
+Use the `caiqy-dsh-plugin-v<version>` tag for fork releases, which does not trigger
+the inherited upstream release workflow. Push the fork commit before updating the
+parent workspace's submodule pointer and market index.
+
+Keep the official 0.3.3 CLI and extension installed separately. Publishing this
+plugin does not update those components. Published npm versions cannot be overwritten.
+
+## License
+
+MIT
+
+## Task video recording
+
+Ask the agent to record before it performs the task. It starts an authorized task
+tab, confirms recording is active, performs the task, then stops video before
+ending the session. No manual Start click is required. Preview and Save As are in
+the extension's Features → Video recording → Recent recordings.
+
+`bsk_inspect` with `action: "video"` exposes `videoAction` start/status/stop/save/
+list/discard. The default is a silent, fixed-tab MP4 with a 60-second limit (up to
+10 minutes). Export requires an explicit `output` path on the harness host; the
+extension's Save As writes on the browser computer. Partial recordings and limits
+are reported explicitly. See the [video reference](skill/references/video.md).

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: browserskill
+      # Must be the published package name — the loader imports this specifier.
+      # Quoted because YAML reserves a leading '@' in plain scalars.
+      name: "@caiqy/browser-skill-dsh-plugin"