@nelsonlongxiang/dsh-open-a2a-net 0.6.40 → 0.6.42

package/lib/index.js

@@ -9,6 +9,7 @@ import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, ran
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { networkInterfaces } from 'node:os';
 import { selectLanIPv4 } from "./lan-ip.js";
+import { isLinkKey, normalizeLinkKeys, originOf, outboundKeyFor } from "./link-keys.js";
 import { dirname, join } from 'node:path';
 import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
 // The package own version, read from package.json at load time so the
@@ -52,7 +53,7 @@ import { createFloodGuard } from "./flood-guard.js";
 import { createQueueGuard, queueFullRefusal, QUEUE_FULL_NEXT, WIRE_ERROR_QUEUE_FULL } from "./queue-guard.js";
 import { resolveZone } from "./zone.js";
 import { registerA2aNetworkSkill } from "./skill-registration.js";
-import { isRootOriginUrl, sameMountedUrl, signOriginClaim, verifyOriginClaim as verifyOriginClaimOf } from "./origin-claim.js";
+import { isRootOriginUrl, sameMountedUrl, originClaimTeamWarning, signOriginClaim, verifyOriginClaim as verifyOriginClaimOf } from "./origin-claim.js";
 import { AuthObserver } from "./auth-observer.js";
 import { allowlistVersion, authorizationRef, buildAuthorization, callerAdmission, localCandidateAdmission, canonicalAllowlist, judgeSettlement, joinedFaceAdmission, refusalOf, sameZoneAdmission, recheckRemoteCliAuthorization } from "./task-auth.js";
 import { MessageId } from '@deepseek-ai/dsh-llm';
@@ -172,6 +173,9 @@ export function apply(ctx, config) {
     });
     // F4 slice: say the quiet part at boot instead of leaving the exposure to
     // be discovered from a ledger full of unexplained steering.
+    const teamWarning = originClaimTeamWarning(config.team);
+    if (teamWarning !== undefined)
+        logger.warn(teamWarning);
     const exposure = directDeliveryExposure(config.peers, config.apiKey);
     if (exposure.warning !== undefined)
         logger.warn(exposure.warning);
@@ -199,7 +203,9 @@ export function apply(ctx, config) {
         }
     };
     // gh#193: the one door to peers — while isolated nothing leaves this host.
