@nelsonlongxiang/dsh-open-a2a-net 0.6.30 → 0.6.32

package/lib/peer-directory.js

@@ -0,0 +1,134 @@
+/**
+ * Project a verified peer card into directory rows and identify its own
+ * advertised canvas teams (#159). The card's core is signed; sessionTeams,
+ * teamMemberships, and canvasOrg are unsigned, serve-fresh claims. Nothing
+ * here grants admission: the caller must still apply its existing scope and
+ * the receiver must still enforce OriginClaim and target-level membership.
+ *
+ * @module src/peer-directory
+ */
+import { CANVAS_MEMBER_CAP, CANVAS_NAME_MAX, CANVAS_TEAM_CAP } from "./canvas-store.js";
+/** Only this card's own valid canvas namespace may name its teams. */
+export function advertisedCanvasTeams(card) {
+    const found = [];
+    const seen = new Set();
+    for (const entry of (card.canvasOrg ?? []).slice(0, CANVAS_TEAM_CAP)) {
+        const name = entry.name;
+        if (name === '' || name !== name.trim() || name.length > CANVAS_NAME_MAX || name.includes('/') || /^\d+$/.test(name))
+            continue;
+        if (entry.team !== card.team + '/canvas/' + name || entry.members.length > CANVAS_MEMBER_CAP)
+            continue;
+        if (seen.has(entry.team))
+            continue;
+        seen.add(entry.team);
+        found.push(entry);
+    }
+    return found;
+}
+/** A nested zone may itself end in /canvas; preserve its own session alias. */
+function sessionAliasAllowed(card, team) {
+    if (!/^.+\/canvas\/[^/]+$/.test(team))
+        return true;
+    const prefix = card.team + '/';
+    const suffix = team.startsWith(prefix) ? team.slice(prefix.length) : '';
+    return suffix !== '' && !suffix.includes('/');
+}
+/** Match a session claim without treating another zone's canvas as a session. */
+export function sessionCandidateMatches(card, team) {
+    return sessionAliasAllowed(card, team) && (card.sessionTeams ?? []).some(entry => entry.team === team);
+}
+/** A member the publisher also serves as its own session is not ours. */
+function peerPublishesSession(card, handle) {
+    return (card.sessionTeams ?? []).some(entry => entry.team === handle);
+}
+/** Match a scoped caller to this peer's canvas before sending the payload. */
+export function canvasCandidateMatches(card, team, caller, resolveLocal) {
+    if (caller !== undefined && (resolveLocal?.(caller.handle) !== caller.id || peerPublishesSession(card, caller.handle)))
+        return false;
+    return advertisedCanvasTeams(card).some(entry => entry.team === team && (caller === undefined || entry.members.includes(caller.handle)));
+}
+/** A naked team string is unsafe when both a canvas and another face claim it. */
+export function canvasTargetAmbiguous(cards, team, caller, resolveLocal, hasDelegation) {
+    const owners = cards.filter((card) => card !== undefined && advertisedCanvasTeams(card).some(entry => entry.team === team));
+    if (owners.length === 0)
+        return false;
+    if (caller !== undefined) {
+        if (resolveLocal?.(caller.handle) !== caller.id)
+            return true;
+        const ownerCollision = owners.some(card => peerPublishesSession(card, caller.handle)
+            && advertisedCanvasTeams(card).some(entry => entry.team === team && entry.members.includes(caller.handle)));
+        if (ownerCollision)
+            return true;
+    }
+    // Distinct signed publishers with the same qualified group name cannot be
+    // selected by the team-only API. URL aliases of one signed card are one.
+    const eligible = owners.filter(card => canvasCandidateMatches(card, team, caller, resolveLocal));
+    const identities = new Set(eligible.map(card => JSON.stringify([card.publicKey, card.session])));
+    return identities.size > 1 || hasDelegation || cards.some(card => card !== undefined && (card.team === team || sessionCandidateMatches(card, team)));
+}
+/**
+ * Existing peer rows plus optional canvas rows for the model-tool directory.
+ * The GUI's remote-node rows call with includeCanvas=false, so a group is
+ * never rendered as an extra session node. Membership is carried only as an
+ * internal scope hint and stripped before the tool's public result.
+ */
+export function peerDirectoryRows(card, peer, includeCanvas) {
+    // The origin fields (publisher session label + LAN IP) are natural
+    // grouping dimensions: a fleet's rows cluster by the host that owns
+    // them, no manual grouping required.
+    const origin = card.lanIp !== undefined ? card.session + ' (' + card.lanIp + ')' : card.session;
+    // via = the peer URL the card was fetched from: the panel shows which
+    // host:port each remote row came from, so an unknown node is traceable
+    // to its publishing endpoint at a glance.
+    // legacy: the publisher's card carries no roster capability — a
+    // pre-roster node (0.5.43-). Rows from it are marked so the fleet
+    // audit (and the phase-2 teamed-only default flip) knows which peers
+    // never grow the roster face.
+    const legacy = card.capabilities?.roster !== true;
+    const rows = [
+        { team: card.team, session: card.session, name: card.name, description: '', origin, via: peer, ...(legacy ? { legacy } : {}) },
+    ];
+    // Roster reader half: the card's unsigned teamMemberships map each
+    // published session team to its declared roster teams, so a remote
+    // node's teamed/teamless state is visible without visiting its host.
+    const rosterOf = new Map();
+    for (const membership of card.teamMemberships ?? []) {
+        const list = rosterOf.get(membership.node) ?? [];
+        list.push(membership.team);
+        rosterOf.set(membership.node, list);
+    }
+    for (const entry of card.sessionTeams ?? []) {
+        // A foreign canvas-shaped claim cannot masquerade as a session. A valid
+        // own-zone session stays visible even if its zone ends in /canvas.
+        if (!sessionAliasAllowed(card, entry.team))
+            continue;
+        const declared = rosterOf.get(entry.team);
+        rows.push({ team: entry.team, session: card.session, name: entry.name, description: entry.description, origin, via: peer, ...(entry.workspace !== undefined ? { workspace: entry.workspace } : {}), ...(legacy ? { legacy } : {}), ...(declared !== undefined && declared.length > 0 ? { teams: declared } : {}) });
+    }
+    const publishedSessions = new Set((card.sessionTeams ?? []).map(entry => entry.team));
+    if (includeCanvas)
+        for (const entry of advertisedCanvasTeams(card)) {
+            const declared = rosterOf.get(entry.team);
+            rows.push({ team: entry.team, session: card.session, name: entry.name, description: 'canvas team', origin, via: peer, ...(legacy ? { legacy } : {}), ...(declared !== undefined && declared.length > 0 ? { teams: declared } : {}), canvasMembers: entry.members.filter(ref => !publishedSessions.has(ref)) });
+        }
+    return rows;
+}
+/**
+ * Whether one caller label can receive network traffic back. Composite
+ * `<zone>/<id>` shapes route anywhere (N1); bare zone names resolve to a
+ * live initiator per host, so cross-host they would steer whichever node
+ * shares the name — treated as unroutable everywhere.
+ */
+export function routableCallerLabel(callerSession) {
+    return callerSession !== undefined &&
+        (/[a-z0-9-]+\/[0-9a-f]{8}$/i.test(callerSession) || /[a-z0-9-]+\/[a-z0-9]{4,}$/i.test(callerSession));
+}
+/**
+ * Why an async route from such a caller cannot expect its receipt: the
+ * autosend arm skips it and the steered hint is omitted, so the debt has
+ * no paying path — say so at dispatch time instead of silently stranding
+ * a pending row.
+ */
+export function unroutableCallerNote(label) {
+    return `\n(Note: caller label "${label}" is not network-routable, so the target cannot auto-send a receipt back to you — reconcile via context_id follow-ups instead.)`;
+}

