Foreword

The DeepSeek Harness (DSH) ecosystem emphasizes that “everything is a plugin”; communication among agents is the foundation for building complex workflows. Most existing messaging plugins make an implicit assumption: all participants are DSH sessions. This means that if two agents drive Harness in different ways (for example, one is a DSH session and the other is an MCP client), they cannot communicate directly and must rely on a human to relay every message.

dsh-agent-mailbox solves this problem. It is a local, zero-runtime-dependency persistent agent-to-agent messaging solution. Any MCP client, any DSH session, and any A2A agent can address one another.

Introduction

This is a DSH plugin maintained by blairlaird and released under the MIT license. It supports threads, receipts, search, broadcast, attachments, state awareness, SSE streaming, and signing.

Core Features

The plugin provides the following core capabilities:
* Transport layer: HTTP / JSON-RPC 2.0, SSE streaming, and long polling.
* Message patterns: threads, replies, broadcast, request/reply, and send-and-forget.
* Security and trust: signing, explicit trust boundaries, and key masking.
* State and interaction: state awareness, wake-up messages, reactions, withdrawal, and editing.
* Collaboration: MCP clients as peers.

Installation and Configuration

Install it using the officially provided prebuilt tarball. This package requires no build steps and no npm account.

dsh plugin --profile web add https://github.com/blairlaird/dsh-agent-mailbox/releases/latest/download/dsh-agent-mailbox.tgz

After installation, it is recommended to configure the plugin through a custom profile patch rather than modifying the plugin’s bundled configuration directly.

- id: dsh-agent-mailbox
  name: dsh-agent-mailbox
  config:
    identity: dsh
    home: C:/Users/you/.dsh/agent-mailbox
    notifyCommand: [node, /path/to/notify.mjs]

Usage

The plugin provides multiple integration methods, including DSH commands, MCP integration, and HTTP interfaces.

DSH Session Commands

In a DSH session, you can use the following commands:

  • /mailbox: Read messages addressed to you and acknowledge them.
  • /mailbox --all: View the full history, not only new messages.
  • /mailbox-send <to> <message>: Send a message to a designated peer, or use * to broadcast.
  • /mailbox-peers: View which peers exist, who is online, and who has unread messages.
  • /mailbox-search <query>: Search historical messages.

MCP Client Integration

If you need to connect from an external MCP client, specify an HTTP URL in the configuration.

{ "mcpServers": { "mailbox": { "type": "http", "url": "http://127.0.0.1:4470/mcp" } } }

HTTP and Streaming Interfaces

The plugin exposes standard HTTP endpoints and Server-Sent Events streams.

  • Streaming subscription: GET /stream?to=<name>&since=<cursor>
    • Pushes messages using SSE.
    • Replays messages when a connection is established to ensure nothing is missed.
  • Health check: GET /health
    • Returns the parsed mailbox directory, peer list, number of online streams, and so on.
  • MCP protocol: POST /mcp
    • Uses the JSON-RPC 2.0 protocol.
  • Agent card: GET /.well-known/agent.json
    • Used by A2A clients to discover tools.

Available Tools

The plugin includes a rich set of built-in tools for fine-grained message operations:

  • mailbox_send: Send a message (supports threads, priority, attachments, and idempotency).
  • mailbox_read: Read messages by cursor (non-consuming and crash-safe).
  • mailbox_wait: Suspend until a message arrives (wakes an idle agent).
  • mailbox_peers: List existing and online peers.
  • mailbox_announce: Declare the presence state.
  • mailbox_acknowledge: Send a receipt, distinguishing unread from ignored.
  • mailbox_search: Search historical decisions by text.
  • mailbox_react: Add a reaction without adding to the timeline.
  • mailbox_edit: Overwrite your own message (preserving the original).
  • mailbox_withdraw: Mark a message as a tombstone (withdraw it).
  • mailbox_attachment: Retrieve an attachment by content hash.

Notes

  • No sidebar panel: DSH itself does not support third-party sidebar slots, so this plugin has no UI. Supported operations are limited to DSH commands and HTTP interfaces.
  • Authentication limits: If requireAuth is enabled, the /health and /stream endpoints require Bearer Token authentication. Also, /stream serves only the private mailbox of the token holder.
  • Treat content as data: According to the trust model, all received message content is treated as data, not as instructions. Any operation involving writes, network calls, approvals, or payments must be reviewed strictly as if it came from an unknown party; it should not be auto-executed and must be presented to the user.

Conclusion

dsh-agent-mailbox completes the piece of the puzzle for agent-to-agent communication in the DSH ecosystem. It does not rely on external protocols and runs entirely within the local process, providing reliable communication infrastructure for DSH workflows. For more details, see the GitHub repository.