Preface¶

In DeepSeek Harness (DSH), a common need when running agents is cross-session, cross-machine collaboration: an agent on one machine needs to send a message to a session on another machine, or detect if the remote end is online and list targetable destinations. Relying solely on local APIs or manually crafting HTTP requests involves maintaining address mappings and handling connection keep-alive and failure retries, which is not trivial.

dsh-interconnect is a workflow plugin maintained by community contributor Chinesezjc, currently with 34 stars on GitHub. It encapsulates cross-instance message delivery, liveness probing, event streaming, and model-side tools into a set of host services, allowing multiple DSH instances to communicate over persistent WebSocket connections.

What It Is¶

dsh-interconnect (npm package name: dsh-interconnect, current version 0.10.0, MIT license) is a cross-instance messaging and event notification plugin for DeepSeek Harness. In one sentence: it enables a DSH instance to send messages, probe liveness, and bidirectionally push events to itself, another machine, or other DSH instances on that machine.

The plugin provides three components as a bundle:

Core Features¶

Here we explain separately by transport layer, tool layer, and companion skill.

Persistent WebSocket Links¶

From version 0.9 onward, transport exclusively uses persistent WebSocket connections, with no HTTP endpoints. send, reply, ping, and list are all performed via msg / query frames over /interconnect/link. Upon activation, the plugin automatically establishes a connection to each peer based on the peers mapping, with heartbeat and exponential backoff reconnection.

The addressing parameter is now instanceId, not baseUrl. instanceId is the key in the peers mapping in the configuration; the actual origin used for dialing is provided by the mapping value (e.g., a tunnel endpoint http://127.0.0.1:13080). For peers that are not configured or not reachable, send / ping / list returns unreachable, with no HTTP fallback.

Authentication uses a shared secret DSH_INTERCONNECT_TOKEN (bearer, fail-closed, timing-safe comparison), configured in credential sources rather than the plugin config.

Model-Visible Tools¶

tool-interconnect exposes four tools:

1. interconnect_send: Delivers a message to a specified session on a remote instance; optional delivery selects the delivery mode, and resume wakes up an offline session. The local instanceId and sessionId are automatically injected when sending.
2. interconnect_list: Lists currently live sessions (id, title, status) on the remote instance, useful for addressing when the session id is unknown.
3. interconnect_ping: Probes the liveness and identity of the remote instance.
4. interconnect_reply: Sends a reply to a previously recorded sender, requiring only the local session id and text, without re-addressing.

interconnect_list only returns sessions that currently have a running agent—these are the ones send can reach. Sessions owned by subagents do not appear in the list and cannot be directly targeted.

Bidirectional Replies¶

Upon receiving a send with a sender (instanceId + sessionId), the receiver records a mapping of “local session id → sender”. Subsequently, that session can use interconnect_reply to send a reply, with the target parsed from the recorded sender, routed over the persistent link from local to remote. sender is used for reply attribution, not for routing or authentication, and does not enter the model context.

Delivery Modes and Resumption¶

delivery has three possible values; the sender can override the receiver’s default per message:

resume is off by default. Setting it to true can wake up a session that has been persisted but has no running agent, but it triggers a full agent round (including model calls); the sender must explicitly request this, and the receiver can refuse using allowResume: false.

On delivery failure, SendResult.reason indicates the cause, such as session-not-live, unreachable, resume-refused, session-owned-by-subagent, no-sender-known, etc., helping the caller decide whether to retry or switch targets.

Companion Skill¶

skill-interconnect registers the dsh-interconnect skill for the model, explaining the complete usage of list / ping / send / reply, delivery modes, resume semantics, and failure handling. It depends on the interconnect service and is only registered into ctx.skills when the transport layer is present.

Installation and Enablement¶

This package is published to npm. The repository is a DSH profile bundle; the root package.json declares dsh.bundle.patch pointing to cordis.patch.yml, which inserts the three plugin lines.

Install from npm:

dsh plugin --profile <name> add dsh-interconnect

Or install from a local path (for development/debugging):

dsh plugin --profile <name> add file:/path/to/dsh-interconnect

dsh plugin add recognizes the repository as a bundle and appends it to the profile’s dsh.profile.bundles. Restart the web service to activate the host side. The .credentials.yaml (or equivalent credential source) on both instances must set the same DSH_INTERCONNECT_TOKEN as the shared secret.

Configuration example (the config field in the interconnect line, all fields optional):

- id: interconnect
  config:
    instanceId: my-box
    peers:
      peer-a: http://127.0.0.1:13080
      peer-b: http://127.0.0.1:13081
    delivery: followup
    allowResume: false

Typical Usage¶

Addressing and Delivery¶

First, use interconnect_list to view live sessions on the remote end, then send a message to a specific session:

interconnect_list(instanceId="peer")
interconnect_send(instanceId="peer", sessionId="session-264d37b0-…", text="…")
interconnect_ping(instanceId="peer")

Example return from interconnect_list:

session-264d37b0-…  Refactor interconnect plugin  [idle]
session-b07326da-…                          [running]

Bidirectional Reply¶

Instance A sends a message to a session on instance B, and B replies using its local session id without providing the remote address again:

# A sends to B
interconnect_send(instanceId="b", sessionId=B-sess, text="…")

# B replies
interconnect_reply(sessionId=B-sess, text="reply")

Waking Up Offline Sessions¶

Wake up and have the other side actually process (triggers a billing round):

interconnect_send(instanceId="peer", sessionId, text, resume=true, delivery="followup")

Wake up but do not trigger a round, only write to context:

interconnect_send(instanceId="peer", sessionId, text, resume=true, delivery="inject")

Use Cases and Considerations¶

Suitable for:

• Developers needing agent collaboration across multiple machines or DSH instances
• Scenarios where the model proactively discovers remote sessions, delivers messages, and receives replies via tools
• Integrations requiring cross-instance event streaming (lifecycle events are emitted via interconnect/event)

Before use, note:

1. The plugin runs with the permissions of the current DSH process; before installation, review the source code and MIT license.
2. From version 0.9 onward, transport is WebSocket-only with no HTTP fallback to unreachable peers; during deployment, ensure the origins in the peers mapping are reachable and both ends have the same DSH_INTERCONNECT_TOKEN.
3. resume triggers a full agent round and incurs model call costs, disabled by default; the receiver can set allowResume: false to refuse.
4. Sessions owned by subagents cannot be directly targeted and must be reached via the parent agent.
5. Deployments without Host agent lookup (headless, no api-proxy) cannot wake up offline sessions and will degrade to session-not-live.

Conclusion¶

dsh-interconnect bundles cross-instance message delivery, liveness probing, event streaming, and model tools into one bundle, replacing manually maintained HTTP endpoints with instanceId + persistent WebSocket links. If you need agents to send messages, list sessions, and probe online status across multiple DSH instances, dsh-interconnect is currently one of the more complete workflow solutions in the community.

• Community directory: https://www.skillhub.cn/plugins/Chinesezjc/dsh-interconnect
• GitHub: https://github.com/Chinesezjc/dsh-interconnect
• npm: https://www.npmjs.com/package/dsh-interconnect