@nelsonlongxiang/dsh-open-a2a-net

English | 中文


Open A2A network plugin for DeepSeek Harness (DSH): turns a DSH deployment into one node of a decentralized agent network — no central server, no registry.

Each node publishes a signed, expiring agent card at /.well-known/agent-card.json, discovers peers through seed URLs and referrals (each card lists the peers it knows), resolves names through zone delegations (GNUnet GNS-style: a card may delegate a name to another zone), and routes directly to a peer's team with failover across the reachable half of candidates. Every main session can additionally be exposed as a session node other hosts can discover and join from the web sidebar.

Install

dsh plugin --profile web add @nelsonlongxiang/dsh-open-a2a-net

Restart dsh web, then open the sidebar network panel (footer action).

(As a package specifier, a local path, or a Git URL; the package runs pnpm build in prepare, so a source install builds on install. Note: a standalone Git install currently fails to build outside a DSH profile — the official @deepseek-ai/* npm packages lag the harness source this plugin compiles against, so install from the registry or inside a profile whose harness provides current @deepseek-ai peers.) The plugin composes beside the stock webserver row: it registers its card, state, and control routes on the shared listener and its model tools on the shared tool runtime.

What you get

• Model tools — a2a_teams lists the teams this node can see (own, peers', joined sessions'); a2a_route

sends one message to a team, reuses context_id to continue a remote conversation, and fails over across candidates when a peer is unreachable.

• Sidebar control — a footer action in the web sidebar listing this host's sessions as joinable network

nodes: title, recent-activity excerpt, and team per row, join/leave in place, and a wake action for cold rows (persisted join intent whose session is not loaded yet — opening the session remounts the node). Session teams are <team>/<id8>; web sessions use their id's first 8 chars, imported sessions (import-<uuid>) keep the import- prefix plus the uuid's first 8 hex chars so imported ids cannot collapse into a handful of teams.

• Archive leaves the network — archiving a session (workspace registry state) prunes its join

intent and unmounts its node: at boot settlement before any wake, on every state read (a mid-session archive disappears within one panel poll), and as a route-time guard that never wakes an archived target.

• Honest waits — a synchronous route whose target never answers releases the caller at a 180s

reply-wait deadline with the delivered shape and the receipt contract (the target answers on its own cadence); async: true skips the wait entirely. The network panel dims an in-flight row past 120s as a stale wait instead of implying live progress, and its title carries the package version badge.

• Announce — announce: true publishes this node's card (team, capabilities, referrals, joined session

teams) so peers find it without any directory.

Configuration

Row config overlays in the profile's patch layers; every key has a schema default.

Example — one announcing node with a seed:

- id: a2a
  name: '@nelsonlongxiang/dsh-open-a2a-net'
  config:
    announce: true
    peers: ['http://127.0.0.1:41243']

Trust model

Cards are Ed25519-signed and expire; peers referrals and sessionTeams listings on a card are unsigned and read fresh. The /__dsh_a2a/join and /__dsh_a2a/leave control routes require the configured apiKey (constant-time compare) when one is set; with an empty key they trust only same-origin browsers and loopback callers. Set an apiKey before exposing the listener beyond loopback.

Collaboration SOP (network practice, v0.1)

Distilled from the 0.1.x–0.5.x delivery cycles by the network's research node; adopted by the maintainer.

• Roles — one session, one office, no crossing workspace boundaries: a research node (protocol/design

review, verdict criteria, source-line references with must-fix/recommend labels), a maintainer node (version rulings, releases, adoption receipts), a test node (the single execution point for all live-host verification; production hosts are never used for ad-hoc testing), and an install/ops node (production profile deployment, single-owner, waits for the maintenance window).

• Dispatch discipline — test tasks go to the test node with version + commit + decidable criteria +

receipt target; review tasks go to the research node with source pointers, not paraphrases.

• Receipt contract — tasks longer than minutes route with async: true (wait:false); receipts read

[A2A receipt] task <task_id> <outcome summary>; the task id is caller-born, request-carried, peer-echoed, and steered-header-transmitted — four-way agreement before a receipt correlates.

• Upgrade chain — test node green → maintainer receipt → ops node requests the window → production

upgrade → maintainer's browser-face final check → network-wide notice.

• Reuse red lines — shared pure logic extracts to a library; shared runtime capability extracts to a

Service; plugins never value-import each other; production hosts carry no verification duty (no dev-who-self-tests).

Verify

pnpm install   # auto-install-peers pulls the DSH peer train from npm
pnpm verify    # typecheck, build, source tests, and built-artifact layout guard
pnpm build     # host lib (including lib/a2a-client.js), client types, and browser bundle (lib/client.js)

License

MIT