dsh-intercom

English | 中文 | 安装提示词

An intercom plugin for DeepSeek Harness (dsh): discovery, 1:1 messaging, and request/reply between independent dsh sessions running on the same machine.

Ported from pi-intercom (MIT, Copyright Nico Bailon) — see NOTICE.

Install with one prompt

No checkout, no build toolchain: paste one prompt into a running DSH session and the agent installs the plugin from GitHub, verifies the profile, and walks you through a two-session messaging check. See INSTALL.md (中文) — or keep reading for the manual quickstart.

Features

• Cross-session messaging — send (fire-and-forget, with mailbox queueing for temporarily disconnected named peers) and ask/reply (blocking request-reply) between sessions in one dsh process or across independent dsh processes.
• Discovery — list / list-cwd show every live session on the machine with name, working directory, model, and live status (idle, thinking, tool:<name>).
• Session aliases — the name action gives a session a stable address; peers resolve aliases, full session ids, or unique id prefixes.
• Inbound relay — messages arrive as a relay from the named sender: idle sessions start a new turn with it, busy sessions receive it as steering at the next step boundary.
• Coordination skill — installing the plugin also registers a dsh-intercom skill (planner-worker playbooks, send-vs-ask guidance) with dsh's skill registry; no manual install step.
• Web UI panel — in the web profile, an "Intercom" page in the Settings panel lists the live roster and can send a message as any session hosted by that dsh process.

How it works

Every dsh process hosting the plugin registers each of its agents with a local broker process (auto-spawned as node lib/broker/broker.js from the installed plugin, one socket — unix socket or Windows named pipe — per $DSH_HOME/intercom). Sessions discover and message each other through the broker; if the broker cannot start, same-process sessions still work through a direct in-memory fallback (status reports which mode you are in).

Quickstart

Install into the web profile and restart dsh:

dsh plugin --profile web add github:Sqhao-O/dsh-intercom

lib/ build artifacts are committed, so the GitHub install runs no build step. Then open two sessions and name them (the intercom tool is available to every session):

intercom({ action: "name", alias: "planner" })    → in session 1
intercom({ action: "name", alias: "worker" })     → in session 2
intercom({ action: "list" })                      → see each other, from either
intercom({ action: "send", to: "worker", message: "hello from planner" })
intercom({ action: "ask", to: "planner", message: "what is the status?" })
intercom({ action: "reply", message: "all good" }) → planner answers the ask

Or hand dsh the whole acceptance scenario as one prompt:

安装 github:Sqhao-O/dsh-intercom 插件，重启后开两个 session（分别命名 planner 和 worker），从 planner 给 worker 发一条消息并确认送达。

Usage

Give each session a name, then talk to it from any other session:

intercom({ action: "name", alias: "worker" })                  → name this session
intercom({ action: "list" })                                   → list live sessions (all processes)
intercom({ action: "list-cwd" })                               → list sessions in this working directory
intercom({ action: "list-cwd", cwd: "/path" })                 → list sessions in a specific directory
intercom({ action: "send", to: "worker", message: "..." })     → send a message (queued if the named peer is offline)
intercom({ action: "ask", to: "worker", message: "..." })      → send and block until the reply arrives
intercom({ action: "reply", message: "..." })                  → reply to the current / single pending ask
intercom({ action: "reply", to: "planner", message: "..." })   → disambiguate between multiple pending asks
intercom({ action: "pending" })                                → list unresolved inbound asks
intercom({ action: "cancel", messageId: "..." })               → request cancellation of a message you sent
intercom({ action: "status" })                                 → plugin/transport status

Address sessions by alias, full session id, or the unique id prefix shown in parentheses by list. send/ask also accept replyTo, messageId, supersedes, retryOf, and a cwd scope (omit to to target the sole live peer in a directory). ask never queues: a disconnected target fails immediately, while send to a recently disconnected named session queues in the broker mailbox and is delivered when a session with the same alias and working directory reconnects. DSH_INTERCOM_ASK_TIMEOUT_MS overrides the 10-minute default ask timeout.

Web UI panel

In the web profile, open the Settings panel → Intercom. The page lists the live roster (auto-refreshing) with name, status, and directory, plus a send box. The send box never invents an identity: you pick a sender among the sessions hosted by that dsh process, and the message rides that session's own broker connection — the receiver sees the real session as the sender.

The panel is served by two plugin routes on the dsh web server (GET /intercom/roster, POST /intercom/send). Like the broker socket, they trust the local machine: any local process can read the roster and send as a host-local session while dsh web runs.

Configuration

Optional $DSH_HOME/intercom/config.json — full reference (every key is optional; unknown keys are ignored):

Key	Type	Default	Meaning
enabled	boolean	true	When false the plugin loads but never spawns or connects to the broker; every tool action except status answers with a clear disabled message.
inboundTrigger	"always" | "replies" | "never"	"always"	Whether an inbound broker message may wake the session into a new model turn: "always" wakes on every message, "replies" only wakes on replies to messages this session sent, "never" only queues messages as context (no turn is triggered).
replyHint	boolean	true	Append the intercom({ action: "reply" ... }) hint to inbound messages that expect a reply.
status	string	—	Custom suffix appended to the automatic idle/thinking presence status shown to peers (e.g. "idle · on-call").
confirmSend	boolean	false	Accepted for pi-intercom config compatibility but a no-op: dsh's host-level tool-approval flow is the equivalent confirmation gate, so the plugin never opens its own dialog.

