PerryLink/dsh-background-agents

Compatibility

What you get

dsh-background-agents upgrades DSH’s fire-and-forget background jobs into two coordinated surfaces:

1. Five steering tools — background_agent starts a durable, continuable child on the official subagent seam (optional tool_filter — removes tools, never grants new ones; persona; max_depth; childProvider/childModel route). bg_message delivers a later turn; bg_list reports status (or the descendant tree with parentId/depth); bg_result reads the latest result text (reasoning fallback flagged textSource: 'reasoning'); bg_stop requests interruption.
2. Progress and archive — autoReport injects one throttled progress line after each child turn; reportDelivery: wakeup starts a parent turn when idle. The idle sweep archives quiet children and bg_message wakes them back up (autoArchive: false parks quiet watchers instead).
3. Dashboard projection + Web panel — the backgroundAgents session projection folds the parent log into rows; a sidebar panel shows live status, jump, message, stop, and result peek. Everything reconstructs from the durable log — no separate database.
4. Team rooms (v0.5.0+) — the /room command family plus eight room_* tools build persistent multi-agent rooms: members (each an independent session), a message bus (directed/broadcast), a shared task board, and a shared timeline — stored in the team_rooms storage domain (SQLite or JSONL) and recovered across DSH restarts. Cross-member task handoffs route through the official approval seam.

Quick start

# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-background-agents#main"

# or from npm (published releases)
dsh plugin --profile web add dsh-background-agents

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A4 'id: background-agents'

The bundle patch carries the plugin row; provider is required. The repo commits its build output (lib/), so git installs need no build step. The plugin needs the subagent spine already mounted (any profile built on @deepseek-ai/dsh-base has it). Team rooms mount wherever the storage domain is composed (@deepseek-ai/dsh-storage-domain); the five bg_* tools work without it.

Then, in any session, just ask the model — or call the tools directly:

background_agent "watch the repo for test failures and keep me posted" (label: test-watch)
bg_list
bg_message <agentId> "also check the snapshot tests now"
bg_stop <agentId>

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-background-agents#main" — committed lib/, no prepare or allowBuilds step.
• npm channel (published releases): dsh plugin --profile web add dsh-background-agents.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-background-agents-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-background-agents (or remove the row from the profile patch).

Configuration

Every tunable is a validated Schemastery Config field — change it in cordis.yml, never in code. Only provider is required.

Tools & surfaces

How it works — and why it survives restarts

Everything rides the official subagent seam: startContinuable, followup, interrupt, listChildren — the plugin performs no lifecycle routing of its own, never touches another session’s Agent, and never kills a process tree (stop = request interruption, teardown belongs to the continuation manager).

The plugin writes every fact through one structured channel and one model-visible channel:

• background-agents/fact structured fact events — the registered / message / stop / progress / archived facts, appended to the parent log as log-only records with the envelope’s ignorable: true marker; readers that do not know the type skip the records instead of refusing the log. Hosts whose Session.append predates the marker (every released rc line through 0.1.0-rc.7 drops it silently — the stamping fix exists on harness master only — making unmarked sessions unresumable on stricter builds) are detected before the first append (peer-version pre-check, then a probe of the returned envelope) and fact appends are skipped with a one-time warning — the durable store, the notices, and the tools keep working, and the projections degrade to an empty fact fold.
• tool/result replay metadata — the same facts in logs written before the structured channel (folded only while a row has no structured provenance).
• injected user/message notices (model-visible), source { kind: 'plugin', plugin: 'dsh-background-agents' } — the throttled progress lines and archive notices (canonical [background-agent <id>] … prefix).
• the official subagent-settled notice — the child’s durable “settled” fact.
• Team rooms mirror the same discipline: every delivered room message is a durable user/message in the member’s own log, and the shared timeline mirrors as log-only team-room/fact events in the team_rooms storage domain.

The backgroundAgents projection folds the structured channel and keeps the legacy folds; the dashboard value and bg_list facts reconstruct on every reopen without parsing human-readable notice text. When the catalog itself is unavailable, bg_list returns an explicit unrecoverable marker — it never fabricates an empty list.

How this relates to the built-in subagent tools

The harness core ships its own subagent tools (subagent, send_message, interrupt_agent, and the child-side report tool). This plugin’s bg_* tools are their session-scoped companions; both can be mounted together:

What the core tools lack: bg_list, bg_result, idle archiving, and the per-parent folded panel projection.

Not in scope: scheduled triggering (the schedule seam exists), cross-machine/remote agents, and any change to the official subagent activation contract.

Not this plugin

Permissions & data

• Permissions: the workshop manifest declares session:append, subagent:spawn, and tools:register.
• Data: team rooms live in the team_rooms storage domain (SQLite or JSONL — zero extra services); background-agent facts ride the parent session log. No separate database, no network.
• Session log: background-agents/fact and team-room/fact events are appended with the envelope’s ignorable: true marker on hosts that honor it (pre-marker hosts are detected and fact appends are skipped — see allowUnmarkedFacts); the model-visible progress lines and room deliveries are real user/message records.

Security boundaries

• Official seam only. Start, message, and stop are thin adapters over startContinuable / followup / interrupt; stop requests interruption and never kills processes.
• tool_filter only restricts. It removes tools from the child’s view — never grants new ones; names are validated against allowedChildTools.
• Approval-gated handoffs. room_transfer_task routes through the official approval seam and fails closed when no answerer grants it.
• Model-visible ⟺ logged. Every delivered room message is a durable user/message in the member’s own log; the shared timeline mirrors as log-only team-room/fact events.
• No scheduling, no cross-machine agents. Children are process-local continuable sessions of the deployment.

Known limitations

• Team rooms require the storage domain to be composed; without @deepseek-ai/dsh-storage-domain, the /room command and room_* tools are disabled (the five bg_* tools still load).
• provider must name a continuable-capable provider (prepareContinuable); a missing provider makes background_agent fail until it appears.
• maxBackgroundAgents is a shared budget across every continuable direct child of the session, including ones the built-in subagent tool started.
• One-shot children are never listed or messaged — bg_list keeps continuable rows only.
• Children are process-local: the schedule seam owns “when”, this plugin owns steering a live conversation.

Development

pnpm install        # tooling only; harness packages resolve against a sibling checkout
pnpm run typecheck  # strict TS, node + client programs
pnpm test           # vitest: unit + end-to-end tests (real subagent seam, scripted LLM, jsdom panel)
pnpm run build      # lib/index.js (node half) + lib/client.js (web client bundle)
pnpm run gen-aliases  # re-map harness package paths after the checkout moves

A keyless end-to-end demo drives a real parent session and a background child through a deterministic scripted LLM (no API key; dev/ is gitignored — adapt the paths to your checkout):

$env:DSH_HOME = 'D:/deepseek-harness/Project/Plugins/dsh-background-agents/dev/dsh-home'
pnpm dsh --profile headless --patch dev/cordis.yml "【父会话】驱动后台 agent 演示"

Topics

dsh, dsh-plugin, deepseek-harness, subagent, background-agent, background-agents, agent-dashboard, conversation-steering, team-rooms, multi-agent, message-bus, task-board, collaboration

Contributors

• @PerryLink — creator and maintainer: the background-agent runtime on the official subagent seam, the team-room hub, the Web UI sidebar panel, the session projections, docs, CI/CD and releases.

PerryLink DSH Plugin Family

This project is one of the DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

License

Apache License 2.0 © 2026 dsh-background-agents contributors