dsh-plugin-focus — Focus Board for DeepSeek Harness agents
A real, installable DSH plugin (DeepSeek Harness / Cordis profile bundle) that gives the agent a focus tool and a durable focus board — a small note file (default .dsh/focus.md) in the session workspace that pins the objective, hard constraints, and decisions across context compaction and across sessions on the same workspace. The todo list tracks what to do next; the focus board tracks why we are doing it and what must not drift.
Compatibility
Tool schemas are validated against the @deepseek-ai/dsh-tools value-schema DSL (compiled at plugin load). 1.1.1 fixes a schema violation that made the host abort the whole profile boot on DSH ≥ 0.1.0-rc.6 with unsupported JSON schema: schema.required is not supported by the value schema DSL. If you installed an affected version and your DSH no longer starts, upgrade to 1.1.1 (or remove the plugin from the profile) — no data is lost.
Features
| Feature | Status |
|---|
focus tool — set / get / append / summary / clear | ✅ stable |
Structured entries — tag notes with kind (objective / constraint / decision / note) and status (open / done), grouped by summary | ✅ stable (v1.1) |
Prompt guidance section (focus:instructions) | ✅ stable |
| Automatic injection — board is re-injected into model context at every turn start and whenever it changes | ✅ stable |
Archive on clear — clear moves the old board to .dsh/focus.md.bak (accumulates) | ✅ stable |
focusBoard session projection for UIs | ✅ stable |
| Read-only web panel (composer dock) | 🧪 experimental (loader-format client bundle, not verified against a running web instance) |
How it works
- The board is a plain, append-friendly text file. Entries are timestamped and ordered;
get renders newest-first with a configurable character cap (the file is never trimmed by rendering).
- The plugin is a single Cordis plugin: the host face (
lib/index.js) registers the tool, the projection, and the auto-injection; the browser face (lib/client.js) renders the panel. The same composition row covers both faces via the package's dsh.bundle + dsh.client manifest sections.
- All file access goes through the host
ctx.fs service, and every resolved path is containment-checked against the agent's session workspace — the board can never escape it.
- Auto-injection mirrors the in-box
dsh-time-context mechanism: an agent/pre-step waterfall listener appends a plugin snapshot message carrying the board text (step 1 of every turn, plus mid-turn whenever the text changes). Resumed sessions get the board back on their first step.
Install
The package declares "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }, so it goes through DSH's official plugin management:
# from a local checkout (equivalent to pnpm add <path> + auto-reconcile of the bundles list)
dsh plugin --profile <profile> add /path/to/dsh-plugin-focus
# or after publishing to npm
dsh plugin --profile <profile> add dsh-plugin-focus
Restart DSH. The focus tool is registered host-wide; the read-only panel appears in the web UI on a web profile.
Alternative: mount on one agent preset only
- Copy a built-in preset to
$DSH_HOME/.agent-presets/<id>/ (never edit the deployment's own preset — an upgrade overwrites it).
- Append to
agent.cordis.yml:
- id: focus
name: 'dsh-plugin-focus'
config:
file: '.dsh/focus.md'
- Make sure
dsh-plugin-focus resolves (installed in the profile's node_modules or the module fallback directory).
Usage (model side)
| action | args | behavior |
|---|
set | note (required) | append an entry pinning the current focus / constraints |
append | note (required) | append a log entry (decision, discovery, reversal) |
get | — | read the whole board (newest first, capped, omitted-count footer) |
clear | — | empty the board; the old board is archived to the archive file |
The plugin also injects a focus:instructions prompt section (disable with personaSection: false) and re-injects the board into context automatically (disable with autoInject: false).
Configuration
All optional, on the composition row's config:
| key | default | meaning |
|---|
file | .dsh/focus.md | board path, relative to the session workspace; cannot escape it (runtime-enforced) |
archiveFile | .dsh/focus.md.bak | archive path for clear |
archive | true | whether clear archives first |
maxEntries | 60 | max entries kept on disk (oldest dropped) |
maxChars | 8000 | render cap for get / auto-injection (view truncation only) |
autoInject | true | inject the board into model context at turn start / on change |
personaSection | true | register the prompt-guidance section |
sectionOrder | 5 | prompt section order (persona is 0, ascending) |
File format
# Focus Board
<!-- dsh-plugin-focus v1 -->
## [2026-08-14T23:12:00.000Z] set
<note, may span lines>
## [2026-08-14T23:13:00.000Z] append
<another note>
Clearing appends an archive block (stamped with the clear time) to the archive file, so history accumulates.
Design
- Pure logic separated from the runtime:
lib/board.js has zero DSH/Cordis imports (parse / render / mutate / archive) and is unit-tested in isolation; lib/index.js is the Cordis plugin.
- Safety: every path resolves through
ctx.fs and is containment-checked with ctx.fs.contains against the session workspace.
- Lifecycle: tool registration, projection, injection listener, and prompt section are all Cordis-scope-managed; stopping/removing the plugin cleans them up.
- Two faces, one row: the host loader imports
., the browser loader imports ./client (via the dsh.client manifest). The focusBoard session projection (event focus/write) is the data seam any future UI can read with useProjection('focusBoard').
Tests
node --test test/
Uninstall
dsh plugin --profile <profile> remove dsh-plugin-focus
Roadmap
- Verify the web panel against a live web instance and iterate on the slot UI.
- Expose board mutations from the panel (edit / clear buttons).
- Optional: attach the board to
turn/start events for explicit snapshot semantics.
License
MIT
FAQ
- The board is empty in a fresh session — where did it go? The board is per-workspace, not per-session:
focus set in a session whose workspace already has a .dsh/focus.md reads the existing entries. Each agent session resolves the board from its own session.header.cwd.
- Does the injection cost tokens? The board is injected once per turn start (plus mid-turn only when the text changes), capped at
maxChars. An empty board injects nothing.
- Can the board escape my workspace? No. Every path is resolved through
ctx.fs and containment-checked against the session workspace; a configured path outside it fails loud.
- The web panel is marked experimental — why? The client bundle is hand-written in the loader format without a bundler and has not been verified against a running web instance yet.
- How do I publish this to npm?
npm publish (a prepublishOnly test run is wired in). Then dsh plugin add dsh-plugin-focus installs it without a build step.