Example:

{
  "enabled": true,
  "inboundTrigger": "always",
  "replyHint": true,
  "status": "custom suffix"
}

A malformed config file fails closed: the plugin keeps working with defaults except inboundTrigger: "never", and logs a warning. The config is loaded once at plugin load — changing config.json afterwards takes effect only after restarting dsh.

Installation

dsh plugin --profile web add github:Sqhao-O/dsh-intercom

The GitHub install composes exactly like the tarball install below (verified end to end by pnpm test:dod against a scratch DSH_HOME). The coordination skill registers itself — there is no separate skill install step.

Install from tarball

The local equivalent of the GitHub install, verified end to end against a scratch DSH_HOME (never the real ~/.dsh):

pnpm build
pnpm pack --pack-destination "$(mktemp -d)"   # produces dsh-intercom-<version>.tgz
export DSH_HOME="$(mktemp -d)"                # scratch home (Git Bash syntax)
dsh plugin --profile web add /path/to/dsh-intercom-<version>.tgz
dsh --profile web --dump-config | grep dsh-intercom   # verify the composed row

The tarball contains only lib/, client.js, skills/, cordis.patch.yml, package.json, README*, LICENSE, and NOTICE — no sources or tests. For a local checkout, see "Local development" below.

Development

Requires Node.js ≥ 20 and pnpm.

pnpm install
pnpm build       # compile sources to lib/ (artifacts are committed)
pnpm test        # node:test via tsx
pnpm lint        # oxlint
pnpm typecheck   # tsc --noEmit
pnpm format      # prettier

See CONTRIBUTING.md for the workflow.

Local development (mount into a real dsh)

Mount the checkout into a dsh profile without touching your real ~/.dsh:

pnpm install && pnpm build   # dsh loads the compiled lib/, no build at install time

# Point DSH_HOME at a scratch directory first (Git Bash syntax):
export DSH_HOME="$PWD/tests/e2e/.tmp/dsh-home-link"

dsh plugin --profile web add link:"$PWD"   # symlinks the repo into the profile
dsh --profile web --dump-config | grep dsh-intercom   # verify the composed row
dsh web                                    # boot with the plugin mounted

link: creates a symlink in the profile's node_modules, so pnpm build after a source edit is enough — reinstalling is never needed. The same commands work with --profile headless (or any other profile).

End-to-end tests

All e2e scripts run against scratch DSH_HOME directories with mock LLMs — no real API key, and the real ~/.dsh is never touched. They are kept out of pnpm test; see tests/e2e/README.md.

• pnpm test:e2e boots three real dsh processes (two concurrently, plus a worker relaunch) and covers the cross-process path: roster discovery via list, a send relay waking the peer process, an ask blocking until the peer's reply unblocks it, and — after the worker process is killed — an immediately failing ask, a mailbox-queued send, and delivery of that queued message to the relaunched worker (same alias + cwd).
• pnpm test:install runs the tarball install preview: pack, inspect the tarball contents, install into a scratch DSH_HOME with the real dsh CLI, and boot headless to prove the module loads (and the skill registers).
• pnpm test:panel boots a real dsh web server with the plugin link-installed: the browser half is served and wired into the boot graph, the roster route lists two probe sessions through the broker, and the send route delivers a real message into the peer's session log.
• pnpm test:dod is the final acceptance: it runs dsh plugin --profile web add github:Sqhao-O/dsh-intercom against the pushed GitHub repo in a fresh scratch home, then boots two dsh processes and proves planner→worker delivery and a worker→planner ask/reply.

Local acceptance

pnpm test:accept (tests/accept/, also kept out of pnpm test) is the one suite that deliberately targets the CURRENT DSH_HOME — by default the real ~/.dsh — for an in-place check after installing into the real web profile. It boots a real dsh web against the repo's mock LLM (child-env DEEPSEEK_BASE_URL / DEEPSEEK_API_KEY=test; settings.yaml is never touched and no real model call is made), temporarily appends a single probe row to the web profile's cordis.patch.yml (backed up first, restored byte-identical with a sha256 check on every exit path), and asserts the real-environment wiring: tool + skill registration, broker auto-spawn under ~/.dsh/intercom, the panel roster/send routes (relay + wake in the worker's session log, and a 400 for a non-local sender), an ask/reply between the probe sessions, and the served client.js. Probe sessions (accept-planner-* / accept-worker-*) persist under ~/.dsh/sessions/ and are listed at the end; the acceptance-spawned dsh web is stopped (the broker self-exits when idle).

pnpm test:accept

Known limitations

• Same machine only. Discovery and delivery go through a local socket (unix socket or Windows named pipe) keyed by $DSH_HOME/intercom — there is no cross-host transport.
• Text messages only. Attachments (files/snippets/context) exist in the vendored protocol types but the tool does not accept or render them yet.
• confirmSend is a no-op (see the config table).
• The Web UI panel is web-profile only and English-only (no locale namespace yet). There is no TUI overlay.
• The panel's React rendering is verified by contract, not by a browser test: the e2e asserts the bundle is served, wired into the boot graph, and that its data routes work end to end, but does not automate a real browser.

License

MIT — see LICENSE and NOTICE.