@nelsonlongxiang/dsh-open-a2a-net 0.7.0 → 0.8.1-preview.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +109 -94
  3. package/README_zh.md +64 -66
  4. package/THIRD_PARTY_NOTICES.md +12 -0
  5. package/assets/nexusDist/assets/index-BuidhKVr.css +1 -0
  6. package/assets/nexusDist/assets/index-YtYrkDJi.js +9 -0
  7. package/assets/nexusDist/index.html +2 -2
  8. package/cli/a2a.mjs +349 -20
  9. package/cordis.patch.yml +167 -0
  10. package/docs/licenses/dsh-superagent-MIT.txt +21 -0
  11. package/lib/a2a-client.js +12 -4
  12. package/lib/card.js +2 -0
  13. package/lib/cli-deposit.js +75 -4
  14. package/lib/config.js +1 -2
  15. package/lib/direct-forward.js +23 -1
  16. package/lib/faces/admin.js +31 -48
  17. package/lib/faces/wire.js +110 -71
  18. package/lib/followup-admission.js +47 -0
  19. package/lib/followup-delivery.js +19 -2
  20. package/lib/index.js +618 -389
  21. package/lib/node-self.js +1 -1
  22. package/lib/outbound-scope.js +10 -0
  23. package/lib/peer-directory.js +3 -1
  24. package/lib/queue-guard.js +1 -1
  25. package/lib/receipt.js +24 -2
  26. package/lib/skill/SKILL.md +1 -0
  27. package/lib/skill/references/cli.md +193 -21
  28. package/lib/skill/references/collaboration.md +3 -2
  29. package/lib/skill/references/superagent.md +106 -0
  30. package/lib/superagent/a2a-watch.js +587 -0
  31. package/lib/superagent/contract.js +1 -0
  32. package/lib/superagent/host/a2a-source.js +251 -0
  33. package/lib/superagent/host/executor.js +520 -0
  34. package/lib/superagent/host/index.js +1107 -0
  35. package/lib/superagent/host/policy.js +308 -0
  36. package/lib/superagent/host/pr-follow.js +158 -0
  37. package/lib/superagent/host/review-requests.js +77 -0
  38. package/lib/superagent/host/role-tools.js +137 -0
  39. package/lib/superagent/host/store.js +136 -0
  40. package/lib/superagent/host/tools.js +297 -0
  41. package/lib/superagent/source-types.js +22 -0
  42. package/lib/superagent/upstream/dsh-superagent/src/core/assignments.js +160 -0
  43. package/lib/superagent/upstream/dsh-superagent/src/core/engine.js +244 -0
  44. package/lib/superagent/upstream/dsh-superagent/src/core/errors.js +63 -0
  45. package/lib/superagent/upstream/dsh-superagent/src/core/evals.js +381 -0
  46. package/lib/superagent/upstream/dsh-superagent/src/core/ids.js +5 -0
  47. package/lib/superagent/upstream/dsh-superagent/src/core/index.js +9 -0
  48. package/lib/superagent/upstream/dsh-superagent/src/core/intake.js +68 -0
  49. package/lib/superagent/upstream/dsh-superagent/src/core/memory.js +51 -0
  50. package/lib/superagent/upstream/dsh-superagent/src/core/model.js +79 -0
  51. package/lib/superagent/upstream/dsh-superagent/src/core/part.js +71 -0
  52. package/lib/superagent/upstream/dsh-superagent/src/core/ports.js +1 -0
  53. package/lib/superagent/upstream/dsh-superagent/src/core/reasons.js +35 -0
  54. package/lib/superagent/upstream/dsh-superagent/src/core/replies.js +94 -0
  55. package/lib/superagent/upstream/dsh-superagent/src/core/stage.js +27 -0
  56. package/lib/superagent/upstream/dsh-superagent/src/core/tickets.js +487 -0
  57. package/lib/superagent/upstream/snapshot-8c32a9d.js +62 -0
  58. package/lib/task-auth.js +21 -0
  59. package/lib/task-ledger-rows.js +4 -0
  60. package/lib/task-ledger.js +69 -3
  61. package/lib/tools/info.js +13 -7
  62. package/lib/types/a2a-client.d.ts +0 -7
  63. package/lib/types/cli-deposit.d.ts +65 -1
  64. package/lib/types/config.d.ts +6 -20
  65. package/lib/types/direct-forward.d.ts +14 -0
  66. package/lib/types/faces/admin.d.ts +5 -0
  67. package/lib/types/faces/wire.d.ts +20 -57
  68. package/lib/types/followup-admission.d.ts +13 -0
  69. package/lib/types/followup-delivery.d.ts +1 -1
  70. package/lib/types/index.d.ts +0 -2
  71. package/lib/types/outbound-scope.d.ts +1 -0
  72. package/lib/types/queue-guard.d.ts +2 -0
  73. package/lib/types/receipt.d.ts +21 -1
  74. package/lib/types/superagent/a2a-watch.d.ts +227 -0
  75. package/lib/types/superagent/contract.d.ts +36 -0
  76. package/lib/types/superagent/host/a2a-source.d.ts +90 -0
  77. package/lib/types/superagent/host/executor.d.ts +132 -0
  78. package/lib/types/superagent/host/index.d.ts +340 -0
  79. package/lib/types/superagent/host/policy.d.ts +128 -0
  80. package/lib/types/superagent/host/pr-follow.d.ts +51 -0
  81. package/lib/types/superagent/host/review-requests.d.ts +36 -0
  82. package/lib/types/superagent/host/role-tools.d.ts +85 -0
  83. package/lib/types/superagent/host/store.d.ts +61 -0
  84. package/lib/types/superagent/host/tools.d.ts +32 -0
  85. package/lib/types/superagent/source-types.d.ts +218 -0
  86. package/lib/types/superagent/upstream/dsh-superagent/src/core/assignments.d.ts +53 -0
  87. package/lib/types/superagent/upstream/dsh-superagent/src/core/engine.d.ts +191 -0
  88. package/lib/types/superagent/upstream/dsh-superagent/src/core/errors.d.ts +58 -0
  89. package/lib/types/superagent/upstream/dsh-superagent/src/core/evals.d.ts +99 -0
  90. package/lib/types/superagent/upstream/dsh-superagent/src/core/ids.d.ts +1 -0
  91. package/lib/types/superagent/upstream/dsh-superagent/src/core/index.d.ts +9 -0
  92. package/lib/types/superagent/upstream/dsh-superagent/src/core/intake.d.ts +15 -0
  93. package/lib/types/superagent/upstream/dsh-superagent/src/core/memory.d.ts +40 -0
  94. package/lib/types/superagent/upstream/dsh-superagent/src/core/model.d.ts +432 -0
  95. package/lib/types/superagent/upstream/dsh-superagent/src/core/part.d.ts +49 -0
  96. package/lib/types/superagent/upstream/dsh-superagent/src/core/ports.d.ts +217 -0
  97. package/lib/types/superagent/upstream/dsh-superagent/src/core/reasons.d.ts +36 -0
  98. package/lib/types/superagent/upstream/dsh-superagent/src/core/replies.d.ts +55 -0
  99. package/lib/types/superagent/upstream/dsh-superagent/src/core/stage.d.ts +18 -0
  100. package/lib/types/superagent/upstream/dsh-superagent/src/core/tickets.d.ts +151 -0
  101. package/lib/types/superagent/upstream/snapshot-8c32a9d.d.ts +317 -0
  102. package/lib/types/task-auth.d.ts +9 -0
  103. package/lib/types/task-ledger-rows.d.ts +21 -4
  104. package/lib/types/task-ledger.d.ts +9 -0
  105. package/lib/types/types.d.ts +7 -4
  106. package/nexus-stage/scripts/mockhost.py +2 -2
  107. package/nexus-stage/src/main.ts +27 -0
  108. package/nexus-stage/src/planning-card-text.ts +1 -1
  109. package/nexus-stage/src/planning-team-roles.ts +80 -0
  110. package/nexus-stage/src/planning-types.ts +2 -0
  111. package/nexus-stage/src/planning-view.ts +1 -0
  112. package/nexus-stage/src/planning.css +29 -9
  113. package/nexus-stage/src/wb-superagent.ts +518 -0
  114. package/nexus-stage/src/workbench.css +32 -0
  115. package/nexus-stage/src/workbench.ts +25 -3
  116. package/nexus-stage/src/world.ts +1 -1
  117. package/package.json +8 -2
  118. package/assets/nexusDist/assets/index-C7HagaGy.css +0 -1
  119. package/assets/nexusDist/assets/index-CA_YZTWG.js +0 -9
  120. package/assets/stageDist/assets/index-Bj7S2pA1.css +0 -1
  121. package/assets/stageDist/assets/index-C-28k_o5.js +0 -974
  122. package/assets/stageDist/assets/interiors-CQGBjffT.png +0 -0
  123. package/assets/stageDist/assets/office-tileset-CHQT-uYL.png +0 -0
  124. package/assets/stageDist/index.html +0 -13
  125. package/lib/legacy/teams-bridge-inbound.js +0 -156
  126. package/lib/teams-bridge.js +0 -18
  127. package/lib/types/legacy/teams-bridge-inbound.d.ts +0 -94
  128. package/lib/types/teams-bridge.d.ts +0 -112
