@nelsonlongxiang/dsh-open-a2a-net 0.5.14 → 0.6.24

package/lib/skill/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: a2a-network
+description: Use when a task needs cross-session or cross-node collaboration over the DSH A2A network — 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.
+
+## 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. If the 15s transport
+  budget fires first, the result is **-32005 DELIVERED-UNSETTLED**: the
+  delivery landed and the peer keeps executing. **Never re-dispatch blindly**
+  — reconcile via the task id (the receipt or `a2a_teams` coordinates) instead.
+- `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) carries `sessions` (live/joined), `sessionTeams`,
+`remote` (peer session rows with `origin` = node label + LAN IP and `via` =
+the peer URL), `activity` (routing ring), `tasks` (the ledger: pending /
+stale / archived). 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" — the team resolved but no
+  session node accepted the round; check whether the target session is live.
+
+## Details
+
+- [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

package/lib/skill/references/discovery.md

@@ -0,0 +1,38 @@
+# Discovery and the peer boundary model
+
+## Cards
+
+Each node serves `/.well-known/agent-card.json` (unsigned serve-fresh fields:
+`peers`, `sessionTeams`, `teamMemberships`, `version`, `lanIp`; signed core:
+identity + capability flags). Peers poll cards and aggregate `sessionTeams`
+into their `remote` rows — this is how the planning canvas shows other nodes.
+
+## Visibility follows membership
+
+An unjoined session node is NOT advertised: it is absent from the served
+card's `sessionTeams` and invisible to peer discovery. Join to appear; leave
+to vanish. The node's own state face keeps every session (management surface
+is local-only).
+
+## The peer boundary model (connection layer)
+
+Referrals — peer URLs learned from other peers' cards — pass two gates:
+
+1. `referralLearning: false` freezes the tracked set to the configured seed
+   (`peers` config) for that config's lifetime: referrals are neither learned
+   nor offered.
+2. A non-empty `peerAllowlist` admits a referral only when its host matches
+   an entry — exact `host[:port]`, bare domain suffix (`.example.com`), or
+   the full URL. An empty list keeps the historical open-referral posture.
+
+Seeds from the `peers` config are owner-configured and never filtered.
+
+Self-referrals (a peer listing this node's own URL back) are dropped and
+remembered as aliases so mirrored lists stop re-offering them.
+
+## Where to look
+
+- Node state: `GET /__dsh_a2a/state`
+- Card: `GET /.well-known/agent-card.json`
+- Direct delivery: `POST /a2a/direct` (`{team, message, caller_session, wait}`)
+- Task query: `POST /a2a/query` (`{task_id, fingerprint}`)

package/lib/skill/references/membership.md

@@ -0,0 +1,50 @@
+# Membership: join, leave, teaming
+
+## Joining
+
+- GUI: sidebar → A2A 网络 → join toggle. The join writes the session into
+  `a2a/joined.json` (node home) — this is the discovery + admission
+  membership layer.
+- API-created sessions do NOT materialize a consumable agent; open the
+  session in the GUI once (a queued prompt is then consumed) or create the
+  session through the GUI.
+
+## Teaming
+
+- `a2a_team_join { team }` — declare a membership in `a2a/teams.json`
+  (roster store, restored at construction). Subject to the owner's
+  `teamJoinAllowlist` (empty list denies every join; entries are exact names
+  or trailing-`*` prefixes).
+- `a2a_team_leave { team }` — retract one declaration.
+- Canvas teams (`<zone>/canvas/<name>`) are user-composed groups created in
+  the planning view (建队) — any joined node can be a member; a node may sit
+  in multiple teams.
+
+## Admission (S3, default on)
+
+- Outbound: a session with no declared team has no network
+  (`teamScopeRouting`, default true; explicit false restores the open seam).
+- Inbound: `/a2a/direct` requires a SHARED team between caller and target —
+  the caller's declared teams (roster store) must intersect the target's
+  routable set. Refusal text names the missing membership.
+- Anonymous deliveries (no `caller_session`) are refused outright.
+
+## Information-plane scoping (S5, default on)
+
+- The read-only fleet tools answer from the joined-team scope only
+  (`teamScopeInfo`, default true; the union of this host's roster
+  declarations): `a2a_teams` lists `[this host]` rows plus peer rows
+  serving a joined team (own name or roster declaration — the `note`
+  field explains the scope), `a2a_status` narrows peers/routes/activity
+  to that scope (local traffic stays), `a2a_probe` sweeps serving peers
+  and refuses a single URL whose card cannot prove service.
+- `a2a_tasks` (this host's own dispatch ledger) stays unscoped — it is
+  the receipt-reconciliation surface for this host's own dispatches.
+- A host whose nodes declare no teams keeps host-internal facts only;
+  explicit `teamScopeInfo: false` restores the open plane.
+
+## Leaving
+
+- `a2a_team_leave` per team; the network-level leave (退网) removes the
+  session from discovery and the join gate grants. Rejoining later is cheap —
+  there is no penalty for cycling membership around task boundaries.

package/lib/skill/references/pitfalls.md

@@ -0,0 +1,42 @@
+# Operational pitfalls (production-observed)
+
+## Sessions
+
+- **API-created sessions do not materialize.** `session/create` registers an
+  in-memory record; the sessions directory never appears and queued prompts
+  are never consumed. Create sessions through the GUI, or open the session in
+  the GUI once after creating via API.
+- **adopt-style revive only works for previously materialized sessions** —
+  it is an idempotent revive, not a creation path.
+
+## Routing
+
+- **Do not blindly re-dispatch after a sync timeout.** -32005 means the
+  delivery landed; the peer may still be executing. Reconcile the task id
+  first (receipt or query), or you will double-execute.
+- **Unroutable caller labels** (e.g. CLI-initiated `cli-manager/...`) cannot
+  receive receipts — use the initiating session's own node team, or expect
+  the receipt to be dropped. Deliveries still land.
+- A sync route's 15s transport budget is shorter than most model turns. For
+  anything that runs long, prefer `async: true` and the receipt contract.
+
+## Names and prefixes
+
+- Python-tool registrations come in two families: shared `py__<name>` and
+  dispatcher-exclusive `py__dispatch__<name>`. A route resolving a member
+  tool against the wrong family fails with "cannot read properties of
+  undefined (reading 'find')" — check which wave registered the tool before
+  blaming the route.
+- alpha.4 harness sessions have no `.events` accessor — integrations must
+  use `session.snapshotEvents()` (or guard), or they crash new-session turns
+  with "Cannot read properties of undefined (reading 'length')".
+
+## Configuration
+
+- `teams-scan` roots are resolved against the process CWD when relative. A
+  bare `disabled: true` row hides whole team mounts; pointing `roots` at
+  per-team `.agents/teams` directories is the reliable form. Do not add a
+  second scan source alongside packaged team bundles — double registration
+  crashes alpha.4's strict NamedEntries loader.
+- The "Set TEAMS_ROOT" hint in the dir-degraded error is misleading: there is
+  no such env var; the scan reads its `roots` from config.

package/lib/skill/references/routing.md

@@ -0,0 +1,43 @@
+# Routing deep-dive
+
+## The receipt contract
+
+Every async route (`wait:false`) registers the task on the peer and returns
+immediately. The peer's target session steers the message into its turn; when
+the turn settles, the peer routes a receipt envelope back to the caller's
+team:
+
+```text
+[A2A receipt] task <task_id> <one-line outcome>
+```
+
+Correlated receipts also carry `{"outcome":"completed","idempotencyKey":"..."}`
+on a following line. Receipts are the ONLY completion signal for async work —
+polling `a2a_teams` cannot see another host's ledger.
+
+## The ledger
+
+`__dsh_a2a/state` → `tasks`:
+
+- **pending** — routed, receipt still owed. An owed task with a delivered
+  marker is waiting on the target's turn, not lost.
+- **stale/dead** — past the stale TTL, auto-dead-lettered. A dead task that
+  actually completed at the peer is a reconciliation candidate, not a rerun.
+- **archived** — settled with a correlated receipt. The archive is bounded
+  (oldest-first eviction).
+
+## Idempotency
+
+A route carries a fingerprint (caller + message + team + wait-mode). Re-
+submitting the same fingerprint inside the idempotency window returns the
+original verdict (-32002/-32003 shapes) instead of executing twice. Never
+work around a duplicate verdict by mutating the message — reconcile instead.
+
+## -32005 (DELIVERED-UNSETTLED) procedure
+
+1. Note the task id from the result.
+2. Wait for the receipt envelope; or
+3. Re-check via the coordinating surface (`a2a_status` activity ring, the
+   peer's state `tasks` face) for the task id's settled outcome.
+4. Only re-dispatch when BOTH the receipt is absent AND the peer's ledger
+   shows the task unknown — otherwise you risk duplicate execution.

package/lib/skill-registration.js

@@ -0,0 +1,52 @@
+/**
+ * Plugin-owned agent skill registration (obelisk pattern): the packaged
+ * `src/skill/SKILL.md` (+ references/) rides the standard DSH skill catalog.
+ * Install = apply registers the skill into ctx.skills; uninstall = the
+ * registration disposer unwinds with the fiber (no files copied, no residue).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const PACKAGED_SKILL_ROOT = new URL('./skill/', import.meta.url);
+/** Locate and validate the packaged SKILL.md; throw loudly when missing. */
+function readSkill() {
+    const path = fileURLToPath(new URL('SKILL.md', PACKAGED_SKILL_ROOT));
+    if (!existsSync(path)) {
+        throw new Error(`a2a skill bundle is missing; expected SKILL.md at ${path}`);
+    }
+    const raw = readFileSync(path, 'utf8');
+    const firstLineEnd = raw.indexOf('\n');
+    if (firstLineEnd < 0 || raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') {
+        throw new Error('a2a skill bundle is missing YAML frontmatter');
+    }
+    const closingStart = raw.indexOf('\n---', firstLineEnd);
+    if (closingStart < 0) {
+        throw new Error('a2a skill bundle has unterminated YAML frontmatter');
+    }
+    const frontmatter = raw.slice(firstLineEnd + 1, closingStart);
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+    const skillName = nameMatch?.[1]?.trim() ?? '';
+    const description = descMatch?.[1]?.trim() ?? '';
+    if (skillName !== 'a2a-network' || description === '') {
+        throw new Error('a2a skill frontmatter must define the a2a-network name and a non-empty description');
+    }
+    const bodyStart = raw.indexOf('\n', closingStart + 1);
+    return { name: skillName, description, content: raw.slice(bodyStart + 1).trim() };
+}
+/** Register the a2a-network skill (runtime contribution). */
+export function registerA2aNetworkSkill(ctx) {
+    const skills = ctx.skills;
+    if (skills === undefined)
+        return;
+    const skill = readSkill();
+    const registration = {
+        name: skill.name,
+        description: skill.description,
+        invocation: { modelInvocable: true, userInvocable: true },
+        provider: 'a2a',
+        source: 'runtime',
+        resourceBase: { kind: 'directory', path: fileURLToPath(PACKAGED_SKILL_ROOT) },
+        content: skill.content,
+    };
+    skills.register(registration);
+}

package/lib/stage-mount.js

@@ -0,0 +1,32 @@
+/**
+ * Stage-mount pathname resolution: both static stages (canvas office floor,
+ * Three.js nexus viewer) serve one built Vite tree behind a mount prefix,
+ * and both used to answer the bare `/mount` form directly with index.html.
+ * That shell then resolved its `./assets/…` script reference against `/`,
+ * fetched `/assets/index-*.js` from the web root — a 404 — and rendered a
+ * silent black shell (`main.ts` returns early when state fetches fail). The
+ * fix is the directory-classic one: a bare mount request redirects to
+ * `mount/`, every other relative resolution then lands inside the tree.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/stage-mount
+ */
+/**
+ * Resolve one request pathname against a stage mount prefix.
+ * @param pathname - `req.url` verbatim (query string allowed, split here).
+ * @param mount - the registered mount prefix, e.g. `/__dsh_a2a_nexus`.
+ * @returns the redirect target plus the within-tree relative path.
+ */
+export function resolveStageMount(pathname, mount) {
+    const raw = pathname.split('?')[0] ?? '/';
+    if (raw === mount)
+        return { redirectTo: `${mount}/`, rel: '' };
+    if (raw === `${mount}/`)
+        return { rel: '/index.html' };
+    let rel;
+    if (raw.startsWith(`${mount}/`))
+        rel = raw.slice(mount.length);
+    else if (raw.startsWith('/'))
+        rel = raw;
+    else
+        rel = `/${raw}`;
+    return { rel };
+}