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.
