PerryLink/dsh-background-agents

---

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（40+ 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 40+ plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

Compatibility

Host 0.1.2-alpha.2 and later fails closed on the session event vocabulary, so this plugin no longer writes its log-only fact events (background-agents/fact, team-room/fact) there: facts route to the logger/panel channel instead and the projections degrade to an empty fold. Older rc lines (through 0.1.1-rc.2) keep the ignorable-marker discipline. The client half now rides the current client packages (dsh-api-session-controller, dsh-client-web) and the current subagent remote (interruptByParent, prompt with a client-minted requestId; the old history RPC is gone — result peeks read the child session's conversation projection). 0.1.2-rc.1 (adapted 2026-09-04): the session envelope keeps its ignorable field for stored-log read compatibility only - Session.append still cannot stamp it (the third parameter is SurfaceIntent for surface event types only, never an options bag), so fact-gate behavior is unchanged. 0.1.3-alpha.1 (adapted 2026-09-06): the CI harness pin moves to the master checkout (d347e7039) - the handle seam (open → read → close) of the session-persistence service. The published 0.1.2-rc.1 runtime predates open(), so the cold bg_result read feature-detects the seam and falls back to load() - same behavior on both lines. Verified 2026-09-06 against the dsh-v0.1.7-alpha.1 master checkout (full gate chain + profile install smoke). 0.1.5-alpha.1 (adapted 2026-09-09): SessionHandleReadResult now returns { eventState, events }, so the cold bg_result read destructures .events from the handle seam (the published load() fallback is unchanged). The CI harness pin moves to the public tag commit 5dda764ed3aa (the local checkout is 13 infra commits ahead and unreachable from CI) and the compat probes install the alpha line. Peers widen to >=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 (prerelease-tuple rule: the first arm alone does not match 0.1.5-alpha.1) and devDeps pin 0.1.5-alpha.1. Verified 2026-09-09 against dsh-v0.1.7-alpha.1 (full gate chain). The earlier 0.1.3-alpha.1 claim is superseded: that prerelease falls outside both peer arms. 0.1.5-rc.1 (adapted 2026-09-10): dependency pins move to the published 0.1.5-rc.1 line; no seam change affects this plugin's behavior. 0.1.5-rc.2 (adapted 2026-09-11): dependency pins move to the published 0.1.5-rc.2 line; no seam change affects this plugin's behavior. 0.1.6-alpha.2 (adapted 2026-09-18): the client session service removed its subagent-navigation call, so the action now reports that navigation is owned by the session header (ui-subagent's lineage seat) instead of failing silently; the room panel derives its current session from main-view retention (retainedBy.mainView) because SessionListState.current is gone. The agent/created catch-up listener returns synchronously under its own 2 s bound, and an unreadable child log reports unavailable instead of empty text. Dashboard metrics fed by the session-log fact channel remain unavailable on this line (a non-surface fact event still cannot be stamped with the ignore marker) — the durable room tables and the panel's projection value are the record. Verified 2026-09-18 (both typecheck rulers + the full test suite); the browser-visible half is not machine-verified yet. 0.1.7-alpha.1 (adapted 2026-10-04): the host completed its move to producer-owned message attribution — the catch-all { kind: 'plugin', plugin } source is retired from both the type map and physical-row admission — so every notice this plugin injects now carries its own kind: 'dsh-background-agents', declared by module augmentation; the projection still reads 'plugin'-kinded notices out of older logs. Tool results are V4 first-class role: 'tool' messages (toolCallId/content/isError at the top level, no { type: 'tool-result' } wrapper block), and listChildren returned to identity-only SubagentCatalogEntry rows — no kind discriminator, no diagnostics, no activity — so every direct-listing call site classifies by mode === 'continuable'. Client-side, IconBranchOutline16 became IconBranchOutlineRegular and ISessions.refreshSubagents became refreshProjections(sessionId). Verified 2026-09-22 (both typecheck rulers + the full test suite + build + artifact checks); the browser-visible half is not machine-verified yet.

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 plus the per-turn metrics samples (tokens, turn wall time, error flag), 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.8 and 0.1.1-rc.2, and the 0.1.2-rc line (which keeps the envelope field for stored-log read compatibility only and still cannot stamp it), drop 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: 'dsh-background-agents', form: 'notice' } — 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.

Cross-ecosystem inbound (P2)

External agent runtimes — OpenAI Agents SDK, CrewAI, and similar — can publish into a team room through a minimal newline-delimited JSON-RPC 2.0 bridge over stdio. This is a JSON-RPC direct-connect minimal set, not the official ACP wire protocol: full ACP compatibility waits for the upstream seam.

Enable it with two Config fields and point inbound.command at a launcher that emits one JSON notification per line on stdout:

# cordis.yml (plugin row)
inbound:
  enabled: true
  command: "python external_runtime.py --room <room-id>"

The runtime emits three notification kinds; method is the event name and params.name is the external agent's display name:

{"jsonrpc":"2.0","method":"agent_started","params":{"name":"researcher","room":"<room-id>","traceId":"t-1"}}
{"jsonrpc":"2.0","method":"agent_message","params":{"name":"researcher","room":"<room-id>","traceId":"t-1","message":"found the failing test"}}
{"jsonrpc":"2.0","method":"agent_finished","params":{"name":"researcher","room":"<room-id>","traceId":"t-1","status":"ok","usage":{"inputTokens":100,"outputTokens":40}}}

Each maps onto the room's existing surfaces: agent_started opens a task-board card, agent_message posts to the message bus, and agent_finished completes the card and posts the outcome. Invalid messages fail closed — they are dropped and a JSON-RPC error is written back. External runtimes are not DSH sessions, so the room owner's member session stands in as the sender; a room with no owner member drops the event. Start and stop are owned by the plugin fiber through a disposer; an unspawnable inbound.command degrades to a logged warning (the bridge stays dormant, nothing else is affected).

Interoperability with other DSH plugins

Verified against DSH 0.2.0-rc.2 (the runtime this README ships for) and the high-star plugin set surveyed on 2026-10-05.

This plugin does not interfere with other plugins, including the widely installed high-star ones:

• No tool-name collision. Every tool is namespaced (background_agent, bg_*, room_*). The plugin registers no bare name that a shipped tool or another plugin owns, so it never shadows anything — the mechanism dsh-routing-suite (7000★) uses against the built-in