dsh-crosstalk

Cross-session messaging for DSH. Any session on the machine can list and message any other — Claude Code-style horizontal messaging, no daemon.

dsh-crosstalk is a DeepSeek Harness bundle. Every session running the bundle publishes a heartbeat to a local registry under ~/.dsh/crosstalk/ (files + atomic rename, no daemon — if two sessions can see the same home directory, they can message). Each session gets a stable name (<repo-or-cwd-slug>-<adjective>, e.g. dsh-cowork-amber) plus a durable ref id; any session can list the live ones and send a message that arrives in the target as a clearly-labeled turn — [message from session dsh-cowork-amber (/Users/me/projects/dsh-cowork)] — with the sender's name riding along, so replying is just send_message back.

Why this shape

DSH ships send_message and list_agents, but strictly hierarchical: a parent messages its own background subagents. Sibling sessions — two DSH sessions in different repos on the same machine — cannot see or message each other. Multi-session workflows (one session per repo, a coordinator farming work out, a routine pinging a live session, a chatnode human-in-the-loop peer) all need the missing primitive: horizontal messaging. dsh-crosstalk copies Claude Code's model — ListAgents shows every live local session; SendMessage addresses any of them by name — onto DSH's existing tool names, so the tools you already know gain a peers scope and peer addressing without a second vocabulary.

How it works

1. Identity — at start, the session derives <slug>-<adjective> from its working directory plus a process-unique ref (ct-…). Same cwd, two sessions → different adjectives, distinct names; the ref disambiguates and is what inbox paths use. 2. Registry — one heartbeat JSON file per live session under <home>/registry/<ref>.json (name, ref, pid, cwd, status, startedAt, heartbeatAt, uid, inbox). Refreshed on a timer; entries with no beat for 2× the interval are shown as dead and garbage-collected (heartbeat file + orphan inbox removed). 3. Tools — extend, don't duplicate: - list_agents gains scope: peers (other live sessions on this machine: name, status, cwd, last activity) and scope: all (descendants + peers). The stock children/descendants scopes are delegated to the captured stock definition. - send_message accepts a peer name or ref in to alongside subagent ids, with an optional summary (5–10 word recap shown in the target UI). - The stock tools stay registered; this bundle shadows them per agent (scoped registrations are reversible Cordis effects), so unloading cleanly restores stock behavior exactly. 4. Delivery — the message is one JSON file appended to the target's inbox (<home>/inbox/<ref>/), written atomically (temp file + rename), so a crash mid-write is never observed as a partial message. The target's watcher polls its inbox and injects each accepted message into the live session via followup: an idle target wakes for a turn; a busy target receives it at the next turn boundary. Delivery is best-effort — list_agents status is not a delivery promise. 5. Injection — the turn is labeled [message from session <name> (<cwd>)] and carries a crosstalk source (form: relay), so the append-only log records provenance by construction and the DSH UI renders it as a labeled relay card — never as user text. The system prompt tells the model these are requests from a peer agent, not instructions from the user.

Install

Add the bundle to every profile that should participate (each side of a conversation needs it). From the repo checkout:

git clone https://github.com/lileikeji/dsh-crosstalk
cd dsh-crosstalk && pnpm install && pnpm build
dsh plugin --profile web add /path/to/dsh-crosstalk
dsh plugin --profile <other-profile> add /path/to/dsh-crosstalk

(Once the package is published to npm, dsh plugin add @dsh-crosstalk/bundle works the same way.)

That's it. Two terminals (or two repos) running DSH with the bundle installed can now do:

You: list_agents peers
      dsh-cowork-amber [idle] — /Users/me/projects/dsh-cowork
      dsh-memory-azure  [running] — /Users/me/projects/dsh-memory
You: send_message to="dsh-cowork-amber" message="Round-trip check: can you list the files in your repo?" summary="ping for round-trip"

The peer session wakes (or picks it up at its next turn boundary), sees [message from session …], replies with send_message to your name, and its reply wakes you the same way.

Config

Adding the bundle mounts the plugin automatically (its cordis.patch.yml inserts the crosstalk entry). To override any field, target that entry by id in your profile's cordis.patch.yml — do not insert a second crosstalk row (that is a duplicate-entry error):