package/lib/node-self.js CHANGED
@@ -171,7 +171,7 @@ export function sessionSource(events, others = { tainted: () => false, local: ()
171
171
  if (field !== undefined) {
172
172
  // Another session's text: its taint becomes ours (persisted); a clean one is neutral. A subagent is
173
173
  // always this host's; a peer agent or a reference must be a session this host knows, else this
174
- // call is refused (a native-teams bridge could name a remote caller here).
174
+ // call is refused (a caller could name a remote session here).
175
175
  // A session reference names its sessions in references[].sessionId (the installed shape); the others name one.
176
176
  const named = kind === 'session-reference' && Array.isArray(source?.references)
177
177
  ? source.references.map(r => r?.sessionId)
@@ -10,15 +10,25 @@ export async function outboundScope(r, id, handle, team) {
10
10
  if (team.includes('/canvas/') && !sharedCanvas && !teams.includes(team))
11
11
  await r.warmPeers();
12
12
  let orgShared = false;
13
+ // Design v5 (v5-B2): a peer's superagent team canvas, named bare or with its owner's fingerprint.
14
+ let openTeam = false;
15
+ const bareTarget = team.replace(/@[0-9a-f]{8}$/, '');
13
16
  for (const org of r.peerOrgs())
14
17
  for (const row of org) {
15
18
  if (typeof row.team !== 'string' || row.team === '' || !Array.isArray(row.members))
16
19
  continue;
20
+ if (row.superagentTeam === true && row.team === bareTarget)
21
+ openTeam = true;
17
22
  if ((row.members.includes(id) || row.members.includes(handle)) && (row.members.includes(team) || row.team === team)) {
18
23
  orgShared = true;
19
24
  break;
20
25
  }
21
26
  }
27
+ // A session that declares a team — a roster team or any canvas seat — may request a peer's superagent team; a
28
+ // teamless one still has no network (S3).
29
+ const declared = teams.length > 0 || r.canvasNames().some(name => r.canvasMembers(name).some(ref => ref === id || ref === handle || r.memberHandle?.(ref) === handle));
30
+ if (openTeam && declared)
31
+ return { ok: true };
22
32
  if (teams.length === 0 && !sharedRoster && !sharedCanvas && !orgShared)
23
33
  return { ok: false, error: `team-scoped routing is on and this session (${r.id8(id)}) has declared no team membership — a teamless node has no network. Declare one with a2a_team_join (subject to the owner's teamJoinAllowlist)` };
24
34
  if (!teams.includes(team) && !sharedRoster && !sharedCanvas && !orgShared)
@@ -47,7 +47,9 @@ export function canvasCandidateMatches(card, team, caller, resolveLocal) {
47
47
  return advertisedCanvasTeams(card).some(entry => {
48
48
  if (entry.team !== team)
49
49
  return false;
50
- if (caller === undefined)
50
+ // Design v5 (v5-B2): a superagent team canvas takes requests from callers that sit in no seat of it; the
51
+ // publisher's own admission (links, then the team's Policy) decides, as for any route to its mailboxes.
52
+ if (caller === undefined || entry.superagentTeam === true)
51
53
  return true;
52
54
  return entry.members.some(ref => {
53
55
  const qualified = splitQualifiedMember(ref);
@@ -3,7 +3,7 @@ export const WIRE_ERROR_QUEUE_FULL = -32009;
3
3
  export const DEFAULT_TARGET_QUEUE_CAP = 3;
4
4
  /** How many receipt-owing tasks this host holds pending and unanswered for `team`. */
5
5
  export function queuedFor(rows, team) {
6
- return rows.filter(row => row.status === 'pending' && row.receiptExpected !== false && row.answeredAt === undefined &&
6
+ return rows.filter(row => row.status === 'pending' && row.receiptExpected !== false && row.answeredAt === undefined && row.acknowledgedAt === undefined &&
7
7
  (row.direction === 'inbound' || row.peer === 'local') &&
8
8
  (row.team === team || row.deliveredTo === team)).length;
9
9
  }
package/lib/receipt.js CHANGED
@@ -30,7 +30,10 @@ export function taskIdRefusal(taskId) {
30
30
  }
31
31
  /** The network's fixed, case-sensitive correlation template. */
32
32
  export const RECEIPT_PATTERN = /^\[A2A receipt\] task (\S+)\s*([\s\S]*)$/;
33
- /** Controlled outcome vocabulary — the ONLY branchable field of an envelope. */
33
+ /**
34
+ * Controlled outcome vocabulary — how the work ended. One of the envelope's two
35
+ * branchable fields; {@link RECEIPT_DISPOSITIONS} is the other.
36
+ */
34
37
  export const RECEIPT_OUTCOMES = [
35
38
  'completed',
36
39
  'failed',
@@ -40,7 +43,21 @@ export const RECEIPT_OUTCOMES = [
40
43
  'sync_completed',
41
44
  'unknown',
42
45
  ];
43
- const KNOWN_ENVELOPE_KEYS = ['outcome', 'idempotencyKey', 'sessionKey', 'elapsedMs', 'artifacts', 'onBehalfOf', 'authRef'];
46
+ /**
47
+ * superagent p1-receipt-cmd (S14): what the receipt hands back — the work's
48
+ * result, or a question that needs the caller's attention. A closed set; any
49
+ * other value is dropped. An attention receipt settles the task like any
50
+ * receipt but is not a completion (it carries no outcome); the answer comes
51
+ * back as a new task in the same context.
52
+ *
53
+ * `acknowledged` (superagent v4, requester acknowledgement): the target took the task up and will answer later — the
54
+ * caller's row stays owed (the result receipt settles it) but no longer counts against the queue cap or expires at the
55
+ * 24-hour TTL. It rides the receipt form so every hop treats it as settlement traffic (no debt of its own, never refused
56
+ * by a queue). A host that predates it drops the unknown value and settles the row on it; the result then arrives as a
57
+ * late receipt that updates the settled row's summary and outcome.
58
+ */
59
+ export const RECEIPT_DISPOSITIONS = ['result', 'attention', 'acknowledged'];
60
+ const KNOWN_ENVELOPE_KEYS = ['outcome', 'idempotencyKey', 'sessionKey', 'elapsedMs', 'artifacts', 'onBehalfOf', 'authRef', 'disposition'];
44
61
  void KNOWN_ENVELOPE_KEYS;
45
62
  function tryEnvelopeLine(line) {
46
63
  const trimmed = line.trim();
@@ -67,6 +84,9 @@ function tryEnvelopeLine(line) {
67
84
  fields.onBehalfOf = record['onBehalfOf'];
68
85
  if (typeof record['authRef'] === 'string' && /^[0-9a-f]{16}$/.test(record['authRef']))
69
86
  fields.authRef = record['authRef'];
87
+ if (typeof record['disposition'] === 'string' && RECEIPT_DISPOSITIONS.includes(record['disposition'])) {
88
+ fields.disposition = record['disposition'];
89
+ }
70
90
  if (Object.keys(fields).length === 0)
71
91
  return undefined;
72
92
  return fields;
@@ -120,6 +140,8 @@ export function formatReceipt(taskId, summary, fields) {
120
140
  ordered['onBehalfOf'] = fields.onBehalfOf;
121
141
  if (fields.authRef !== undefined)
122
142
  ordered['authRef'] = fields.authRef;
143
+ if (fields.disposition !== undefined)
144
+ ordered['disposition'] = fields.disposition;
123
145
  const keys = Object.keys(ordered);
124
146
  if (keys.length === 0)
125
147
  return header;
@@ -120,3 +120,4 @@ renders the same data for humans.
120
120
  - [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
121
121
  - [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
122
122
  - [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
123
+ - [superagent.md](references/superagent.md) — the superagent team (design v4, `superagent: true`): workbench Source, gate, the router's superagent_* tools and its A2A isolation, the owner control route
@@ -10,12 +10,19 @@ model tools.
10
10
  ## Identity and home host
11
11
 
12
12
  - `a2a-net init <name> [--uuid 16hex] [--home URL] [--force]` creates an
13
- Ed25519 identity: handle `<name>/<16 hex>`, stored in
14
- `$A2A_CLI_HOME/cli.json` (default `~/.a2a/cli.json`, mode 0600). An
15
- existing identity is never replaced without `--force` (the old handle's
16
- deposit stops verifying).
13
+ Ed25519 identity: handle `<name>/<16 hex>` (the name must match
14
+ `[a-z0-9-]{1,32}`, else a usage error, exit 2; the 16 hex is random unless
15
+ `--uuid` gives it), stored in `$A2A_CLI_HOME/cli.json` (default
16
+ `~/.a2a/cli.json`; the file is mode 0600). `--home` is saved with the
17
+ identity, a trailing `/` stripped. An existing identity is never replaced
18
+ without `--force`. `--force` writes a fresh identity file: a new key, a new
19
+ random uuid unless `--uuid` is given, and the saved home is dropped unless
20
+ `--home` is passed again. The old key is gone for good, so nothing can sign
21
+ for the old handle any more; its deposit stays on the home host until it
22
+ expires (4h at most).
17
23
  - Home host: `--home` > `$A2A_HOME` > the home saved by `init --home` >
18
- `http://127.0.0.1:3080`.
24
+ `http://127.0.0.1:3080`. An environment variable set to the empty string
25
+ counts as unset.
19
26
  - Keyed hosts: `--key` > `$A2A_KEY` (prefer the variable; a flag value stays
20
27
  in shell history). A host behind dsh-pocket also wants its session token as
21
28
  the `dsh_pocket_token` cookie: set `$A2A_POCKET_TOKEN` (or `$A2A_TOKEN`).
@@ -24,14 +31,29 @@ model tools.
24
31
 
25
32
  - `a2a-net publish` deposits the signed CLI card on the home host
26
33
  (`/__dsh_a2a/cli-deposit`, a control route: key-gated like every write).
27
- The deposit lives at most 4h. An expired deposit is no longer routable and
34
+ The deposit lives 4h from each publish (both the default and the maximum;
35
+ there is no flag to change it). An expired deposit is no longer routable and
28
36
  its card is no longer served, but it stays in the host's directory as an
29
37
  OFFLINE row (gh#47; the newest 16 are kept) so canvas refs to it never
30
38
  dangle silently. Publish again (same handle, same key) to come back.
39
+ - `a2a-net publish --owes` (superagent p1-mailbox-owes) declares in the
40
+ signed card that this identity owes a receipt for what its mailbox takes.
41
+ A home host that knows the declaration answers a delivery to it
42
+ `delivered` instead of final: the caller books a debt, the per-target cap
43
+ (`targetQueueCap`, default 3, `0` disables; counted per identity across all
44
+ callers) applies and refuses with
45
+ `-32009` when full, and the identity's own `receipt <task_id>` frees the
46
+ slot. An owed row the 64-row cap pushes out is archived as evicted. Every
47
+ publish states it afresh — `publish` or `inbox --renew` without `--owes`
48
+ withdraws it — so only an identity that does answer every task (the
49
+ superagent Source) should declare it. A host that predates it ignores the
50
+ field and keeps the mailbox final.
31
51
  - A handle stays pinned to the key it was published with, live or offline
32
52
  (gh#137): publishing it with a different key (e.g. after `init --force
33
53
  --uuid <same>`) is refused with "held by another key". Run `a2a-net revoke`
34
- first; the next publish then takes the new key. A key swap is therefore
54
+ first (it acts on the current identity's handle, so with the same `--uuid`
55
+ it removes the old deposit, live or offline); the next publish then takes
56
+ the new key. A key swap is therefore
35
57
  always an explicit act, never a silent overwrite.
36
58
  - While deposited, the host serves the card at
37
59
  `<home>/a2a/cli/<handle>/.well-known/agent-card.json` and lists the handle
@@ -44,13 +66,13 @@ model tools.
44
66
 
45
67
  ## Team display names
46
68
 
47
- Canvas rows in `a2a-net teams` carry an owner-qualified id, `<zone>/canvas/<name>@<fp8>` (the first 8 hex of sha256 over the owner card's public key; #282). Route to that id to pick one owner when several hosts have a canvas of the same name; a bare `<zone>/canvas/<name>` still routes as before (this host's own canvas first, refused as ambiguous when several remote owners match). Your own fingerprint names your own canvas; an id nobody's key matches reaches no one. The id survives a change of the owner's address. It names a signing key, not a host: a seeded peer serving that key's signed card core is treated as an alias of the same owner (as before), and a card's canvas list is not itself signed. Canvas names may not end in `@<8 hex>`.
69
+ Canvas rows in `a2a-net teams` carry an owner-qualified id, `<zone>/canvas/<name>@<fp8>` (the first 8 hex of sha256 over the owner card's public key; #282; a host that does not send an `id`, or an owner card without a key, shows the bare `<zone>/canvas/<name>`). Route to that id to pick one owner when several hosts have a canvas of the same name; a bare `<zone>/canvas/<name>` still routes as before (this host's own canvas first, refused as ambiguous when several remote owners match). Your own fingerprint names your own canvas; an id nobody's key matches reaches no one. The id survives a change of the owner's address. It names a signing key, not a host: a seeded peer serving that key's signed card core is treated as an alias of the same owner (as before), and a card's canvas list is not itself signed. Canvas names may not end in `@<8 hex>`.
48
70
 
49
- `a2a-net teams <query>` searches the owner-set seat label as well as the route handle; `--json` exposes the effective display name. Local rows prefer `seatName`, then the current title (`name`), then the legacy label. Only the human workbench owner panel/config can set `seatNames`; the CLI has no naming command.
71
+ `a2a-net teams <query>` is a case-insensitive substring search over the route handle and the display name (the owner-set seat label included); `--json` exposes the effective display name. Local rows prefer `seatName`, then the current title (`name`), then the legacy label. Only the human workbench owner panel/config can set `seatNames`; the CLI has no naming command.
50
72
 
51
73
  ## Tasks: ledger and host observability
52
74
 
53
- `a2a-net tasks --json` returns the existing `pending`, `dead`, and `archived` arrays plus `settlement` and `conservation` copied unchanged from `/__dsh_a2a/state`. These blocks include the lifetime `settlement.refusalsTotal`, refusal ring and mode, and the host conservation verdict/counters/duplicate ids. Older hosts omit a block they do not expose; the CLI does not manufacture zero counters or a passing verdict. Plain `tasks` appends a conservation line (`conserved`, `delta`) and a settlement line (`mode`, `refusalsTotal`, `offChain`) when the respective block exists.
75
+ `a2a-net tasks --json` returns the existing `pending`, `dead`, and `archived` arrays plus `settlement` and `conservation` copied unchanged from `/__dsh_a2a/state`. These blocks include the lifetime `settlement.refusalsTotal`, refusal ring and mode, and the host conservation verdict/counters/duplicate ids. Older hosts omit a block they do not expose; the CLI does not manufacture zero counters or a passing verdict. Plain `tasks` appends a conservation line (`conserved`, `delta`) and a settlement line (`mode`, `refusalsTotal`, `offChain`) when the respective block exists, and a further `enforce refused` line (reason and blockers) when the settlement block carries `enforceRefused`; plain lists cap at 20 rows per section.
54
76
 
55
77
  ## Files (#91 file channel)
56
78
 
@@ -59,12 +81,15 @@ Files do not go through session messages: use the file channel below, never JPFI
59
81
  - `a2a-net file send <path…> <team> [--note TEXT]` stages each file (≤64 MiB,
60
82
  ≤16 per send) on the home host by sha256, granted to `<team>` for 24h, and
61
83
  routes ONE message with one `[A2A file] v1 sha256=… size=… name=… from=<home>`
62
- line per file. File bytes never ride a message.
84
+ line per file (`--note`, when given, rides as the message's first line). File bytes never ride a message.
63
85
  - `a2a-net file fetch "<reference line>" [--out DIR]` pulls a referenced file,
64
86
  checks its size and sha256, and saves it as `<sha12>-<name>` (no links
65
87
  followed, no overwrite of other content). A CLI identity proves itself only
66
- on its HOME host, so only files whose `from` is the home host can be fetched;
67
- for a file on another host, ask the sender to send it through your home host.
88
+ on its HOME host, so only files whose `from` is the home host — or one of the
89
+ home's advertised aliases (`ownerHost` / `originClaimAudiences` from the state
90
+ face, #332) — can be fetched; the alias lookup asks only the configured home,
91
+ and old/denied/malformed/redirected metadata fails closed. For a file on any
92
+ other host, ask the sender to send it through your home host.
68
93
  - Sessions use the `a2a_file_send` / `a2a_file_fetch` tools for the same thing.
69
94
 
70
95
  ## Sending
@@ -114,7 +139,8 @@ Files do not go through session messages: use the file channel below, never JPFI
114
139
  same message: 409 replay; different message: 409 conflict). Resending is
115
140
  therefore safe:
116
141
  - A dropped connection or a 5xx is resent automatically, up to 3 times,
117
- with the SAME id (backoff 1s, 2s, 4s).
142
+ with the SAME id (backoff 1s, 2s, 4s; the 1s base is overridable with
143
+ `$A2A_RETRY_BASE_MS`).
118
144
  - If it still fails, stderr names the id: rerun with `--task <id>` to
119
145
  resend it without risking a second execution.
120
146
  - A resend the host already has prints `already received … — not sent a
@@ -132,11 +158,30 @@ Files do not go through session messages: use the file channel below, never JPFI
132
158
  - B signs its auto-receipt as the member that did the work. Its destination prefers an online CLI household on that host (an owner-controlled fact); otherwise it returns only to the pinned home, never another directory advertiser. In the normal single-home setup it settles A’s single forwarded outbound row on-chain under `enforce` and enters the CLI mailbox (`a2a-net inbox`). `--sync` returns B’s final reply. The transport still has a 15s synchronous patience window, not a full model-turn budget. For forwarded or long work, prefer `a2a-net route <team> <message>` (async by default) then `a2a-net inbox --wait --renew`. A `--sync` transport expiry is `-32005`; the target still auto-receipts the original task after finishing. Reconcile by task id/inbox instead of treating a new direct pong as its receipt or resending blindly.
133
159
  - With forwarding off or any prerequisite missing, the original "No live DSH session node accepts team" error includes the reason it was not forwarded. Receiving hosts never forward the forwarded request again.
134
160
  - Admission: a deposited handle is a node fact of its home host (N3); that fact alone grants no remote scope or admission. Operator canvas membership and B’s home pin are still required. Global self-description is never a link.
135
- - `a2a-net report <message…>` is a one-way report to the host's process team.
161
+ - `a2a-net report <message…>` is a one-way report to the host's process team
162
+ (addressed to the zone the home's state face names, `dsh` if it names none).
136
163
  - A message that starts with `-` goes after `--`. Flag values never become
137
164
  part of the message.
138
165
  - Async output is one line (`delivered → <team> · task <id> · <receipt>`);
139
- `--json` prints the raw reply.
166
+ delivery-uncertainty outcomes (acceptance `unknown`/`inserted`, receiver
167
+ bookkeeping failed, a sync wait released without a final reply) print a
168
+ reconciliation-hint line instead. `--json` prints the raw reply plus the
169
+ `class` field below.
170
+ - `route --json` adds an observation field `class`, judged from structured
171
+ fields only (HTTP status, `delivered`, `code`, `acceptance`, a sync
172
+ `result`, a replay's `prior`) and never from error text:
173
+ - `sent`: delivered, including `receiverBookkeeping: "failed"`,
174
+ `acceptance: "inserted"` and `-32005` (landed, not settled); also a replay
175
+ whose task the host already holds, unless it failed.
176
+ - `gone`: resending the same task can never succeed: `-32001` payload too
177
+ large, `-32002` the id is bound to a different message, or a replay whose
178
+ task already failed.
179
+ - `retry`: everything else, including `acceptance: "unknown"`, 401/403, 5xx,
180
+ `-32003/-32007/-32008/-32009/-32011` and generic `-32000`. Retry with the
181
+ SAME task id. A consumer counts retries and only drops (with a record)
182
+ past its own bound. No JSON at all (e.g. the network failed) also means
183
+ retry. `class` changes no host semantics, and no exit code by default; the opt-in
184
+ `--exit-class` switch (see the receipt section) makes the exit code carry it.
140
185
 
141
186
  ## Receiving: the mailbox
142
187
 
@@ -151,6 +196,21 @@ Files do not go through session messages: use the file channel below, never JPFI
151
196
  its snapshot is unreadable or renumbered, or a write to disk failed (the
152
197
  next restart would reload older numbers).
153
198
  - Text over 4000 chars is cut and marked `truncated: true, chars: <original>`.
199
+ - Rows mailed by a host from next/0.8 on also carry structured fields, so a
200
+ reader branches on fields and never parses the text:
201
+ - `task_id` and `context_id` of the delivery;
202
+ - `proof`, how the host proved the caller when it took the delivery. On
203
+ the wire face it is the same verdict the text header states:
204
+ `origin-claim` for 已验证来源, otherwise the value in 未验证(…), such as
205
+ `cli-identity`, `claim-mismatch` or `unbound`. A delivery from a session
206
+ on the home host itself is `in-process` and has no header;
207
+ - `receipt_for`, the task id a receipt row answers, and `disposition` when
208
+ its envelope carried one;
209
+ - `admission`, the admission rule the host matched when it took the
210
+ delivery (`canvas-shared`, `remote-ref-cli`, `cli-deposit`,
211
+ `local-exempt`, …) — the rule name only, never which canvas or team.
212
+ Older rows carry none of these. Which `proof` values a consumer trusts is
213
+ that consumer's decision (the superagent Source takes it from its design).
154
214
  - The host's state face totals both losses for every handle as
155
215
  `cliMailbox: {dropped, truncated}`.
156
216
  - `a2a-net inbox` lists the whole mailbox.
@@ -164,8 +224,103 @@ Files do not go through session messages: use the file channel below, never JPFI
164
224
  cannot be recovered; tell the user.
165
225
  - On an older host, or after the store starts over (a new `epoch`), the
166
226
  cursor falls back to the newest `at` seen.
227
+ - `inbox --after <cursor>` is a replayable read for a consumer that keeps its
228
+ own position, such as a superagent a2a Source. Start with `start`, then pass
229
+ back the `next` you received. It prints one JSON object
230
+ `{handle, epoch, after, next, mail, lost, epochChanged}` with `mail` oldest
231
+ first, and never reads or moves the local `inbox.cursor`:
232
+ - `lost` counts mail the cap pushed out before this window. It is `null`,
233
+ meaning unknown, when the host's store restarted (`epochChanged: true`);
234
+ the read then returns every row it still has.
235
+ - A cursor past the newest seq the host issued is not one it handed out
236
+ (forged or mixed up). The read flags it with `cursorAhead: true`, returns
237
+ no mail, keeps `next` equal to the cursor, reports `lost: null` (unknown,
238
+ as across an epoch change), and warns on stderr.
239
+ - A consumer such as the superagent a2a Source reports a health error
240
+ whenever `lost > 0`, `lost` is `null`, or `cursorAhead` is set. Lost mail
241
+ cannot be recovered; the error makes the gap visible instead of hiding it.
242
+ - A host without `seq` is refused (exit 1); there is no time-based
243
+ fallback. `--after` does not combine with `--new`, `--peek`, `--wait` or
244
+ `--hook` (exit 2).
245
+ - `thread <context_id> [--limit N] [--before <cursor>]` reads one
246
+ conversation back, newest first, as one JSON object
247
+ `{handle, epoch, context_id, entries, more, next_before, unscoped, mail_lost}`
248
+ (superagent p1-context-read). It is read-only: it never reads or moves the
249
+ local `inbox.cursor`.
250
+ - Entries with `dir: "in"` are mailbox rows the home host tagged with that
251
+ `context_id` (`seq`, `from`, `task_id`, `text`, and `proof` /
252
+ `receipt_for` when the row has them). The host tags every
253
+ mailbox delivery from this version on; `unscoped` counts the rows that
254
+ carry no `context_id` (mailed by an older host) and cannot be placed.
255
+ - Entries with `dir: "out"` are this identity's own routes the host took
256
+ (`route --json` class `sent`), read from `sent.jsonl` in the identity
257
+ home: `team`, `task_id`, `text`, and `reply` when `--sync` got one. A route
258
+ is journaled under the context the host named in its reply, or the
259
+ explicit `--context`; a `-32005` reply names none, so only `--context`
260
+ covers it. Texts over 4000 characters are cut (`truncated`, `chars`). Past
261
+ 1 MiB the journal rolls into `sent.1.jsonl` (one older generation, read
262
+ too). The journal lives on this machine only; a failed journal write
263
+ warns on stderr and never fails the send.
264
+ - `--limit` is 1-200 (default 20). When `more` is true, pass `next_before`
265
+ back as `--before` for the next page. Within one millisecond the journal
266
+ side is newer than the mailbox side.
267
+ - `mail_lost` counts earlier mailbox rows the 64-row cap already pushed
268
+ off the host, whatever their context; they cannot be recovered.
269
+ - The two sides keep time on different machines: an `in` row's `at` is the
270
+ home host's clock, an `out` row's `at` is this machine's. When the CLI
271
+ talks to a home on another machine whose clock is off, the two sides can
272
+ interleave in the wrong order. Paging stays complete either way.
273
+ - `receipt <task_id> [--attention | --acknowledged | --outcome O] [--to TEAM] <one line…>` is the one formal
274
+ receipt for a task this identity received:
275
+ - It sends `[A2A receipt] task <task_id> <one line>` plus the v2 envelope
276
+ line. The default is a result,
277
+ `{"outcome":"completed","idempotencyKey":<id>,"disposition":"result"}`.
278
+ `--outcome` says how the work ended instead: `failed`, `rejected`
279
+ (declined, never taken up) or `abandoned` (stopped before it finished);
280
+ `completed` is the default. Any other value, or `--outcome` together with
281
+ `--attention`, exits 2 and sends nothing; `expired`, `sync_completed` and
282
+ `unknown` are outcomes the host derives, not ones a sender claims.
283
+ With `--attention` it is a question for the caller,
284
+ `{"idempotencyKey":<id>,"disposition":"attention"}`, with no outcome:
285
+ it settles the task but is not a completion. The caller's answer comes
286
+ back as a new task in the same context.
287
+ - The target is the sender of that task's mailbox row; `--to` names one
288
+ when the mailbox has none (or several). With neither, it exits 2 and
289
+ sends nothing. The receipt rides the task's own `context_id`, so it also
290
+ shows in `thread`.
291
+ - It rides task id `receipt-<task_id>`. The host runs a task id once, so a
292
+ task gets one receipt: the same receipt again is a replay ("already
293
+ received"), and a different one, such as a result after an attention,
294
+ is refused (exit 1).
295
+ - The task id must be letters, digits, `.`, `_`, `:` or `-`, and at most
296
+ 72 characters, so `receipt-<task_id>` fits the 80-character task id. A
297
+ longer id exits 2; it is never cut short. The line is folded to one
298
+ line.
299
+ - `--json --exit-class` (on `route` and `receipt`) makes the exit code
300
+ carry the class too, for callers whose command runner keeps the exit
301
+ code and drops stdout (superagent's a2a Source): 0 sent (or the same
302
+ receipt replayed), 4 gone, 5 the task already carries a different receipt
303
+ (`receipt` only), 1 retry or any other failure. `--exit-class` without
304
+ `--json` exits 2. Without the switch no exit code changes.
305
+ - A task delivered into a CLI mailbox is final on the caller's side (no
306
+ debt is booked for it), so its receipt settles nothing there; the
307
+ caller still gets it, with `disposition` on its mailbox row. A receipt
308
+ settles a debt only where the caller tracked one.
309
+ - `--acknowledged` says the task is taken up and its result follows. It settles nothing: the caller's row stays owed until the result receipt, leaves the queue count, and expires 7 days after the acknowledgement instead of 24 hours after dispatch. It rides task id `ack-<task_id>`, so the later receipt is not refused.
310
+ - `admission <caller> [--local] [--json]` asks the home host how `<caller>`
311
+ would be admitted delivering to this identity right now, recomputed from the
312
+ host's current links: `{caller, admitted, rule}`. `--local` asks for the
313
+ same-host face (a session on the home host). The query is signed with this
314
+ identity's key, and the host answers only the identity itself — a holder of
315
+ the host key cannot ask about another identity's links — with the rule name
316
+ and nothing more. Exit 0 once answered (admitted or not), 1 when the host
317
+ refuses the query or predates it. A signed query stays valid for its
318
+ 5-minute window, so it can be replayed within it; that is accepted — the
319
+ answer is read-only, goes through the host's own control face, and is the
320
+ identity's own question.
167
321
  - `inbox --wait [--timeout 30m] [--interval 15s] [--renew]` blocks until
168
- unread mail arrives, then prints it and exits 0; exits 3 on timeout.
322
+ unread mail arrives (the interval also comes from `$A2A_POLL_MS` when
323
+ `--interval` is not given), then prints it and exits 0; exits 3 on timeout.
169
324
  `--renew` re-publishes the deposit when it is gone or under 10 minutes from
170
325
  expiry. Run as a background task, its exit is the wake signal.
171
326
  - `inbox --hook` serves a Claude Code hook (PostToolUse / UserPromptSubmit):
@@ -176,18 +331,31 @@ Files do not go through session messages: use the file channel below, never JPFI
176
331
 
177
332
  ## Reading the host
178
333
 
179
- If configured enforcement is refused because old forwarded canvas debts lack receiver facts, the plugin stays online in observe. `tasks --json` preserves `settlement.mode` and `settlement.enforceRefused:{reason,blockers}`; tasks/status text also shows the refusal. This boot-time audit remains after reconciliation; a later owner-controlled reapplication may enable enforce once blockers are cleared. Configuration on disk is unchanged.
334
+ If configured enforcement is refused because old forwarded canvas debts lack receiver facts, the plugin stays online in observe. `tasks --json` preserves `settlement.mode` and `settlement.enforceRefused:{reason,blockers}`; tasks/status text also shows the refusal. The audit runs once at boot, so the refusal remains after reconciliation
335
+ until the host restarts (a restart with the same config re-runs it and turns
336
+ enforce back on once the blockers are gone); configuration on disk is
337
+ unchanged — the downgrade to observe happens in memory only.
180
338
 
181
339
  `whoami`, `teams [query]`, `status`, `tasks`, `probe` read the home host's
182
340
  state face (key-gated on a keyed host). `--json` prints raw rows for
183
- `whoami`, `teams`, `tasks`, `probe`, `route`, `report`, `inbox` and `skills`.
341
+ `whoami`, `teams`, `status`, `tasks`, `probe`, `route`, `report`, `inbox` and
342
+ `skills`.
184
343
 
185
344
  `teams` includes local canvas and peerOrg rows with qualified route name, owner URL and memberCount; same names on different hosts stay separate. `whoami --json` is pure JSON and includes only canvases naming this CLI identity, local and remote. An unreadable optional state face reports canvasError/UNKNOWN, never falsely empty membership. Canvas failures retain the original refusal and add visible-directory not-found, owner prerequisites (including each missing direct receiver link), or conflicting owner candidates. Owner URLs do not require direct dialing or a home override and grant no admission.
186
345
 
346
+ ## The superagent team (owner)
347
+
348
+ `a2a-net superagent request <text…> [--thread ID] [--json]` sends a request to the team's workbench Source. Sent from the terminal it is an ordinary message, not a person's: the router judges it against the team's rules. `a2a-net superagent reevaluate <trigger id> [--json]` asks the router to judge a stored message again (refused for an A2A message whose sender already has its outcome). `a2a-net superagent state [--json]` prints the team state: router, accept mode, tickets with their stage, and replies. These commands apply only on a home with `superagent: true`.
349
+
350
+ Both ride the home's **owner** control credential (`$A2A_KEY`, plus the pocket cookie behind dsh-pocket), not this CLI's identity. The credential makes the request land, not the person: sent from the terminal it is an ordinary message — the router judges it against the team's rules like an agent's, never as an explicit request or a stop (owner ruling 2026-11-08; only the workbench GUI's owner action is a person's).
351
+
352
+ A message from a CLI identity (`route` to the team's A2A address) is an agent's message under superagent's definition. It can reach the team only through the A2A Source's bot list and accept mode; it is never an explicit request and never a stop. See [superagent.md](superagent.md).
353
+
187
354
  ## Local commands
188
355
 
189
356
  - `a2a-net skills [name] [--root DIR] [--json]` lists the skills under the
190
- local skill directory (default `~/.agents/skills`), or prints one by name.
357
+ local skill directory (default `~/.agents/skills`), or prints one by name (a
358
+ name miss falls back to a path-substring match).
191
359
  It has no model-tool counterpart.
192
360
  - `a2a-net tools` prints the CLI ↔ model-tool alignment table; `help` the
193
361
  usage.
@@ -201,6 +369,10 @@ state face (key-gated on a keyed host). `--json` prints raw rows for
201
369
  | 2 | usage error: unknown command or flag, missing value, bad argument |
202
370
  | 3 | `inbox --wait` timed out |
203
371
 
372
+ With `--json --exit-class` on `route`/`receipt` the exit code carries the
373
+ class instead: 0 sent, 4 gone, 5 the task already carries a different receipt
374
+ (`receipt` only), 1 retry or any other failure (see the receipt section).
375
+
204
376
  ## Caveats
205
377
 
206
378
  - The mailbox read is gated by the host's control key and the handle only,
@@ -213,6 +385,6 @@ state face (key-gated on a keyed host). `--json` prints raw rows for
213
385
 
214
386
  `a2a-net serve [--config node.json] [--host 127.0.0.1|0.0.0.0] [--port N] [--home DIR]` runs the network layer without a DSH instance: cards and OriginClaim, the peer directory, CLI deposits and mailboxes, one-hop forwarding, canvas ownership, the task ledger, the state face and the workbench. It hosts no AI sessions; it forwards to DSH hosts like any home. Use it as an always-on home for CLIs so a DSH restart does not take their deposits, mailboxes and canvas directory down (they also survive the node's own restart).
215
387
 
216
- - `node.json` holds plugin config keys (`team`, `session`, `agentName`, `apiKey`, `peers`, `originClaimUrl`, `originClaimAudiences`, `forwardDirect`, …; `dshHome` is the file form of `--home`, `host`/`port` the file form of the flags); flags win. `--host` takes `127.0.0.1` or `0.0.0.0` only. Defaults: `--host 127.0.0.1`, `--port 13090`, `--home ~/.a2a-net/node` (separate from the CLI's own `~/.a2a`). Bind beyond loopback only with an `apiKey`.
388
+ - `node.json` holds plugin config keys (`team`, `session`, `agentName`, `apiKey`, `peers`, `originClaimUrl`, `originClaimAudiences`, `forwardDirect`, …; `dshHome` is the file form of `--home`, `host`/`port` the file form of the flags); flags win. `--host` is meant for `127.0.0.1` (default) or `0.0.0.0` — the value reaches the listener unvalidated (only `--port` is validated). The node also forces `sessionNodes: true` and `wakeJoinedOnBoot: false`, and defaults `announce: true` (an always-on node exists to be found; a file `announce` still overrides it). Defaults: `--host 127.0.0.1`, `--port 13090`, `--home ~/.a2a-net/node` (separate from the CLI's own `~/.a2a`). Bind beyond loopback only with an `apiKey`.
217
389
  - The runtime needs the tested DSH packages next to this one. In an empty folder: `npm i @nelsonlongxiang/dsh-open-a2a-net@<version>` plus the pinned set `serve` prints when one is missing (npm's `latest` tags of those packages are older and do not work), then `npx a2a-net serve --config node.json`.
218
390
  - Link it like any host: list the DSH hosts in its `peers` and add the node's URL to theirs; put CLIs and the DSH sessions they work with in a canvas team on the node (or rely on #282 S3 for canvases owned elsewhere).
@@ -1,6 +1,6 @@
1
1
  # A2A 协作规范
2
2
 
3
- > 版本 v1.18,2026-11-03。本文自成一体:各节点照本文执行,不需要、也不引用任何只在某台机器上才有的文件或工件。A2A 协作的规则以本文为准;更新时整份替换旧版。本文的修订由属主裁定后生效,评审 PASS 不能让修订自己生效。修订记录见文末。
3
+ > 版本 v1.18.1,2026-11-09。本文自成一体:各节点照本文执行,不需要、也不引用任何只在某台机器上才有的文件或工件。A2A 协作的规则以本文为准;更新时整份替换旧版。本文的修订由属主裁定后生效,评审 PASS 不能让修订自己生效。修订记录见文末。
4
4
 
5
5
  **一句话:自己能做完的就自己做完;要别人做的,一次说清、异步发出,然后接着干别的。**
6
6
 
@@ -46,7 +46,7 @@
46
46
  - 只提交自己改的文件,提交前复核暂存内容;不收编、不暂存、不回退别人在途的改动。
47
47
  - 先看一眼目标仓库的在途改动(`git status`、开着的分支和 PR):别人正在改同一批文件,就另开分支,或先和对方说一声,不在同一份文件上并行改。
48
48
  - 推分支、提 PR 到项目自己的远端,是正常写入,不算外发。
49
- - 例外只有两种:属主宣布冻结的仓库(例如 D1 冻结的 ai-native-expert-agents)不写;凭证和密钥不在写权限之内,按第 9 节办。
49
+ - 例外只有两种:属主宣布冻结的仓库不写(以属主的冻结公告为准);凭证和密钥不在写权限之内,按第 9 节办。
50
50
 
51
51
  **不用 git worktree。**
52
52
  - 不建、也不进 git worktree:不用 `git worktree add`,不用 agent 的“进入 worktree”功能,新建坐席时不选“在 worktree 里工作”。
@@ -426,3 +426,4 @@
426
426
  | v1.16 | 评审 PASS 就是授权:外发、不可逆、生产配置凭评审 PASS 执行,开发自己合并(作者不能自并的由评审合并);只有身份授权资金找持权人、跨项目接口找总工、仓库写明“属主保留”的才等属主;FAIL 有异议改完重审或另起复核,不上报属主;补一个例子,改写两个旧例子的放行依据 |
427
427
  | v1.17 | 一个项目至多两个角色:开发做,评审审。测试归评审,一个 PASS 就够;不设监督和巡查,跨项目的找总工;要并行由开发拉子 agent,不另开坐席;A2A 只剩送审和上报,转派一节改为送审;补现有项目收成两个角色的做法和一个例子。另按 PR 评审意见修订:v1.15 至 v1.17 是属主 2026-11-01 至 11-02 的裁定,本文的修订由属主裁定生效;项目文档已把点头交给具名的人的找那个人,写明的验证步骤照做;PASS 不附带凭证;FAIL 有异议改了送同一个评审审新的 SHA,同一个 SHA 不换评审重审;文件和目录一节去掉 `work/`、`tools/`、`YGL_HOME` 和具体清单文件名,凭证改为不进仓库和任务产物,一次性验证的输出可留在交付记录 |
428
428
  | v1.18 | 去掉授权:取消「先授权五类」、持权人授权、总工授权和「属主保留」,各节点自主决定、自主执行。高档事只多一个条件,即一个非自我节点(不是作者坐席,也不是作者拉起的子 agent)对同一个 SHA 给出评审 PASS。自起的干净复核和验证器重算只算自测;持权人只负责提供凭证;总工只做路由和资源先后;属主可以随时叫停。本文的修订仍由属主裁定生效。属主 2026-11-03 提出 |
429
+ | v1.18.1 | 第 3 节的冻结例外不再点名具体仓库和本机编号,以属主的冻结公告为准(属主 2026-11-09 裁定,#512)。 |
@@ -0,0 +1,106 @@
1
+ # superagent team (design v4)
2
+
3
+ With `superagent: true` in the plugin config, this host runs superagent's own domain engine. The engine is upstream `src/core`, vendored unchanged under `src/superagent/upstream/dsh-superagent`.
4
+
5
+ The flow follows upstream's model:
6
+
7
+ 1. **Source → Trigger.** Today the Source is the workbench. Later the A2A Source also feeds Triggers.
8
+ 2. **Gate.** The gate decides who may originate work (upstream docs/002):
9
+ - **explicit**: an allowed person who addresses the team, or an allowed person's follow-up on a thread with tickets. The owner is that person, through the workbench or `a2a-net superagent request` with the owner credential.
10
+ - **inferred**: a message from an agent on the A2A Source's bot list that addresses the team, or an unlisted person's follow-up. A2A and CLI callers are always agents: a CLI identity proves a key, not a person.
11
+ - The accept mode (`off`, `observe`, `auto`; default `observe`) decides what inferred work can do. Under `observe`, the router judges each inferred candidate against the enabled rules, and a match is recorded as "would accept", with nothing accepted. Under `auto`, a match on enabled rules is accepted.
12
+ - An agent can never make a stop.
13
+ 3. **Eval by the router.** The router is one fixed session the owner names.
14
+ 4. **Decision → Ticket with Mandate.** An accepted request becomes a ticket.
15
+ 5. **Assignment → executor.** The A2A executor runs tickets on the owner's fixed **members**, one ticket per member at a time; the others wait as `working / queued`. It never opens a session.
16
+
17
+ ## The A2A Source (agents)
18
+
19
+ With `sources.a2a` on, **the team's A2A address is its canvas team**: `<zone>/canvas/<name>`, or `<zone>/canvas/<name>@<fp8>` from another host (design v5). A route there never reaches a member session: the host takes it into the team's mailbox, a CLI identity `superagent-team/<16 hex>` it holds under `<a2a home>/superagent/team-cli/` (`GET /__dsh_a2a/superagent` shows it as `a2a.address`). That handle is internal: a route straight to it is refused (`[superagent-team-address]`, counted). Requesters are admitted as for any route to this host's mailboxes — a CLI identity deposited here, an operator's canvas remote reference, a session of this host that declares a team (a teamless session has no network); the team's Policy then decides what becomes work. A sync route answers at once, delivered: the team works asynchronously and its result arrives as the task's receipt. The team's receipts and follow-ups go out from this host's own process face on the canvas team's behalf, with `onBehalfOf` spelled exactly as the requester addressed it, so the requester's ledger settles them as host-face. The team host's card marks the bound canvas as its superagent team (`canvasOrg[].superagentTeam`), so a session on another host that declares a team of its own may route there without a seat on it; the team host still admits it only through an operator link (the owner adds it as a canvas remote reference), and the team's receipt lands on the requester's host as the answer to that one request — its sender, its canvas, the peer key and process label the request was born on. #402's a2a-watch runs inside the host, unchanged:
20
+
21
+ - It keeps the deposit published, renewing it before the 4h expiry.
22
+ - It reads the mailbox and turns each message into a Trigger. A2A callers are agents, so each Trigger has `human: false` and `addressed: direct`.
23
+ - It applies its own trust filter. A message needs a host-verified proof and an operator link (`canvas-shared`, `remote-ref-*` or `cli-deposit`; a CLI deposited on this host counts once routing scope is on). It must not be a loop and must not be a receipt.
24
+ - It sends replies back only to the original caller, after the host rechecks the caller's link. The first message to a task is the formal receipt, and later ones are follow-ups in the same context.
25
+
26
+ Requests to the team address take **no target queue slot**: the engine governs the work. An agent's request becomes a candidate only when the agent is on the bot list and the accept mode is not `off`. Upstream sends automatic acknowledgements only to persons, so an agent's first reply is the result, which is its formal receipt.
27
+
28
+ When an agent's request becomes a ticket, the host sends the requester one **acknowledgement**: an `acknowledged` receipt (`a2a-net receipt <task> --acknowledged`, on task `ack-<task>`). The acknowledgement settles nothing. The requester's row stays owed until the ticket's result receipt settles it. Meanwhile it leaves its host's queue count, and it expires 7 days after the acknowledgement instead of 24 hours after dispatch, so a long ticket does not dead-letter on the requester's side. An older host that does not know the disposition settles the row on the acknowledgement, and the result then arrives as a late receipt.
29
+
30
+ The request keeps its one formal receipt for the result. While its ticket is open and no member report on it is `ready`, a reply on that request (a member's question, a notice) goes to the requester as a follow-up in the same conversation, not as the receipt. When the ticket ends and the request still has no receipt, the host sends the ending receipt itself, with the outcome and the latest report's summary. Upstream sends no result for a stopped or closed ticket, so for those it goes out at once. For any other outcome it waits 5 minutes, so the router's own result goes first.
31
+
32
+ Members can each work in one repository: the owner names it per member in the settings (`repos`, member → `owner/name`). The router then names the repository a request is about when it accepts (`superagent_route` item `repo`); the ticket runs only on that repository's members and waits for one of them without holding up tickets behind it. A request about no single repository is accepted without `repo` and runs on any member. An unknown repository is refused with the team's list.
33
+
34
+ Every A2A message to the team address gets a formal outcome, not only those that start a ticket. A message the team does not take (observe mode, a sender not on the list, a stop an agent may not give, the router's ignore) gets a `rejected` receipt with the reason. A message delivered into a ticket as a follow-up gets a `completed` receipt once its member has it. Without these, the sender's owed row only ever dead-lettered.
35
+
36
+ ## For the router
37
+
38
+ - Candidates arrive in your own session as `[superagent candidate] …` cards. Decide each by its `trigger_id` with `superagent_route`:
39
+ - `accept`: one ticket for the request, with a title, a scope, a reason and an acknowledgement in the request's language. Do not add an implementation plan.
40
+ - `attach`: to a listed open ticket that the message points at or asks for again. A duplicate is attached, never accepted twice. The card lists this thread's tickets and up to 20 of the team's other open tickets, newest first.
41
+ - `stop`: a person asked to stop that ticket.
42
+ - `ignore`: with a reason.
43
+ - For an **inferred** candidate, pass `rules` with the enabled rules it matches. `accept` needs at least one. Under `observe` it is recorded as would-accept. `rules: []` records an assessed ignore.
44
+ - A person's question that asks for no work: answer it with `superagent_reply` (`answer`, its `trigger_id`), then still decide it with `ignore`. Every candidate ends with a `superagent_route` item; an undecided one expires and comes back.
45
+ - Read with `superagent_read`, reply with `superagent_reply` (`answer`, `result` or `attention`), and ask an idle ticket's worker for a status report with `superagent_status`. Give an open ticket's member a fact you learned after accepting it with `superagent_note` (`ticket_id`, `text`); it reaches the member as "note from the router" and grants nothing — new work is a new request. A candidate marked "judged before" is a message a person asked you to judge again. An `attention` reply relays the ticket's open question (`question`, copied exactly); when your text does not already carry it, the host puts the question in front, since only the text reaches the person. Each tool shows you what it returned (tickets, a candidate, a decision's ticket id, a refused item's code), clipped at 12,000 characters.
46
+ - You neither send nor receive A2A work. `a2a_route` from you, or to you by any address (handle, session id, or a canvas you sit in), is refused with `[superagent-router-outbound]` or `[superagent-router-inbound]`.
47
+ - No other session can use these tools; they answer `not-router`.
48
+ - These four are the only tools you can call. Your session runs the `superagent-router` preset; beyond it, the host refuses every other call with `[superagent-role-tools]`, and your visible tools are cut down to them.
49
+
50
+ ## For a member
51
+
52
+ - Your assignment arrives in your own session as `[superagent assignment] ticket … «title»`. It carries the scope and the original request with its trigger id. Later messages on that ticket's threads arrive as `[superagent input] …`, each with its trigger id and whether it comes from a person or an agent.
53
+ - Before you act on a person's message, acknowledge it with `a2a_ticket_ack` (its `trigger_id`, one or two sentences to them). The acknowledgement is a reply on their thread, and the message is yours to handle (for a comment on your pull request it is only recorded; nothing is posted). A message that asks for work beyond your ticket goes back with `a2a_ticket_handback`, for the router to assess. When a report answers a person's question, pass its trigger id as `answers`. A message you read before your last report stays with the ticket. One you never read goes to the router when the ticket ends, so nothing a person said is lost.
54
+ - Work in your own workspace, in a directory or worktree named after the ticket. Stay within the scope.
55
+ - Report with `a2a_ticket_report`, naming the `ticket_id` on the assignment card (a report for a ticket that is no longer yours is refused):
56
+ - `progress`: something changed that the person must know;
57
+ - `waiting`: you are waiting for a Trigger;
58
+ - `ready`: the result can be reviewed or used. Name a pull request in `pull_request`: the ticket then stays open until it merges or closes, and review comments come back to you as `[superagent input]`;
59
+ - `blocked` / `failed`: you cannot go on;
60
+ - `dropped`: there is nothing to do.
61
+
62
+ Add `question` only for what a person alone can decide; choose reasonable defaults for routine steps and say which you chose. The router hears every report in its own session and hands results and questions to the person.
63
+ - A message from an agent (a bot, a CLI identity) is context only. It cannot end, stop or widen your ticket. A `dropped` report made right after one, with no person writing since, is refused (`agent-cannot-end`).
64
+ - When you hand off (a result, a question, `waiting`, `blocked` or `failed`), the host may give you another ticket; a later `[superagent input]` brings the first one back, before any new ticket. A turn that ends with no report counts as `waiting`, with your last words as its summary.
65
+ - When the owner changes the team settings in a way that touches your ticket, you get a `[superagent input]` saying what changed for it: a rule it was accepted on now reads differently or is off, the team no longer takes agent-started work (accept mode is not `auto`), or its requester may no longer start work. It informs you; it neither stops nor widens the ticket. If it changes what you can do, say so with `a2a_ticket_report`.
66
+ - A `ready` report on a ticket with no followed threads ends it. Your slot then frees, and the next waiting ticket comes to you.
67
+ - You neither send nor receive A2A work (`[superagent-member-outbound]`, `[superagent-member-inbound]`). Do not open sessions or subagents.
68
+ - Your tools are upstream's work tools (`read`, `write`, `edit`, `read_image`, `glob`, `grep`, `bash`, `pwsh`, `job_*`, `web_search`, `web_fetch`, `skill`, `todo_write`), plus `a2a_ticket_report`, `a2a_ticket_ack`, `a2a_ticket_handback` and `a2a_file_fetch`. The host refuses every other call with `[superagent-role-tools]`: subagents, other sessions, `a2a_route`, `a2a_report` and the router's tools. A subagent opened earlier acts in your role.
69
+
70
+ ## Members on other hosts
71
+
72
+ A member can sit on another host: another physical node, or another DSH instance on this machine, even one with the same zone label. Its work and reports travel **host to host** as signed, body-bound OriginClaim requests. There is no A2A route, no ledger debt and no receipt.
73
+
74
+ - **On the team host:** add the member's session to the team's canvas team, naming its host: `POST /__dsh_a2a/canvas { action: 'add-member', name: '<team canvas>', id: '<zone>/<id8>', peer: '<member host base URL>' }` (or in the planning view). The member host must be a linked peer. Its key comes from its signed card and the canvas pins it with the qualified ref. A report or turn end for that member counts only under that key (`/a2a/superagent-team`), so another instance sharing the handle is refused. Removing it from the canvas removes it from the team.
75
+ - **On the member host:** `POST { action: 'serve', team: '<zone>/canvas/<name>@<fp8>', members: [<local session ids>] }` — the team's canvas id, whose fingerprint names its owner. The host finds the linked peer whose signed card has that key and advertises that canvas, and pins the key. Only that key may assign work to those sessions (`/a2a/superagent-member`). Those sessions report with `a2a_ticket_report` as usual, and the host forwards the report, signed. `team: null` leaves the team. This is the member host owner's consent: a team host cannot take another host's sessions on its own. A served session on another preset than `superagent-member` (a serve stored before presets) takes no new work — a stop still reaches it — and the state reports it as `servesProblem` until it is served from a member-preset session.
76
+ - Serving sessions are isolated from A2A like any member.
77
+
78
+ ## For the owner
79
+
80
+ The owner control route is `/__dsh_a2a/superagent`.
81
+
82
+ **The team is a canvas team** (design v5). The owner composes it on the canvas — the planning view's 建队, or `/__dsh_a2a/canvas` — with the router and the members, local and on other hosts, then binds it here with `canvas` (the canvas team's name on this host) and `router` (one of its local sessions). Every other session on that canvas is a member, one worker slot each; adding or removing one on the canvas adds it to or removes it from the pool at once. A member removed while it runs a ticket is told to stop, and the ticket starts again on another member. While the team is bound to no canvas (as right after upgrading from a version before canvas teams, which keeps the router and drops the stored pool) or its canvas is gone, nothing is moved: running work stays with its member until the owner binds a canvas again, and the stored router may join the canvas that becomes the team. One session holds one team role: the team's canvas takes no CLI handle and no session that serves another team host, and a team session sits in no other canvas (`[superagent-team-canvas]`).
83
+
84
+ The router and the members are sessions the owner creates under the team's agent presets, which this plugin ships in its bundle layer: **`superagent-router`** (superagent 总工) for the router and **`superagent-member`** (superagent 团队成员) for each member. The preset is the role's boundary:
85
+
86
+ - `superagent-router`: read-only files, a foreground command and a job wait of at most 5 s, skills and compaction; no subagents.
87
+ - `superagent-member`: the work tools; a foreground command moves to a background job after 5 s, so a stop or a person's answer is taken at the next step; no subagents.
88
+
89
+ Settings naming a router or member that runs another preset are refused, and so is `serve`. A session not loaded at the time, or a host without a preset registry, is not checked.
90
+
91
+ The workbench (`/__dsh_a2a_nexus/`) shows it as the **团队** tab whenever the host runs a team. The tab has five views:
92
+
93
+ - **待你处理**: tickets waiting on a person (answer, review, blocked or failed, failed delivery) and the team's problems. These include a missing router, an empty member pool, a pause, A2A Source errors, an overdue decision, and an undelivered reply.
94
+ - **提需求**: the workbench Source. A request box, and each request's thread with its decisions and replies. Each thread has a box for adding a follow-up. A request the router turned down (`ignore`, or `unavailable` when it did not decide in time) offers 「重新判断」: the router gets it again, marked as a second look.
95
+ - **工单**: tickets grouped by stage, with stop and retry.
96
+ - **团队**: the router, each member's slot, the remote members and the team this host serves, with their pinned keys, and the A2A address.
97
+ - **设置**: the canvas team and its router (members are shown from the canvas), the accept mode, the Source switches, and pause.
98
+
99
+ - `GET` returns the state: threads with their triggers, decisions and replies, and tickets with their stage. It also returns `refusals`, the refusals at the team's edge in this process. These include A2A routes to or from a role session, role sessions' calls outside their tool list, and host-to-host requests that are unsigned or not signed by the pinned key. They are counted by rule (`counts`), and the latest 50 are kept with caller and target (`recent`).
100
+ - `POST { action }` takes one of:
101
+ - `settings`: the canvas team (`canvas`, a canvas on this host; `null` unbinds) and its router (`router`, a joined local session of that canvas) — members are never named here, they come from the canvas — the repository per member (`repos`), the allowed persons per Source, the A2A bot list, the accept mode, the proactive rules (`{name, text, enabled}`), the Source switches, the Eval timeout, and pause;
102
+ - `request`: the workbench Source, with `text`, and `thread` to follow up;
103
+ - `stop` / `retry`: act on a ticket by `ticket_id`;
104
+ - `reevaluate`: a fresh judgement of a stored message by `trigger_id` (`queued: false` while one is under way). A person's message may be judged again; an A2A message whose sender already has its formal outcome is refused (`answered`) — its task is settled, so the sender sends it again. The CLI's `a2a-net superagent reevaluate <trigger id>` does the same.
105
+ - A follow-up on a ticket's thread goes to that ticket (Subscription fan-out). It does not start a new Eval.
106
+ - State lives under `<a2a home>/superagent/`.