Introduction¶
When developing DSH plugins, a common debugging dilemma is that a certain function can only be verified in a foreground session, while the plugin itself runs within a tool call and cannot access the capabilities of the foreground session. When the model wants to confirm “whether this workflow can actually run under real human operation,” it often has to take the roundabout route—digging through browser cookies, guessing RPC parameters, or modifying the DOM. elfgzp/dsh-session-bridge consolidates these detours into a set of standard tool calls.
This introduction is based on the repository’s README and package.json, explaining what it can do, how to install it, and what to watch out for when using it.
What is it¶
dsh-session-bridge is a DSH plugin maintained by elfgzp, categorized under workflows. It exposes two sets of capabilities that already exist on the Host but are invisible to the model tools: ctx.sessionController (create, prompt, check, cancel sessions) and ctx.connection.authenticatedUrl() (local Web App address with a launch token). The one-sentence positioning in the README is: to let the DeepSeek Harness agent open foreground sessions, drive them, read the results back, and hand over the authenticated URL of the local Web App.
Core Features¶
The plugin provides five tools:
| Tool | Function |
|---|---|
dsh_web_url |
Returns the local Web GUI address, with the launch token hidden by default; pass includeToken: true to get a URL that can be opened directly in the browser (requires the danger-full-access preset). |
dsh_session_create |
Creates a foreground session and returns its ID. |
dsh_session_prompt |
Sends a prompt to the session, supporting two modes: queue and steer. |
dsh_session_read |
Reads session records; waitMs can be used to wait for the current turn to end. |
dsh_session_cancel |
Cancels the currently running turn in the session. |
Difference Between Foreground Sessions and Delegated Tasks¶
This is the reason the plugin exists. The README explains it quite directly:
- Foreground sessions are root agents with the
userQuestionsservice; they can actually ask when human approval is needed. - Delegated tasks (sub-agents, workflow agents) do not have this service; when called, they receive
APP_APPROVAL_UNAVAILABLE: Application approval is unavailable in delegated tasks; ask the main task to perform this operation.
Therefore, plugins that require human confirmation (the README cites elfgzp/dsh-cua-macos as an example) can only work end-to-end through foreground sessions, and these five tools are responsible for creating such sessions.
Token Handling¶
The launch token generated by connection.authenticatedUrl() is a valid credential: any browser opening this URL will receive an authenticated session, and the tool’s return value enters the conversation history, thereby entering logs, exports, and chat copies.
Therefore, the default behavior is maskToken: returning the origin and truncating the token in the URL to the first and last four characters. Only pass includeToken: true when you actually need to open the browser, and do not persist or paste the result.
includeToken: true is restricted by the caller’s permission preset. The tool queries the permissionPresets service for the current session’s preset (current(session)) and parses it into { sandbox, approval }. It only returns the plaintext token if sandbox === "danger-full-access", while other presets unconditionally return insufficient-permission and the masked URL.
The README explicitly states that this gate is fail-closed: if permissionPresets is missing, resolve() cannot handle custom, any call throws an error, or execution.agent.session is unavailable, the result is “no token” rather than “allow through”.
Installation and Activation¶
dsh plugin --profile <profile> add github:elfgzp/dsh-session-bridge
Restart DSH after installation. The plugin has no dependencies. The repository requires engines.dsh to be >=0.2.0, and the license is MIT.
Typical Usage¶
The example given in the README is for an agent to verify a function that can only be done in a foreground session:
You have a function that can only be verified in a foreground session. Please:
1. Use dsh_session_create to create a session
2. Use dsh_session_prompt to make it do that thing
3. Use dsh_session_read (waitMs=120000) to read the results back
The three steps correspond to create, prompt, and read in the tool list, with no cookie or DOM manipulation involved in between.
The repository includes tests:
npm test # node --test test/*.test.mjs
lib/format.js contains pure functions (maskToken, clip, reasonLabel, transcribe, waitForTurn) that do not depend on the Host; tests can run on standard Node 20. test/web-url.test.mjs uses apply() with a fake ctx to cover the permission gate and all fail-closed paths.
Suitable Scenarios and Notes¶
Suitable for DSH plugin developers who need to verify functions in real foreground sessions or need to hand over the local Web App address to external processes.
A few usage notes:
dsh_session_readwill truncate long text and return a maximum ofmaxMessagesmessages (default 40). Long sessions need to be read in segments.- Session records include tool calls and their results, so auditing is possible even if the session used other tools.
dsh_web_urldepends on thewebAppservice; headless deployments do not have this service, so the tool will indicate this rather than throwing an error directly.- This plugin is a third-party project in the community directory and runs with the permissions of the current dsh process. Before installing, you should read the source code and confirm that the license (MIT) meets your usage requirements.
Summary¶
The value of dsh-session-bridge lies not in new features, but in bringing operations previously hidden in the browser and RPC layers into standard tool calls, allowing agents to truly enter foreground sessions for verification.
- Community Directory Page: https://www.skillhub.cn/plugins/elfgzp/dsh-session-bridge
- GitHub: https://github.com/elfgzp/dsh-session-bridge