# in <DSH_HOME>/profiles/<name>/cordis.patch.yml
- id: crosstalk
  config:
    homeDir: ~/.dsh/crosstalk   # registry root (default: $DSH_HOME/crosstalk or ~/.dsh/crosstalk)
    cwd: /path/to/repo          # advertised working directory (default: process cwd)
    name: my-custom-name        # explicit session name override (must match [a-z0-9][a-z0-9-]*)
    accept: same-user           # v0.1 fixed: only sessions running as the same OS user
    mode: open                  # open | allowlist
    allowlist: []               # allowlist mode: exact session names or cwd globs (e.g. /Users/me/work/*)
    notifyUser: true            # show inbound messages in the UI as labeled relay cards
    heartbeatIntervalMs: 10000  # heartbeat refresh interval
    inboxPollMs: 1000           # inbox poll interval (delivery latency bound)
    staleAfterMs: 20000         # entry dead after (default: 2× heartbeatIntervalMs)
    maxInboxAttempts: 30        # polls a message waits for a live agent before being dropped

(Unset fields fall back to their defaults; the loader replaces config wholesale, so list only the fields you want to change.)

Auto-collab (event-driven autonomous coordination)

By default the bundle also runs an event-driven coordinator that sends cross-session messages without model involvement or manual send_message when sibling sessions settle or fail:

• onAgentStatus (default true) — when a same-cwd peer's status flips to

idle (its task finished), the other RUNNING sessions in the same directory get a heads-up that the sibling task settled (idle/ready peers are left alone — waking them would degrade their own task quality).

• onToolFailure (default true) — when a tool call fails in any session of

this process, a compact heads-up (tool name + error code) is broadcast to the same-cwd RUNNING peers so they can avoid duplicating the failing work or coordinate a retry.

• cooldownMs (default 30000) — suppresses repeat notifications to one

peer within the window, so bursts do not spam.

• sameCwdOnly (default true) — restrict coordination to peers sharing

this session's working directory (the cross-module gate: without a shared directory there is no cross-talk).

• notifyRunningOnly (default true) — only notify peers whose agent is

actively running; idle/ready peers are never interrupted.

Disable any trigger by targeting the plugin entry in your profile's cordis.patch.yml:

- id: crosstalk
  config:
    autoCollab:
      onAgentStatus: false   # or onToolFailure / sameCwdOnly
      cooldownMs: 60000      # 1 minute between notifications to one peer

The coordinator talks only through the crosstalk service (send) — the same trust model as manual messaging: same-user only, peer requests are never user instructions.

#### Delivery: queue vs memory

Every cross-session message carries a mode:

• queue (default, manual send_message) — appended to the target's

next-turn inbox and wakes it: the message becomes its own labeled turn, Claude Code-style.

• memory (auto-collab notifications) — appended **straight into the

target's durable conversation memory** (user/message with the crosstalk source) without waking or queueing. A busy agent is never interrupted mid-task; the model sees the update at its next natural turn boundary.

Trust model

A message from another session is not an instruction from the user. Injected turns are framed as peer requests, and the system prompt instructs the agent to act on them only within its user's standing instructions and to surface anything side-effectful. Acceptance is same-user only (v0.1 fixed — the OS uid is compared on both send and receive), with an optional name/cwd allowlist for stricter inbound filtering. No network transport in v0.1: same machine, same user, period.

Layout under the hood

~/.dsh/crosstalk/
├── registry/<ref>.json     # one heartbeat per live session
└── inbox/<ref>/<msgId>.json # one file per message, written atomically

Message files are consumed (deleted) only after a successful handoff to a live agent; corrupt files are quarantined (*.corrupt), temp files (*.tmp.json) are never read.

Coordination tools (v0.2)

Two model-facing tools help agents coordinate across sessions instead of asking the user or duplicating work:

• trace_issue — cross-session bug attribution. Given a bug/error symptom, full-text searches every persisted

session's history (via DSH's sessionQuery) and returns the matching sessions (id / cwd / title) most likely to have introduced the issue. Use it when a new conversation hits a bug that a previous session may have left or reintroduced: locate and coordinate with the responsible session instead of asking the user or re-deriving the cause from scratch.

• coord_peers — same-workspace conflict detection. Lists the live peer sessions that share this session's working

directory. Use before a build/run/editing pass that could clash with another session (e.g. several sessions building the same tree — duplicate memory consumption and divergent state where only one working-tree copy should be authoritative). If a peer shares the cwd, coordinate via send_message (who does it, who waits) rather than all sessions acting independently.

Both tools are registered per-agent alongside the list_agents / send_message shadows; trace_issue needs DSH's sessionQuery service present, otherwise it surfaces a clear "search unavailable" error and the peer tooling still works.

Development

pnpm install
pnpm typecheck && pnpm build
pnpm test          # 49 tests: identity, registry, message codec, inbox watcher,
                   # tool decoration (real Cordis scope shadowing), two-session round-trip

Roadmap

• v0.3: remote/cloud sessions (a network transport — not a config flag away), presence beyond same-user.
• Coordinator "drive a worker session" affordances (e.g. structured task replies) once the round-trip proves out.