dsh-team-rooms

Extracted from dsh-background-agents 0.9.6. The background-agent half of that plugin (background_agent and the five bg_* tools) is superseded by DSH's native continuable subagents; the team-room half had no native equivalent and lives on here as its own package. Storage domains, session logs, and settings written by 0.9.6 keep working unchanged — see Compatibility.

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 (team-room/fact) there: facts route to the logger/panel channel instead and the teamRoom projection degrades to an empty fold. Older rc lines (through 0.1.1-rc.2) keep the ignorable-marker discipline. The client half rides the current client packages (dsh-api-session-controller, dsh-client-ui-slots, dsh-client-ui-settings, dsh-client-locale, dsh-client-web).

Data compatibility with dsh-background-agents 0.9.6 is a hard rule. These strings are byte-identical to 0.9.6 and must never be renamed: the storage domain team_rooms, the teamRoom projection key, the team-room/fact session event type, and the team-rooms settings-slot id. An existing profile therefore keeps its rooms, its member logs, and its settings page when you swap the plugin.

What you get

dsh-team-rooms turns several independent sessions into one coordinated team:

1. The /room command family — create, join, leave, list, send, tasks, task add|assign|claim|done|delete. Rooms are named, owned, and addressed by a stable room id you can paste into another session.
2. Eight room_* tools — room_list_rooms, room_post, room_read, room_list_tasks, room_create_task, room_claim_task, room_transfer_task, room_complete_task. The model works the shared board and the bus from inside its own session; room_transfer_task asks for approval before a cross-member handoff.
3. A durable room store — members, the message bus (directed or broadcast), the task board, and the timeline live in the team_rooms storage domain (SQLite or JSONL backend — the deployment chooses; the plugin adds no service of its own) and recover across DSH restarts.
4. A Web settings page — the Team Rooms settings section shows member status, the task board, and the timeline of every room the current session belongs to, read from the teamRoom session projection and written back through the host /room command.

Quick start

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

# or from npm (published releases)
dsh plugin --profile web add dsh-team-rooms

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

The bundle patch carries the plugin row; no Config key is required. The repo commits its build output (lib/), so git installs need no build step. Rooms mount wherever the storage domain is composed (@deepseek-ai/dsh-storage-domain, part of every @deepseek-ai/dsh-base profile); without it the /room command and the room_* tools stay dormant while everything else still loads.

Then, inside any session:

/room create release-prep
/room send <roomId> kickoff: I own the changelog, who takes the docs?
/room task add <roomId> draft the migration note
/room task claim <roomId> <taskId>

Paste the printed room id into another session and /room join <roomId> — that session is now a member, receives room deliveries as ordinary messages, and sees the same board.

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-team-rooms#main" — committed lib/, no prepare or allowBuilds step.
• npm channel (published releases): dsh plugin --profile web add dsh-team-rooms.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-team-rooms-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-team-rooms (or remove the row from the profile patch). Your rooms stay in the team_rooms storage domain and come back if you reinstall.
• ✅ Safe to mount together with dsh-background-agents (≥ 0.9.14). While the deprecation window was open both packages shipped the same room half — the same eight room_* tools, the same settings.section slot id (team-rooms) and the same team_rooms storage domain — and dsh-background-agents ≤ 0.9.13 additionally registered the same roomHub service key, which Cordis permits exactly once per isolate scope. Since dsh-background-agents 0.9.14 that package carries a first-provider-wins coexistence guard: it checks whether roomHub is already provided and, if so, stands its own room half down while its background-agent core keeps running. Either package may therefore be mounted first, and the room half is owned by exactly one of them. If you run dsh-background-agents ≤ 0.9.13, mount only one of the two — upgrade that package, or remove it (dsh plugin --profile web remove dsh-background-agents). Your rooms survive either way: they live in the team_rooms storage domain, not in the plugin.

Configuration

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

Tools & surfaces

That is eight room_* tools, all registered once the storage domain is composed.

How it works — and why it survives restarts

