DSH Beacon
English | 中文
DSH Beacon is an installable DeepSeek Harness bundle for supervising concurrent Sessions. It combines deterministic activity projection, attention ordering, bounded generated briefs, a /brief command, a draggable activity beacon, a global workbench, and a per-Session Context view in one package.
The npm package lives at the repository root and owns the complete feature closure. Its single Cordis Loader row mounts the activity, brief, LLM-provider, and command plugins as child fibers, while the package exposes one Web Client entry. This avoids requiring unpublished @deepseek-ai/dsh-session-* packages and remains compatible with the DSH Client loader's one-source-per-package rule.
Compatibility
| Component | Supported version |
|---|
| DeepSeek Harness packages | First release in >=0.1.2-alpha.6 <0.1.3 that includes SessionEventIntent and the session-brief LLM purpose |
| Cordis | 4.0.2 |
| Node.js | ^22.19.0 or >=24.0.0 |
| React | ^18.2.0 |
| Document Picture-in-Picture | Current Chromium browsers; optional |
DSH is in developer preview and does not promise API compatibility between prereleases. Beacon therefore constrains every DSH peer to one prerelease line. Upgrade Beacon together with DSH.
The published 0.1.2-alpha.5 DSH packages are not compatible with Beacon: their Session reader requires out-of-tree events to carry the ignorable envelope marker, but their public Session.append() implementation cannot persist that marker, and their LLM purpose union does not include session-brief. Publishing Beacon against alpha.5 would leave Sessions unreadable after uninstall or restart. Do not publish this package to npm until DSH releases both APIs; then replace the provisional lower bound with that exact released version and validate a clean install.
Install
After a compatible DSH version and this npm package are published, add the bundle to the Web profile:
dsh plugin --profile web add @jingzechen/dsh-beacon
dsh --profile web --dump-config
dsh --profile web
The config dump contains a @jingzechen/dsh-beacon layer and one dsh-beacon Loader row. The package is a bundle, not a profile; dsh plugin adds its patch to the selected profile.
Update or remove it with:
dsh plugin --profile web update @jingzechen/dsh-beacon
dsh plugin --profile web remove @jingzechen/dsh-beacon
Removing the bundle removes its profile dependency and configuration layer. Browser-local review preferences under dsh.session-overview.view.v1 remain in that browser until its site data is cleared.
Configuration
The published cordis.patch.yml supplies conservative defaults:
| Field | Default | Meaning |
|---|
sessionActivity.maxOpenTools | 3 | Maximum unmatched tool names projected into a Session summary |
sessionActivity.maxErrorBytes | 64 | Maximum UTF-8 bytes retained from a provider-neutral error code |
sessionBrief.automaticTriggers | turn-end, goal-blocked, turn-error | Stable checkpoints eligible for automatic generation |
sessionBrief.minMeaningfulEvents | 2 | Required activity advance after the previous accepted brief |
sessionBrief.maxBriefBytes | 4096 | Maximum complete accepted brief size |
sessionBrief.maxItemsPerField | 8 | Maximum completed, blocker, and citation items |
sessionBriefLlm.maxInputBytes | 32768 | Maximum exact JSON-framed model input |
sessionBriefLlm.maxOutputTokens | 512 | Auxiliary output token cap |
sessionBriefLlm.timeoutMs | 30000 | End-to-end auxiliary request deadline |
A profile patch can replace the complete dsh-beacon row to change these values. DSH patch rows replace config rather than deep-merging it, so restate every required field.
To pin generated briefs to a dedicated route, add both provider and model under sessionBriefLlm. If both are omitted, Beacon uses the latest eligible route recorded for the Session. Brief generation remains unavailable when neither route exists; deterministic activity and context continue to work.
Product behavior
The global workbench lists unarchived top-level Sessions and excludes child or subagent-origin Sessions. It orders pending approvals, questions, and plan reviews before blockers, failures, running work, queued work, explicit Goal completion, changed Sessions, paused Goals, and idle Sessions.
The selected Session view derives Task, current focus, completed Todo items, next action, user attention, provenance, and freshness from bounded DSH projections. Generated text is shown separately and never controls attention ordering. An idle Agent, a normally completed Turn, and completed Todo items do not imply Goal completion.
The Web UI supports opening, cancelling, archiving, steering, pinning, snoozing, marking reviewed, answering pending interactions, and explicitly refreshing a brief through existing DSH APIs and permission checks.
Network, model, and cost
The browser plugin does not open an independent network connection for Session data. It uses the DSH Web Client transport and controller services already configured by the web profile.
The optional brief provider sends one bounded auxiliary request through the configured DSH LLM provider. That request can consume tokens and incur provider charges. The exact request route, source sequence, selected event sequences, duration, result, and reported token usage are logged as Session metadata. The generated brief does not enter the main Agent history and does not invalidate its KV cache.
Brief input may include bounded visible user and assistant text, Session title/header facts, Goal and Todo state, the latest Turn result, active tool names, and the previous accepted brief. It excludes reasoning content, credentials, arbitrary file contents, raw tool arguments, and raw tool results by default.
File and permission access
Beacon does not directly read arbitrary workspace files and does not add a filesystem tool. Activity and brief services read the Session log and existing projections in the Host process. Any file or tool access performed by an Agent remains governed by the installed DSH providers, sandbox, and approval policy.
Approval, question, and plan-review responses use the current DSH interaction objects. Beacon does not add bulk approval, automatic answering, or a second authorization channel.
Browser behavior
The draggable activity beacon is the global entry point. Its hover or focus preview shows at most three actionable and three running Session titles. The detached Picture-in-Picture view shows at most three combined activity rows.
Document Picture-in-Picture requires an explicit user click. Unsupported browsers hide the operation. The originating DSH tab must remain open and connected, and the detached window contains only the bounded activity view rather than the full workbench.
Pin, snooze, bookmark, filter, beacon position, and last-reviewed values are browser-local. They do not change the Session log and do not synchronize across browser profiles or devices.
Install from GitHub
A Git dependency receives source files, not npm's prebuilt package artifact. This repository includes a self-contained prepare script, but pnpm 10 and later requires users to authorize that install-time build in the profile's pnpm-workspace.yaml:
allowBuilds:
'@jingzechen/dsh-beacon': true
Then install a pinned commit and repeat the add command if pnpm requested authorization:
dsh plugin --profile web add github:JingzeChen/dsh-beacon#<commit-sha>
Treat allowBuilds as permission to execute package code during installation. npm distribution is preferred because it ships prebuilt lib/index.js, lib/client.js, declarations, and cordis.patch.yml without an install-time build.
Development
pnpm install
pnpm run build
pnpm pack
pnpm run build emits Host code, the DSH window.__ModuleLoader__ Client bundle with inline CSS Modules, and declarations under lib/. pnpm pack includes only the files listed in package.json.
License
MIT