package/lib/receipt.js

@@ -11,6 +11,23 @@
  * open with a brace can never be mistaken for machine payloads.
  * @module @nelsonlongxiang/dsh-open-a2a-net/receipt
  */
+/**
+ * #114 S5: what a task id may not contain. The id is spliced into the
+ * `[A2A direct] (task <id>)` steer header and the `[A2A receipt] task <id>`
+ * correlation header; a `)` would let one id's header start with another's
+ * (`foo) x` → `(task foo) x)`), and whitespace or control characters break
+ * the `\S+` correlation and the header's one-line shape.
+ */
+const TASK_ID_FORBIDDEN = /[\s)\u0000-\u001f\u007f]/;
+/**
+ * Refusal text for an unusable task id, or undefined when the id is fine.
+ * Both delivery paths (wire face, local candidate) refuse at intake.
+ */
+export function taskIdRefusal(taskId) {
+    return TASK_ID_FORBIDDEN.test(taskId)
+        ? 'task_id must not contain whitespace, ")" or control characters — it is spliced into the [A2A direct] (task <id>) and [A2A receipt] task <id> headers'
+        : undefined;
+}
 /** The network's fixed, case-sensitive correlation template. */
 export const RECEIPT_PATTERN = /^\[A2A receipt\] task (\S+)\s*([\s\S]*)$/;
 /** Controlled outcome vocabulary — the ONLY branchable field of an envelope. */
@@ -23,7 +40,7 @@ export const RECEIPT_OUTCOMES = [
     'sync_completed',
     'unknown',
 ];