-    const peerFetch = (url, init) => config.isolated ? Promise.reject(new Error('isolated: outbound peer traffic is off on this host')) : globalThis.fetch(url, init);
+    // Review of #318 R4: never follow a peer's redirect — X-API-Key and the OriginClaim headers are not stripped on
+    // a cross-origin hop, so a 3xx would hand them to whoever the Location names. A redirect is an HTTP failure.
+    const peerFetch = (url, init) => config.isolated ? Promise.reject(new Error('isolated: outbound peer traffic is off on this host')) : globalThis.fetch(url, { ...init, redirect: 'manual' });
     const fetchImpl = (url, init) => peerFetch(url, init);
     /** Constant-time secret comparison: hash both sides to equal-length digests. */
     function secretEqual(a, b) {
@@ -207,6 +213,39 @@ export function apply(ctx, config) {
         const digestB = createHash('sha256').update(b).digest();
         return timingSafeEqual(digestA, digestB);
     }
+    // #317 link keys (src/link-keys.ts): a per-peer X-API-Key on the peer faces, never on the control routes.
+    const linkKeyMap = normalizeLinkKeys(config.linkKeys);
+    /**
+     * The peer-face key gate (/a2a/direct, /a2a/log, /a2a/blob): this host's apiKey as before; a link key only
+     * from a host whose OriginClaim verifies here BOUND to this very request (audience-bound v2 — never a v1
+     * envelope replayed onto another path; a POST also body-bound, Sig3), and only the key configured for that
+     * signer's own origin (review of #318 R1, R3). A leaked link key cannot act without that peer's node key.
+     * An empty apiKey keeps the open posture.
+     * @param req - the inbound peer request.
+     * @param rawBody - the request body, for a POST.
+     */
+    async function peerKeyAdmits(req, rawBody) {
+        if (config.apiKey === '')
+            return true;
+        const presented = String(req.headers['x-api-key'] ?? '');
+        if (secretEqual(presented, config.apiKey))
+            return true;
+        if (!isLinkKey(presented, linkKeyMap, secretEqual))
+            return false;
+        const claim = await verifyOriginClaim(req, rawBody !== undefined ? { rawBody } : undefined);
+        if (!claim.ok || claim.cli === true || !claim.bound || (rawBody !== undefined && claim.bodyBound !== true))
+            return false;
+        const expected = linkKeyMap.get(originOf(claim.callerUrl));
+        return expected !== undefined && secretEqual(presented, expected);
+    }
+    /**
+     * The headers of one signed peer read (the remote session-log proxy): the OriginClaim for `url` (origin and
+     * path, no query) and the key for that target — its link key, else this host's apiKey (review of #318 R2).
+     */
+    function peerRequestHeaders(url, method) {
+        const key = outboundKeyFor(url, linkKeyMap, config.apiKey);
+        return { ...originClaimHeaders({ url, method }), ...(key !== '' ? { 'X-API-Key': key } : {}) };
+    }
     /**
      * No-key trust for the control routes (gh#7 N1, V1): ONLY a loopback
      * socket — header-only trust (Sec-Fetch-Site, Origin) admitted any
@@ -471,6 +510,7 @@ export function apply(ctx, config) {
     }
     const client = new A2aClient({
         apiKey: config.apiKey,
+        apiKeyFor: url => outboundKeyFor(url, linkKeyMap, config.apiKey),
         sessionId: session,
         cardCaller: config.team,
         // gh#9+gh#10 OriginClaim (docs/protocol/delivery-origin-auth.md): every
@@ -1618,11 +1658,13 @@ export function apply(ctx, config) {
                 // MINIMAL discovery card.
                 handler: async (req, res) => {
                     const send = (named, body_) => {
-                        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body_) });
+                        res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body_), 'Cache-Control': 'private, no-store' });
                         res.end(body_);
                         void named;
                     };
                     const claim = await verifyOriginClaim(req);
+                    // #312: signed discovery is a reduced face; it never requests a full-card callback.
+                    const discoveryOnly = new URL(req.url ?? '/', 'http://x').searchParams.get('discovery') === '1';
                     // W3 (#18 half-side, 0.6.25): a VERIFIED envelope proves the
                     // caller holds a real node key — it does not prove a relationship
                     // with THIS host. The full card (sessionTeams/rosters =
@@ -1633,14 +1675,17 @@ export function apply(ctx, config) {
                     // Interaction with the OriginClaim narrowing: the caller is a
                     // bare zone; linkage judges that zone face against our canvas
                     // remote refs, joined handles, and the caller card's peers.
-                    const named = claim.ok && callerLinkedToThisHost(claim.caller, claim.ok ? claim.callerUrl : '', claim.ok ? claim.card : undefined);
+                    const linkedCaller = claim.ok && callerLinkedToThisHost(claim.caller, claim.callerUrl, claim.card);
+                    const showPeers = claim.ok && (configuredSeedCaller(claim.callerUrl) || linkedCaller);
+                    const named = !discoveryOnly && linkedCaller;
                     // gh#7 G1 (review-seat R2 ruling): the card serves two faces.
                     // A NAMED caller — ?caller_session= or the X-A2A-Caller header in
                     // the zone or zone/id8 shape — gets the FULL card. An anonymous
                     // fetcher (or an invalid shape, fail-closed) gets the MINIMAL
-                    // card: name/team/session/capabilities/records/peers/signature
-                    // stay (discovery, gossip, delegation, capability negotiation
-                    // unbroken), while sessionTeams/teamMemberships/lanIp are
+                    // card: name/team/session/capabilities/records/signature stay.
+                    // #312/#324 F1: peers requires a verified caller that we explicitly seed
+                    // or already link; unrelated self-signed strangers get no topology.
+                    // Meanwhile sessionTeams/teamMemberships/lanIp are
                     // omitted — session membership and rosters are collaboration
                     // facts, not discovery facts. Named determination does NOT
                     // require a shared team: demanding roster symmetry before the
@@ -1696,7 +1741,8 @@ export function apply(ctx, config) {
                     const memberships = teamMemberships.list().flatMap(entry => entry.teams.map(team => ({ node: `${config.team}/${id8(entry.session)}`, team })));
                     const body = JSON.stringify({
                         ...currentCard,
-                        peers: peerStore.list(),
+                        // #324 F1: possession of an arbitrary self-signed identity is not a local relationship.
+                        ...(showPeers ? { peers: peerStore.list() } : {}),
                         ...(named && sessionTeams.length > 0 ? { sessionTeams } : {}),
                         ...(named && memberships.length > 0 ? { teamMemberships: memberships } : {}),
                         // gh#41 fleet planning (owner ruling: any peer composes and
@@ -2073,21 +2119,20 @@ export function apply(ctx, config) {
      */
     function routeIntoAgentFor(agent, team, message, caller, taskId, proofClause, buildHeader, localFrom, onSteered) {
         return new Promise((resolve) => {
+            // #306: synchronous replies use the same reading-turn attribution as automatic receipts.
+            // Registering and steering are synchronous, so this is the exact pre-steer floor.
             const floorAtRegistration = sessionEventsOf(agent).length;
             const waiter = registerFinalWaiter(agent, (text, placeholder) => {
-                // #298 (review of #305 F4): the sync wait may close on a busy target's OTHER turn. `ownTurn` states,
-                // from this session's own events, that the steer carrying this task was read and that the reply is the
-                // reading turn's own last text — the only reply a peer may declare final (`reply_final`).
+                // Preserve #305's reply_final contract: only this task's own completed reading turn qualifies.
                 let ownTurn = false;
                 if (placeholder !== true && taskId !== undefined && taskId !== '') {
                     const events = sessionEventsOf(agent);
                     const read = consumptionIndex(events, taskId, floorAtRegistration);
-                    // The receipt's own window (review of #305 F5): a back-to-back next turn's text is not this turn's.
                     const window = read === undefined ? undefined : readingTurnReply(events, read);
                     ownTurn = window !== undefined && window.completed && window.reply !== '' && window.reply === text;
                 }
                 resolve({ ok: true, reply: text, ...(placeholder === true ? { placeholder: true } : {}), ...(ownTurn ? { ownTurn: true } : {}) });
-            });
+            }, taskId !== undefined && taskId !== '' ? { taskId, steerFloor: floorAtRegistration } : undefined);
             // The header names the sender first: `caller` is the routing node's
             // own label (the session that issued the route), while `team` is this
             // request's target — showing the target as "remote team" hid the
@@ -2146,8 +2191,21 @@ export function apply(ctx, config) {
         boundMissRecent.unshift({ ...row, count: row.count + 1, lastAt: Date.now() });
         boundMissRecent.length = Math.min(boundMissRecent.length, 16);
     };
-    function verifyOriginClaim(req, options) {
-        return verifyOriginClaimOf(req, {
+    /** Our configured seeds anchor origin claims; mounted claims require exact mount matching. */
+    function configuredSeedCaller(callerUrl) {
+        return config.peers.some(peer => {
+            try {
+                return isRootOriginUrl(callerUrl) ? new URL(peer).origin === new URL(callerUrl).origin : sameMountedUrl(peer, callerUrl);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    // #312: topology-only callbacks must never replace a full session/roster card cache entry.
+    const signedDiscoveryPeers = new Map();
+    async function verifyOriginClaim(req, options) {
+        const claim = await verifyOriginClaimOf(req, {
             cardCache,
             fetch: fetchImpl,
             audiences: [ownCardUrl, ...config.originClaimAudiences ?? []],
@@ -2159,6 +2217,32 @@ export function apply(ctx, config) {
             ...(options?.cli === true ? { cliDeposit: cliDepositCard } : {}),
             ...(options?.rawBody !== undefined ? { rawBody: options.rawBody } : {}),
         });
+        // #312: recover bilateral seed evidence from a signed, reduction-only card,
+        // never from a caller-selected unseeded URL and never recursively.
+        const discovery = new URL(req.url ?? '/', 'http://x').searchParams.get('discovery') === '1';
+        if (!discovery && claim.ok && claim.cli !== true && claim.card.peers === undefined && configuredSeedCaller(claim.callerUrl)) {
+            const discoveryKey = new URL(claim.callerUrl).href.replace(/\/$/, '');
+            const known = signedDiscoveryPeers.get(discoveryKey);
+            if (known !== undefined && known.key === claim.card.publicKey && known.expiresAt > Date.now() && Date.now() - known.at < config.cardCacheTtlMs)
+                return { ...claim, card: { ...claim.card, peers: known.peers } };
+            const target = claim.callerUrl.replace(/\/$/, '') + '/.well-known/agent-card.json?discovery=1';
+            try {
+                const response = await peerFetch(target, { method: 'GET', headers: peerRequestHeaders(target, 'GET'), redirect: 'manual', signal: AbortSignal.timeout(5_000) });
+                if (response.ok) {
+                    const verified = verifyCard(JSON.parse(await response.text()), Date.now());
+                    if (verified.ok && verified.card.publicKey === claim.card.publicKey && verified.card.team === claim.card.team) {
+                        if (verified.card.peers !== undefined) {
+                            signedDiscoveryPeers.set(discoveryKey, { at: Date.now(), expiresAt: verified.card.expiresAt, key: verified.card.publicKey, peers: verified.card.peers });
+                            if (signedDiscoveryPeers.size > 64)
+                                signedDiscoveryPeers.delete(signedDiscoveryPeers.keys().next().value);
+                        }
+                        return { ...claim, card: { ...claim.card, ...(verified.card.peers !== undefined ? { peers: verified.card.peers } : {}) } };
+                    }
+                }
+            }
+            catch { /* unavailable refresh keeps bilateral-link checks closed */ }
+        }
+        return claim;
     }
     /**
      * gh#133: the deposited card a CLI claim is judged by, or undefined when
@@ -2488,6 +2572,7 @@ export function apply(ctx, config) {
             joinedSessions,
             idempotencyStore,
             verifyOriginClaim,
+            peerKeyAdmits,
             remoteCliProof,
             forwardReceiptBasis: (taskId, caller, cliHandle, claim) => forwardReceiptBasis(taskLedger.find(taskId), caller, cliHandle, claim),
             forwardDirect: request => forwardDirect(request), ownCanvasFingerprint,
@@ -2495,7 +2580,6 @@ export function apply(ctx, config) {
             callerLinkedToThisHost, get ownCardUrl() { return ownCardUrl; },
             recordActivity,
             bumpLegacyInbound: () => { legacyInboundCount += 1; },
-            secretEqual,
             a2aCallerRefusal,
             a2aCallerAdmission,
             allowlistVersionNow,
@@ -2647,8 +2731,8 @@ export function apply(ctx, config) {
             }),
         }), 'a2a: quick-dispatch route');
         // gh#77: the session-log faces (local transcript reader + remote-log proxy) live in src/faces/session-log.ts.
-        registerSessionLogFaces(webServer, { ctx, config, controlRoute, scanSessionLogList, readSessionLogTail, peerStore, peerFetch, directoryPeerCandidates, memoizedCardFetch });
-        registerFileFaces(webServer, { ctx, config, blobStore, canvasStore, verifyOriginClaim, secretEqual, controlRoute, recordActivity });
+        registerSessionLogFaces(webServer, { ctx, config, controlRoute, scanSessionLogList, readSessionLogTail, peerStore, peerFetch, peerRequestHeaders, directoryPeerCandidates, memoizedCardFetch });
+        registerFileFaces(webServer, { ctx, config, blobStore, canvasStore, verifyOriginClaim, peerKeyAdmits, controlRoute, recordActivity });
     });
     /**
      * Settle one card-fetch outcome into the peer store and the plain card:

package/lib/link-keys.js

@@ -0,0 +1,29 @@
+/**
+ * #317 link keys: a per-peer `X-API-Key` so a public node never holds the fleet key. Outbound requests to a
+ * linked origin carry that link's key; inbound, a link key is accepted on the peer faces only when the
+ * caller's verified OriginClaim names exactly that origin. The control routes never accept a link key.
+ */
+import { originOf } from "./origin-claim.js";
+export { originOf };
+/** The configured link keys keyed by normalized origin; blank keys and unparsable origins are dropped. */
+export function normalizeLinkKeys(linkKeys) {
+    const out = new Map();
+    for (const [peer, key] of Object.entries(linkKeys ?? {})) {
+        const origin = originOf(peer);
+        if (origin !== '' && typeof key === 'string' && key !== '')
+            out.set(origin, key);
+    }
+    return out;
+}
+/** The `X-API-Key` to send to `url`: its link key, else this host's apiKey ('' omits the header). */
+export function outboundKeyFor(url, linkKeys, apiKey) {
+    return linkKeys.get(originOf(url)) ?? apiKey;
+}
+/** Whether `presented` is one of the link keys (every key is compared, in constant time each). */
+export function isLinkKey(presented, linkKeys, secretEqual) {
+    let matched = false;
+    for (const key of linkKeys.values())
+        if (secretEqual(presented, key))
+            matched = true;
+    return matched;
+}

package/lib/origin-claim.js

@@ -153,6 +153,10 @@ export function requestAudiences(req, configured, loopbackArrival = true) {
     return out;
 }
 const originClaimCallerShape = /^[a-z0-9-]+$/i;
+/** #312: explain unsupported host zone configuration without changing startup or signature policy. */
+export function originClaimTeamWarning(team) {
+    return originClaimCallerShape.test(team) ? undefined : 'a2a: configured host team contains invalid characters; OriginClaim cannot produce a verifiable host identity. Use ^[a-z0-9-]+$ (no slash).';
+}
 /**
  * Verify one request's envelope. Cheap refusals (shape, ts, audience,
  * closed window) answer before any card fetch; the card is then read from

package/lib/skill/SKILL.md

@@ -1,117 +1,117 @@
----
-name: a2a-network
-description: Use when a task needs cross-session or cross-node collaboration over the DSH A2A network — setting it up (install, config, apiKey, peers, canvas links for one host, two peers, or hosts that cannot reach each other), joining and teaming, routing work to remote teams and agents, reconciling receipts and the task ledger, and reading the A2A workbench (/__dsh_a2a_nexus/). Covers admission rules, the receipt contract, and the failure shapes that look like bugs but are contract semantics.
----
-
-# DSH A2A Network
-
-Drive the decentralized A2A network: sessions publish agent cards, join a
-membership layer, form canvas teams, and route work to each other through
-`a2a_route`. One plugin (`@nelsonlongxiang/dsh-open-a2a-net`) owns the whole
-surface on every node.
-
-## Objects
-
-- **Node** — one DSH host process exposing `/.well-known/agent-card.json` and
-  the `__dsh_a2a/state` face. Peers discover each other through cards.
-- **Session node** — a live DSH session on a node. Visibility follows
-  membership: an unjoined session is invisible to peer discovery AND refused
-  at the routing admission gate.
-- **Team** — a routable identity. Two kinds: the node's process team
-  (`<zone>/<id8>` from the session id) and canvas teams
-  (`<zone>/canvas/<name>`, user-composed multi-member groups).
-- **Task** — one routed round. Carries a task id, an idempotency fingerprint,
-  and a receipt contract.
-- **CLI identity** — a transient caller outside any session (the `a2a-net`
-  command, 0.6.27+): its own Ed25519 key and a handle `<name>/<16 hex>`,
-  deposited on ONE home host for up to 4h, with a mailbox instead of a
-  wakeable session. See [cli.md](references/cli.md).
-
-## Setting up
-
-Start with [setup.md](references/setup.md). It is a checked path for three
-network shapes:
-- **one host**: install, join the sessions, give them a shared team;
-- **two hosts that reach each other**: one shared `apiKey`, `announce` plus
-  peers seeded both ways, and a canvas team naming both handles;
-- **hosts that cannot reach each other**: host forwarding is not shipped
-  yet (#57), so tunnel or delegate per hop.
-
-The owner does the gestures (install, config, join, allowlist, canvas). The
-agent prepares the exact config and verifies each step with `a2a_whoami`,
-`a2a_probe`, `a2a_teams` and one round with a receipt.
-
-## Routing (a2a_route)
-
-```text
-a2a_route { team: "<zone>/<id8 or canvas name>", message, context_id?, async? }
-```
-
-- `async: true` delivers without waiting (`delivered:true` + task id); the
-  target routes a receipt — a message starting `[A2A receipt] task <id>` —
-  back to your team.
-- Sync (default) waits for the round's final answer. A target on this host
-  gets up to 180s; past that the tool answers the delivered shape
-  (`TASK_STATE_DELIVERED`) and the receipt contract carries the rest. A
-  remote peer's delivery rides a 15s transport budget; if it fires first, the
-  result is **-32005 DELIVERED-UNSETTLED**: the delivery landed and the peer
-  keeps executing. Either way, **never re-dispatch blindly** — reconcile via
-  the task id (the receipt, `a2a_status` activity, or `a2a_tasks`) instead.
-- Model tools cannot route to the bare process team (`<zone>` alone, the
-  host's own mailbox): target a session handle or a canvas team.
-- `context_id` from a previous reply continues that conversation.
-
-## Membership rules
-
-- An unjoined session has NO network: `a2a_route` and `a2a_teams` refuse it
-  (join gate), and discovery does not list it. The session that originates a
-  task is exempt from the gate.
-- Join through the GUI sidebar (A2A 网络) or the join gate prompt; leave
-  through the same surface. Membership is visible; leaving removes you from
-  discovery too.
-- Inbound deliveries from a caller with no `caller_session` are refused
-  (anonymous injection is a closed hole).
-
-## Reading the state
-
-`__dsh_a2a/state` (per node, key-gated like every control route) carries
-`sessions` (live/joined, with their teams), `canvas` (canvas teams; remote
-members show `remote: true`), `remote` (peer session rows with `origin` =
-node label + LAN IP and `via` = the peer URL), `activity` (routing ring),
-and the ledger: `tasks` (pending, each with `settleable`),
-`tasksStaleCount`, `tasksDead`, and `archived` (newest 64 settled rows, each
-with `outcome`, `endedBy` and `late`) plus `archivedCount` /
-`archivedSplit`. `sessionTeams` is a card field, not a state field. The A2A
-workbench (`/__dsh_a2a_nexus/`, merged responsive
-shell since 0.6.2 — the 2D planning board is the stage, directory / ledger /
-activity / plan ride a collapsible rail, narrow screens get a drawer)
-renders the same data for humans.
-
-## Failure shapes that are contract semantics
-
-- `-32000` with "declares no team membership" — the admission gate working
-  as designed; join (or route through a teamed member).
-- `-32000` with "caller_session is required" — the delivery had no caller
-  identity; the protocol contract requires it.
-- `-32005` — sync wait budget fired; delivery landed, reconcile the task id.
-- "No live DSH session node accepts team X" — no session node on the host
-  that received the delivery accepted the round. Either the target session is
-  not live/joined there, or X lives on ANOTHER host and the caller delivered
-  straight to this host's `/a2a/direct` (the `a2a-net` CLI does this):
-  direct delivery never relays to peers — `a2a_route` from a session does.
-- `[PATTERN_NO_MINT]` / `[ALLOWLIST_DENY]` on `a2a_team_join` — only an EXACT
-  allowlisted name joins; adding that name is the owner's act of creating
-  the team. `[CANVAS_TEAM]` — canvas membership is assigned in the workbench,
-  never by the roster tool.
-
-## Details
-
-- [setup.md](references/setup.md) — setup and checks: one host, two peers, beyond direct peers
-- [routing.md](references/routing.md) — receipts, idempotency, ledger anatomy
-- [discovery.md](references/discovery.md) — cards, peer boundary model, invisibility
-- [membership.md](references/membership.md) — join/leave, allowlist, canvas teams
-- [pitfalls.md](references/pitfalls.md) — operational pitfalls observed in production
-- [cli.md](references/cli.md) — the `a2a-net` CLI: deposit, mailbox, inbox hooks, limits
-- [collaboration.md](references/collaboration.md) — collaboration norm (Chinese): single-seat first, decide-then-report with no pre-authorization (a high-tier change needs one non-self node's review PASS on the same SHA), release tiers, stuck gates, credentials, receipts
-- [intake.md](references/intake.md) — intake node (Chinese): handling `workbench-event` deliveries from workbench-market — accept/decline/ask with a reason, open a GitHub issue on accept, write the decision back with the reply token
-- [router.md](references/router.md) — the chief's system prompt (Chinese), self-contained: route workbench events and owner requests to the right project's dev, order cross-project resource conflicts (it authorizes nothing since collaboration v1.18); immutable layer + self-kept mutable layer
+---
+name: a2a-network
+description: Use when a task needs cross-session or cross-node collaboration over the DSH A2A network — setting it up (install, config, apiKey, peers, canvas links for one host, two peers, or hosts that cannot reach each other), joining and teaming, routing work to remote teams and agents, reconciling receipts and the task ledger, and reading the A2A workbench (/__dsh_a2a_nexus/). Covers admission rules, the receipt contract, and the failure shapes that look like bugs but are contract semantics.
+---
+
+# DSH A2A Network
+
+Drive the decentralized A2A network: sessions publish agent cards, join a
+membership layer, form canvas teams, and route work to each other through
+`a2a_route`. One plugin (`@nelsonlongxiang/dsh-open-a2a-net`) owns the whole
+surface on every node.
+
+## Objects
+
+- **Node** — one DSH host process exposing `/.well-known/agent-card.json` and
+  the `__dsh_a2a/state` face. Peers discover each other through cards.
+- **Session node** — a live DSH session on a node. Visibility follows
+  membership: an unjoined session is invisible to peer discovery AND refused
+  at the routing admission gate.
+- **Team** — a routable identity. Two kinds: the node's process team
+  (`<zone>/<id8>` from the session id) and canvas teams
+  (`<zone>/canvas/<name>`, user-composed multi-member groups).
+- **Task** — one routed round. Carries a task id, an idempotency fingerprint,
+  and a receipt contract.
+- **CLI identity** — a transient caller outside any session (the `a2a-net`
+  command, 0.6.27+): its own Ed25519 key and a handle `<name>/<16 hex>`,
+  deposited on ONE home host for up to 4h, with a mailbox instead of a
+  wakeable session. See [cli.md](references/cli.md).
+
+## Setting up
+
+Start with [setup.md](references/setup.md). It is a checked path for three
+network shapes:
+- **one host**: install, join the sessions, give them a shared team;
+- **two hosts that reach each other**: one shared `apiKey`, `announce` plus
+  peers seeded both ways, and a canvas team naming both handles;
+- **hosts that cannot reach each other**: host forwarding is not shipped
+  yet (#57), so tunnel or delegate per hop.
+
+The owner does the gestures (install, config, join, allowlist, canvas). The
+agent prepares the exact config and verifies each step with `a2a_whoami`,
+`a2a_probe`, `a2a_teams` and one round with a receipt.
+
+## Routing (a2a_route)
+
+```text
+a2a_route { team: "<zone>/<id8 or canvas name>", message, context_id?, async? }
+```
+
+- `async: true` delivers without waiting (`delivered:true` + task id); the
+  target routes a receipt — a message starting `[A2A receipt] task <id>` —
+  back to your team.
+- Sync (default) waits for the round's final answer. A target on this host
+  gets up to 180s; past that the tool answers the delivered shape
+  (`TASK_STATE_DELIVERED`) and the receipt contract carries the rest. A
+  remote peer's delivery rides a 15s transport budget; if it fires first, the
+  result is **-32005 DELIVERED-UNSETTLED**: the delivery landed and the peer
+  keeps executing. Either way, **never re-dispatch blindly** — reconcile via
+  the task id (the receipt, `a2a_status` activity, or `a2a_tasks`) instead.
+- Model tools cannot route to the bare process team (`<zone>` alone, the
+  host's own mailbox): target a session handle or a canvas team.
+- `context_id` from a previous reply continues that conversation.
+
+## Membership rules
+
+- An unjoined session has NO network: `a2a_route` and `a2a_teams` refuse it
+  (join gate), and discovery does not list it. The session that originates a
+  task is exempt from the gate.
+- Join through the GUI sidebar (A2A 网络) or the join gate prompt; leave
+  through the same surface. Membership is visible; leaving removes you from
+  discovery too.
+- Inbound deliveries from a caller with no `caller_session` are refused
+  (anonymous injection is a closed hole).
+
+## Reading the state
+
+`__dsh_a2a/state` (per node, key-gated like every control route) carries
+`sessions` (live/joined, with their teams), `canvas` (canvas teams; remote
+members show `remote: true`), `remote` (peer session rows with `origin` =
+node label + LAN IP and `via` = the peer URL), `activity` (routing ring),
+and the ledger: `tasks` (pending, each with `settleable`),
+`tasksStaleCount`, `tasksDead`, and `archived` (newest 64 settled rows, each
+with `outcome`, `endedBy` and `late`) plus `archivedCount` /
+`archivedSplit`. `sessionTeams` is a card field, not a state field. The A2A
+workbench (`/__dsh_a2a_nexus/`, merged responsive
+shell since 0.6.2 — the 2D planning board is the stage, directory / ledger /
+activity / plan ride a collapsible rail, narrow screens get a drawer)
+renders the same data for humans.
+
+## Failure shapes that are contract semantics
+
+- `-32000` with "declares no team membership" — the admission gate working
+  as designed; join (or route through a teamed member).
+- `-32000` with "caller_session is required" — the delivery had no caller
+  identity; the protocol contract requires it.
+- `-32005` — sync wait budget fired; delivery landed, reconcile the task id.
+- "No live DSH session node accepts team X" — no session node on the host
+  that received the delivery accepted the round. Either the target session is
+  not live/joined there, or X lives on ANOTHER host and the caller delivered
+  straight to this host's `/a2a/direct` (the `a2a-net` CLI does this):
+  direct delivery never relays to peers — `a2a_route` from a session does.
+- `[PATTERN_NO_MINT]` / `[ALLOWLIST_DENY]` on `a2a_team_join` — only an EXACT
+  allowlisted name joins; adding that name is the owner's act of creating
+  the team. `[CANVAS_TEAM]` — canvas membership is assigned in the workbench,
+  never by the roster tool.
+
+## Details
+
+- [setup.md](references/setup.md) — setup and checks: one host, two peers, beyond direct peers
+- [routing.md](references/routing.md) — receipts, idempotency, ledger anatomy
+- [discovery.md](references/discovery.md) — cards, peer boundary model, invisibility
+- [membership.md](references/membership.md) — join/leave, allowlist, canvas teams
+- [pitfalls.md](references/pitfalls.md) — operational pitfalls observed in production
+- [cli.md](references/cli.md) — the `a2a-net` CLI: deposit, mailbox, inbox hooks, limits
+- [collaboration.md](references/collaboration.md) — collaboration norm (Chinese): single-seat first, decide-then-report with no pre-authorization (a high-tier change needs one non-self node's review PASS on the same SHA), release tiers, stuck gates, credentials, receipts
+- [intake.md](references/intake.md) — intake node (Chinese): handling `workbench-event` deliveries from workbench-market — accept/decline/ask with a reason, open a GitHub issue on accept, write the decision back with the reply token
+- [router.md](references/router.md) — the chief's system prompt (Chinese), self-contained: route workbench events and owner requests to the right project's dev, order cross-project resource conflicts (it authorizes nothing since collaboration v1.18); immutable layer + self-kept mutable layer