@jingzechen/dsh-beacon

Readme

# DSH Beacon

English | [中文](README.zh.md)

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:

```sh
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:

```sh
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`](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` | `4096` | 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`:

```yaml
allowBuilds:
  '@jingzechen/dsh-beacon': true
```

Then install a pinned commit and repeat the add command if pnpm requested authorization:

```sh
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

```sh
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](LICENSE)