-const KNOWN_ENVELOPE_KEYS = ['outcome', 'idempotencyKey', 'sessionKey', 'elapsedMs', 'artifacts'];
+const KNOWN_ENVELOPE_KEYS = ['outcome', 'idempotencyKey', 'sessionKey', 'elapsedMs', 'artifacts', 'onBehalfOf', 'authRef'];
 void KNOWN_ENVELOPE_KEYS;
 function tryEnvelopeLine(line) {
     const trimmed = line.trim();
@@ -46,6 +63,10 @@ function tryEnvelopeLine(line) {
             fields.sessionKey = record['sessionKey'];
         if (typeof record['elapsedMs'] === 'number' && Number.isFinite(record['elapsedMs']))
             fields.elapsedMs = record['elapsedMs'];
+        if (typeof record['onBehalfOf'] === 'string' && record['onBehalfOf'] !== '')
+            fields.onBehalfOf = record['onBehalfOf'];
+        if (typeof record['authRef'] === 'string' && /^[0-9a-f]{16}$/.test(record['authRef']))
+            fields.authRef = record['authRef'];
         if (Object.keys(fields).length === 0)
             return undefined;
         return fields;
@@ -95,6 +116,10 @@ export function formatReceipt(taskId, summary, fields) {
         ordered['sessionKey'] = fields.sessionKey;
     if (fields.elapsedMs !== undefined)
         ordered['elapsedMs'] = fields.elapsedMs;
+    if (fields.onBehalfOf !== undefined)
+        ordered['onBehalfOf'] = fields.onBehalfOf;
+    if (fields.authRef !== undefined)
+        ordered['authRef'] = fields.authRef;
     const keys = Object.keys(ordered);
     if (keys.length === 0)
         return header;

package/lib/skill/SKILL.md

@@ -112,4 +112,6 @@ renders the same data for humans.
 - [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, release tiers, stuck gates, credentials, receipts
+- [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

package/lib/skill/references/cli.md

@@ -28,6 +28,11 @@ ten model tools.
   its card is no longer served, but it stays in the host's directory as an
   OFFLINE row (gh#47; the newest 16 are kept) so canvas refs to it never
   dangle silently. Publish again (same handle, same key) to come back.
+- A handle stays pinned to the key it was published with, live or offline
+  (gh#137): publishing it with a different key (e.g. after `init --force
+  --uuid <same>`) is refused with "held by another key". Run `a2a-net revoke`
+  first; the next publish then takes the new key. A key swap is therefore
+  always an explicit act, never a silent overwrite.
 - While deposited, the host serves the card at
   `<home>/a2a/cli/<handle>/.well-known/agent-card.json` and lists the handle
   in its directory as "cli — deposited identity (no wake; mailbox)".
@@ -37,16 +42,75 @@ ten model tools.
   405 with an empty body. The fix is a host upgrade, not a retry.
 - `a2a-net revoke` deregisters early.
 
+## Files (#91 file channel)
+
+- `a2a-net file send <path…> <team> [--note TEXT]` stages each file (≤64 MiB,
+  ≤16 per send) on the home host by sha256, granted to `<team>` for 24h, and
+  routes ONE message with one `[A2A file] v1 sha256=… size=… name=… from=<home>`
+  line per file. File bytes never ride a message.
+- `a2a-net file fetch "<reference line>" [--out DIR]` pulls a referenced file,
+  checks its size and sha256, and saves it as `<sha12>-<name>` (no links
+  followed, no overwrite of other content). A CLI identity proves itself only
+  on its HOME host, so only files whose `from` is the home host can be fetched;
+  for a file on another host, ask the sender to send it through your home host.
+- Sessions use the `a2a_file_send` / `a2a_file_fetch` tools for the same thing.
+
 ## Sending
 
 - `a2a-net route <team> <message…>` delivers a round with a signed
   OriginClaim envelope to the HOME host's `/a2a/direct`. It is async by
   default: the receipt comes back to `a2a-net inbox`.
+- The envelope (`X-A2A-Caller`, `X-A2A-Caller-Url`, `X-A2A-Caller-Ts`,
+  `X-A2A-Caller-Sig`) is signed with the identity key, over the identity's
+  deposit face on the home host. It also carries the bound form
+  (`X-A2A-Caller-Aud`, `X-A2A-Caller-Sig2`, docs/protocol/delivery-origin-auth.md
+  §2.1): a signature over the origin, method and path the CLI actually
+  dials, so it is good only at that host's `/a2a/direct`. A host with gh#133 verifies it on the
+  delivery face, from its own deposit table (it never dials the CLI's
+  address back, so a proxy or tailnet address is fine): the delivery's
+  authorization record says `proof: cli-identity` with the full handle as
+  the locally deposited identity; it is not market-origin proof and does not
+  count as an absent-envelope legacy delivery.
+- An older host refuses the envelope as `not-derivable`. The CLI says so on
+  stderr and resends the same task id once unsigned, the way earlier CLIs
+  always sent (accepted only while the host's OriginClaim window is open).
+- Dialling the home through an address the host does not list as its own
+  (a Tailscale address, a card-proxy port such as 13080, a pocket tunnel)
+  makes the bound form miss. While the host's `originClaimUnboundWindow` is
+  open the route still lands and the miss shows only on the host, in
+  `boundMissInbound`; `a2a-net status` prints that gauge beside the address
+  the CLI dials. Once the window is closed the route is refused as
+  `wrong-audience`: stderr names the dialled origin and the fix — the host
+  operator adds it to `originClaimAudiences`, or `--home` / `$A2A_HOME`
+  points at an address the host lists. A proxy that rewrites the path
+  (`<home>` with a path prefix) fails the same way as `bad-sig`. These
+  refusals are never resent unsigned. A redirect from the home is never
+  followed either, on any command (the API key, pocket cookie and claim
+  would travel with it): the command fails naming the status and
+  `Location`, and a route is not resent.
+- An identity may not be named after the host's zone (the deposit is refused).
 - `--sync` waits for the target's reply and prints it:
   `reply from <team> · task <id> · context <ctx>` followed by the reply text.
   When the round has not settled (status other than completed) a warning
   goes to stderr: reconcile by task id before re-sending.
 - `--context ID` continues that conversation (sends it as `context_id`).
+- Every route and report carries a task id born in the CLI
+  (`direct-<12 hex>`). The host runs one task id at most once (same id and
+  same message: 409 replay; different message: 409 conflict). Resending is
+  therefore safe:
+  - A dropped connection or a 5xx is resent automatically, up to 3 times,
+    with the SAME id (backoff 1s, 2s, 4s).
+  - If it still fails, stderr names the id: rerun with `--task <id>` to
+    resend it without risking a second execution.
+  - A resend the host already has prints `already received … — not sent a
+    second time` with the earlier outcome from `/a2a/query`: `pending` (an
+    async delivery waiting for its receipt) or `completed` (with its reply).
+    If that earlier attempt failed, the CLI exits 1 with its reason.
+  - A `--sync` resend whose round has no reply yet exits 1: rerun later
+    with `--task <id> --sync` to fetch the reply.
+  - Reusing an id for a different message, or switching `--sync` on or off,
+    is refused (exit 1): drop `--task` to send it as a new task.
+  - `report` takes `--task` the same way.
 - Direct delivery does not relay: only teams on the home host are reachable.
   A team on another host answers "No live DSH session node accepts team".
 - Admission: a deposited handle is a node fact of its home host (N3). It
@@ -61,12 +125,27 @@ ten model tools.
 
 - Deliveries addressed to a deposited handle, receipts included, land in its
   mailbox on the home host and answer `receipt: "mailbox"`. Entries are
-  `{at, from, text}` (text ≤4000 chars), newest first, 64 kept. A read does
-  not remove anything.
+  `{at, from, text, seq}`, newest first, 64 kept. A read does not remove
+  anything.
+- `seq` numbers a handle's mail 1, 2, 3 … in arrival order. It is never
+  reused and survives restarts. The read also carries `epoch`; `next_seq`;
+  `oldest_seq`; and `dropped`, the count of mail the 64-row cap pushed out.
+  `epoch` changes whenever seq numbers could repeat: the store starts empty,
+  its snapshot is unreadable or renumbered, or a write to disk failed (the
+  next restart would reload older numbers).
+- Text over 4000 chars is cut and marked `truncated: true, chars: <original>`.
+- The host's state face totals both losses for every handle as
+  `cliMailbox: {dropped, truncated}`.
 - `a2a-net inbox` lists the whole mailbox.
 - `inbox --new [--peek]` shows unread mail, oldest first. "Unread" is a local
   cursor (`$A2A_CLI_HOME/inbox.cursor`, tied to the handle) that advances
-  unless `--peek`.
+  unless `--peek`. On a host with `seq` the cursor is the last seq read:
+  - Mail the cap pushed out before you read it is reported once, by
+    `--new`, `--wait` and `--hook` alike (stderr, or inside the hook frame):
+    `N messages were pushed out of the mailbox before they were read`. It
+    cannot be recovered; tell the user.
+  - On an older host, or after the store starts over (a new `epoch`), the
+    cursor falls back to the newest `at` seen.
 - `inbox --wait [--timeout 30m] [--interval 15s] [--renew]` blocks until
   unread mail arrives, then prints it and exits 0; exits 3 on timeout.
   `--renew` re-publishes the deposit when it is gone or under 10 minutes from