The room store is the cross-session authority; the session projection is each member's own reconstructed copy. Two writes run at once and stay consistent:

• Every room mutation (create, join, leave, post, task transitions) queues on ONE hub write chain — the team_rooms domain's single write chain is the ordering authority, so concurrent posters can never interleave a read-modify-write and bus seqs mint strictly in commit order.
• Model-visible ⟺ recorded: a delivered room message is an official inbox delivery (agent.followup wakes a live member; agent.inject hands an offline member its backlog on the next start), so it lands as a durable user/message in that member's own session log.
• The shared timeline mirrors into every member's log as log-only team-room/fact events carrying the canonical store timelineSeq; the teamRoom projection folds each member's own log, so the view reconstructs on every reopen without reading the store.
• Delivery is at-least-once and ordered: per-member cursors (lastDeliveredSeq, lastFactSeq) advance only after a delivery lands, so a crash between commit and delivery re-delivers on catch-up rather than losing the message.

Hosts whose Session.append predates the ignorable marker (every released rc line through 0.1.0-rc.8 and the 0.1.1-rc.2 line, and the 0.1.2-rc line, which keeps the envelope field for stored-log read compatibility only) 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 API surfaces, and the model-visible deliveries keep working, and teamRoom degrades to an empty fold. allowUnmarkedFacts: true opts back in — deliberately dangerous.

Not this plugin

Permissions & data

• Permissions: the workshop manifest declares session:append and tools:register. Rooms never spawn a subagent, so the plugin asks for no subagent:* permission and declares no subagent dependency.
• Data: rooms live in the team_rooms storage domain (SQLite or JSONL — zero extra services). No separate database, no network.
• Session log: 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 room deliveries are real user/message records.

Security boundaries

• Approval-gated handoffs. room_transfer_task routes through the official approval seam and fails closed when no approval service is composed or no answerer grants it — nothing changes on a refusal.
• 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. A room message can never reach a model without being recorded.
• Membership is the authorization boundary. Every room_* tool authorizes against the calling session's own membership; a non-member gets a stable rejection, not a partial write.
• Retention is bounded. Bus, timeline, and done-task windows are enforced on every write, so a long-lived room cannot grow without limit.
• No scheduling, no cross-machine members. A member is a process-local session of this 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).

Known limitations

• Rooms require the storage domain to be composed; without @deepseek-ai/dsh-storage-domain, the /room command and the room_* tools are disabled.
• A room needs at least two members to be interesting, and the roster is bounded by maxMembersPerRoom; membership is per session, not per user.
• There is no cross-machine membership: every member is a process-local session of this deployment.
• room_transfer_task needs an approval answerer. Without one it fails closed by design, so automated profiles that want handoffs must compose an approval service.
• Cost/usage accounting is out of scope here (that lived in the background-agent half); the room surfaces report structure, not spend.

Development

pnpm install        # tooling only; harness packages resolve against a sibling checkout
pnpm run typecheck  # strict TS, node + client programs
pnpm test           # vitest: unit, room-hub, projection, and jsdom panel tests
pnpm run build      # lib/index.js (node half) + lib/client.js (web client bundle)
pnpm run verify:artifacts && pnpm run check:readmes
pnpm run gen-aliases  # re-map harness package paths after the checkout moves

pnpm run pack:smoke builds, packs, and (with DSH_HARNESS_ROOT set) installs the tarball into a throwaway profile to assert the composed row.

Topics

dsh, dsh-plugin, deepseek-harness, team-rooms, multi-agent, message-bus, task-board, collaboration, cross-session

Contributors

• @PerryLink — creator and maintainer: the team-room hub and its write chain, the delivery cursors, the teamRoom projection, the Web settings page, docs, CI/CD and releases.

PerryLink DSH Plugin Family

This project is one of the 33 actively maintained DeepSeek Harness plugins from PerryLink — the roster is 42, of which 6 are frozen and 3 retired; every one keeps its row below, with the reason in the Status column. If this one helps you, the others likely will too:

前往 GitHub