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

package/assets/stageDist/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>dsh-a2a-munder-difflin · A2A Floor</title>
+  <script type="module" crossorigin src="./assets/index-C-28k_o5.js"></script>
+  <link rel="stylesheet" crossorigin href="./assets/index-Bj7S2pA1.css">
+</head>
+<body>
+<div id="root"></div>
+</body>
+</html>

package/lib/a2a-client.js

@@ -6,8 +6,15 @@
  * @module @nelsonlongxiang/dsh-open-a2a-net/a2a-client
  */
 import { verifyCard } from "./card.js";
+import { MAX_ROUTE_BODY_BYTES, WIRE_ERROR_PAYLOAD_TOO_LARGE, withinRouteBodyCap } from "./transport-caps.js";
 /** Direct-route HTTP budget. */
 const HTTP_TIMEOUT_MS = 15_000;
+/** The native-teams bridge marker, when the peer's answer carries one: its
+ * rounds emit no A2A receipt in this slice, so the caller must not book the
+ * task as receipt-owed. */
+function wireBridge(value) {
+    return value === 'native-teams' ? 'native-teams' : undefined;
+}
 /** Wire strings are absent-or-string; anything else degrades to ''. */
 function wireText(value) {
     return typeof value === 'string' ? value : '';
@@ -28,13 +35,26 @@ export class A2aClient {
             headers['Content-Type'] = 'application/json';
         if (this.options.apiKey !== '')
             headers['X-API-Key'] = this.options.apiKey;
+        // GETs are card fetches: name ourselves so the peer serves the full
+        // card (gh#7 G1). POSTs carry caller_session in the body already.
+        if (!json && this.options.cardCaller !== '')
+            headers['X-A2A-Caller'] = this.options.cardCaller;
+        // gh#9+gh#10: the OriginClaim envelope — a verifiable origin on every
+        // peer request when the signer is wired (full-card reads and delivery
+        // verification both ride it).
+        if (this.options.originClaim !== undefined) {
+            for (const [key, value] of Object.entries(this.options.originClaim()))
+                headers[key] = value;
+        }
         return headers;
     }
     async http(path, init, baseUrl) {
         if (init.signal?.aborted)
             throw new Error('A2A request aborted before dispatch');
         const controller = new AbortController();
+        let ownBudgetFired = false;
         const timer = this.options.schedule(() => {
+            ownBudgetFired = true;
             controller.abort();
         }, HTTP_TIMEOUT_MS);
         const abort = () => {
@@ -49,10 +69,26 @@ export class A2aClient {
                 signal: controller.signal,
             });
             const text = await response.text();
-            if (!response.ok)
-                throw new Error(`A2A HTTP ${String(response.status)}: ${text.slice(0, 200)}`);
+            if (!response.ok) {
+                // Carry the status and raw body on the error so callers can read the
+                // peer's structured wire code (idempotency verdicts) without parsing
+                // the prose of the message.
+                const error = new Error(`A2A HTTP ${String(response.status)}: ${text.slice(0, 200)}`);
+                error.statusCode = response.status;
+                error.bodyText = text;
+                throw error;
+            }
             return JSON.parse(text);
         }
+        catch (error) {
+            // Tag the escapee so the caller can tell our budget firing from an
+            // external signal — the abortElapsedMs telemetry needs the author.
+            if (ownBudgetFired && error instanceof Error) {
+                ;
+                error.ownBudgetExhausted = true;
+            }
+            throw error;
+        }
         finally {
             timer();
             init.signal?.removeEventListener('abort', abort);
@@ -67,16 +103,28 @@ export class A2aClient {
      * @returns the verified card, or `undefined` when unreachable, malformed, or rejected.
      */
     async fetchCard(baseUrl) {
+        const outcome = await this.fetchCardDetail(baseUrl);
+        return outcome.ok ? outcome.card : undefined;
+    }
+    /**
+     * The diagnosing half of {@link fetchCard}: the same fetch and verification
+     * with the failure stage preserved, so a probe can tell a down node from a
+     * distrusted card.
+     * @param baseUrl - the peer's base URL.
+     * @returns the verified card, or the failure's stage and detail.
+     */
+    async fetchCardDetail(baseUrl) {
         try {
             const candidate = await this.http('/.well-known/agent-card.json', { method: 'GET' }, baseUrl);
             const verified = verifyCard(candidate, Date.now());
             if (!verified.ok)
-                return undefined;
-            return verified.card;
+                return { ok: false, stage: 'rejected', reason: verified.reason };
+            return { ok: true, card: verified.card };
         }
-        catch {
-            // An unreachable or malformed peer leaves discovery to the other peers.
-            return undefined;
+        catch (error) {
+            // An unreachable or malformed peer leaves discovery to the other peers;
+            // the detail names what actually happened for the probe.
+            return { ok: false, stage: 'unreachable', detail: String(error).slice(0, 200) };
         }
     }
     /**
@@ -106,7 +154,7 @@ export class A2aClient {
      * @param callerSession - caller label overriding the node's label (the calling session's node label).
      * @returns the canonical route result (success or explicit failure).
      */
-    async routeDirect(baseUrl, team, message, contextId, signal, callerSession, asyncMode = false, taskIdFromCaller) {
+    async routeDirect(baseUrl, team, message, contextId, signal, callerSession, asyncMode = false, taskIdFromCaller, callbackAddress) {
         const args = { team, message, caller_session: callerSession ?? this.options.sessionId };
         if (contextId !== undefined)
             args.context_id = contextId;
@@ -120,16 +168,80 @@ export class A2aClient {
         // own (pre-0.5.3 peers).
         if (taskIdFromCaller !== undefined)
             args.task_id = taskIdFromCaller;
+        // The callback address (P2): where the peer routes THIS caller's
+        // receipt — distinct from the caller label when the submitting session
+        // has its own node team (the transport face's callbackTarget mapping
+        // rides this). Old peers ignore the extra body field harmlessly.
+        if (callbackAddress !== undefined && callbackAddress !== '')
+            args.callback = callbackAddress;
+        // Outbound half of the same B5 ruling: refuse to put an oversized
+        // payload on the wire. Rejection is local and instant — a doomed upload
+        // would burn the 15s HTTP budget and end in the peer's 413 anyway.
+        const body = JSON.stringify(args);
+        if (!withinRouteBodyCap(Buffer.byteLength(body, 'utf8'))) {
+            return {
+                ok: false,
+                error: `payload exceeds the ${String(MAX_ROUTE_BODY_BYTES)}-byte direct-route transport cap`,
+                code: WIRE_ERROR_PAYLOAD_TOO_LARGE,
+            };
+        }
         let raw;
+        const dispatchedAt = Date.now();
         try {
             raw = await this.http('/a2a/direct', {
                 method: 'POST',
-                body: JSON.stringify(args),
+                body,
                 ...(signal !== undefined ? { signal } : {}),
             }, baseUrl);
         }
         catch (error) {
-            return { ok: false, error: `direct route to peer failed: ${String(error)}`, code: -32000 };
+            const ownBudgetExhausted = error.ownBudgetExhausted === true;
+            // F1 half-transaction fix (t-mth5gmxy): the 15s budget firing on a SYNC
+            // route does NOT mean the peer failed — the delivery landed and the
+            // peer keeps executing. The structured -32005 code marks the
+            // DELIVERED-UNSETTLED shape; the caller side (index.ts, which owns the
+            // fingerprint and the peer candidates) runs the query compensation and
+            // upgrades or confirms the honest result there. The budget gate checks
+            // BOTH the flag and the error KIND: an immediate transport rejection
+            // (ECONNREFUSED) racing a scheduled timer is a transport failure, not
+            // a wait timeout — only a genuine abort-class error is the budget.
+            const abortClass = error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError' || /abort/i.test(error.message));
+            if (ownBudgetExhausted && abortClass && !asyncMode && !signal?.aborted) {
+                return {
+                    ok: false,
+                    error: `route wait timed out after ${String(HTTP_TIMEOUT_MS)}ms but the delivery was dispatched and may still complete — reconcile via the task query (do NOT re-dispatch blindly)`,
+                    code: -32005,
+                    task_id: taskIdFromCaller,
+                    abortElapsedMs: Date.now() - dispatchedAt,
+                    ownBudgetExhausted: true,
+                };
+            }
+            // The peer's structured wire code rides the HTTP rejection body
+            // (idempotency verdicts -32002/-32003 among others): surface it, so a
+            // caller can tell a terminal verdict from an ordinary transport miss
+            // without parsing prose.
+            let code = -32000;
+            const bodyText = error.bodyText;
+            if (typeof bodyText === 'string') {
+                try {
+                    const parsed = JSON.parse(bodyText);
+                    if (typeof parsed.code === 'number')
+                        code = parsed.code;
+                }
+                catch {
+                    /* prose body — keep the generic code */
+                }
+            }
+            const failure = {
+                ok: false,
+                error: `direct route to peer failed: ${String(error)}`,
+                code,
+                // Wait-window telemetry (envelope-v2 §4): measured patience plus
+                // whose budget ended it. Pure observation, zero semantics.
+                abortElapsedMs: Date.now() - dispatchedAt,
+                ...(ownBudgetExhausted ? { ownBudgetExhausted: true } : {}),
+            };
+            return failure;
         }
         if (raw.error !== undefined && raw.error !== null) {
             const failure = {
@@ -141,26 +253,91 @@ export class A2aClient {
             return failure;
         }
         // The delivered shape (wait:false): no result member — the reply rides
-        // the receipt contract back to the caller's team instead.
+        // the receipt contract back to the caller's team instead. A bridged
+        // native round carries the peer's `bridge` marker and promises NO
+        // receipt: the text must not claim one the slice will never send.
         if (raw.routed === true && raw.delivered === true) {
             const taskId = wireText(raw.task_id) !== '' ? wireText(raw.task_id) : taskIdFromCaller ?? '';
+            const bridge = wireBridge(raw.bridge);
+            // F1 client half (async-stall §三): the peer's consumed probe rides
+            // through — a delivered-but-unconsumed message is queued (busy turn)
+            // or latched, and the caller should follow up, not assume arrival.
+            const consumed = typeof raw.consumed === 'boolean' ? raw.consumed : undefined;
             return {
                 ok: true,
                 team,
-                reply: `Delivered to ${team} (async). The target routes a receipt — a message starting "[A2A receipt] task ${taskId} <outcome summary>" — back to your team when done; watch a2a_status activity or follow up with the context id.`,
+                reply: bridge !== undefined
+                    ? `Delivered to ${team} (async native-teams round). It settles through the team's own routing chain and routes no A2A receipt in this slice — reconcile via context_id follow-ups.`
+                    : consumed === false
+                        ? `Delivered to ${team} (async), but the target had not started a turn on it yet — the message is queued behind the session's current turn. Watch a2a_status activity or follow up with the context id; do not resend.`
+                        : `Delivered to ${team} (async). The target routes a receipt — a message starting "[A2A receipt] task ${taskId} <outcome summary>" — back to your team when done; watch a2a_status activity or follow up with the context id.`,
                 task_id: taskId,
                 context_id: wireText(raw.context_id),
                 task_status: wireText(raw.task_status) === '' ? 'TASK_STATE_DELIVERED' : wireText(raw.task_status),
+                ...(consumed !== undefined ? { consumed } : {}),
+                ...(bridge !== undefined ? { bridge } : {}),
             };
         }
         const reply = this.replyText(raw.result, '');
+        const bridge = wireBridge(raw.bridge);
         return {
             ok: true,
             team,
             reply,
-            task_id: wireText(raw.task_id) !== '' ? wireText(raw.task_id) : taskIdFromCaller ?? wireText(raw.task_id),
+            // Same echo-first rule as the delivered branch: the peer's echo wins,
+            // else the caller-born id, else ''.
+            task_id: wireText(raw.task_id) !== '' ? wireText(raw.task_id) : taskIdFromCaller ?? '',
             context_id: wireText(raw.context_id),
             task_status: wireText(raw.task_status),
+            ...(bridge !== undefined ? { bridge } : {}),
         };
     }
+    /**
+     * Query a peer's `/a2a/query` outcome surface (W7 slice 2): read-only
+     * lookup of one claimed task's settled outcome. The fingerprint is the
+     * authorization — the caller recomputes it from the exact submit fields
+     * with the shared `peerPayloadFingerprint`. Every transport-level failure
+     * (network miss, HTTP error, unparseable or malformed body, empty fields)
+     * answers `undefined`: a query that cannot complete carries no increment
+     * of information, never a verdict.
+     */
+    async queryOutcome(baseUrl, taskId, fingerprint, signal) {
+        if (taskId === '' || fingerprint === '')
+            return undefined;
+        try {
+            const raw = await this.http('/a2a/query', {
+                method: 'POST',
+                body: JSON.stringify({ task_id: taskId, fingerprint }),
+                ...(signal !== undefined ? { signal } : {}),
+            }, baseUrl);
+            return parseQueryAnswer(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Coerce one raw wire body into an {@link A2aQueryAnswer}; anything
+ * malformed degrades to `undefined` (no verdict), never to a guess. */
+function parseQueryAnswer(raw) {
+    if (raw.found !== true && raw.found !== false)
+        return undefined;
+    if (raw.found === false) {
+        if (raw.reason !== 'unknown-task' && raw.reason !== 'payload-mismatch')
+            return undefined;
+        return { found: false, reason: raw.reason };
+    }
+    if (raw.status === 'pending')
+        return { found: true, status: 'pending' };
+    const settledAt = typeof raw.settled_at === 'string' && raw.settled_at !== '' ? raw.settled_at : undefined;
+    if (settledAt === undefined)
+        return undefined;
+    const truncated = raw.truncated === true ? { truncated: true } : {};
+    if (raw.status === 'completed' && typeof raw.reply === 'string') {
+        return { found: true, status: 'completed', reply: raw.reply, settledAt, ...truncated };
+    }
+    if (raw.status === 'failed' && typeof raw.error === 'string') {
+        return { found: true, status: 'failed', error: raw.error, settledAt, ...truncated };
+    }
+    return undefined;
 }

package/lib/canvas-store.js

@@ -0,0 +1,218 @@
+/**
+ * Persisted canvas teams: user-composed multi-member routing groups under
+ * the a2a home (`a2a/canvas.json`). A canvas team is a named set of member
+ * references in one of two shapes: a local session id (a joined session
+ * node on this host) or a remote team handle (`<zone>/<id8>`, a session
+ * node published by a peer — one member may sit in many teams). Routing to
+ * `<team>/canvas/<name>` resolves the first live local member, wakes the
+ * first cold local one, then falls through to the remote members in order
+ * (the directory resolves their handles; remote nodes never wake from
+ * here). Membership order is the routing priority (member list order),
+ * preserved verbatim on disk. Plain JSON, one writer (the control routes),
+ * read fresh by the state route.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/canvas-store
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Upper bounds: a canvas taxonomy, not a database. */
+export const CANVAS_TEAM_CAP = 64;
+export const CANVAS_MEMBER_CAP = 32;
+/** Longest accepted team name (same budget as group names). */
+export const CANVAS_NAME_MAX = 40;
+/**
+ * Whether one member entry references a remote node rather than a local
+ * session id. Remote refs are zone-qualified team handles (`<zone>/<id8>`),
+ * so the '/'-test is deterministic: local session ids (`session-<uuid>`,
+ * `import-<uuid>`) never contain one, and canvas team names — the only other
+ * strings in a member slot — are barred from '/' at creation.
+ */
+export function isRemoteMemberRef(id) {
+    return id.includes('/');
+}
+/**
+ * Shape-gate for a remote member reference at the control-route seam: at
+ * least one '/'-delimited segment on each side, no whitespace. The registry
+ * cross-check lives in the UI (the picker offers discovered rows only);
+ * this gate keeps malformed strings out of the persisted file.
+ */
+export function validRemoteMemberRef(id) {
+    const trimmed = id.trim();
+    return trimmed === id && isRemoteMemberRef(id) && !/\s/.test(id)
+        && !id.startsWith('/') && !id.endsWith('/') && !id.includes('//');
+}
+function validName(raw) {
+    const clean = raw.trim();
+    if (clean === '' || clean.length > CANVAS_NAME_MAX)
+        return undefined;
+    // '/' would nest the wire namespace (<team>/canvas/a/b); pure digits would
+    // reorder under JSON.parse's integer-like key ordering if the store ever
+    // migrated to a keyed map — both stay out now.
+    if (clean.includes('/') || /^\d+$/.test(clean))
+        return undefined;
+    return clean;
+}
+/**
+ * Bounded canvas-team store with last-write-wins persistence. Pure of any
+ * registry knowledge: callers validate join state and resolve members.
+ */
+export class CanvasStore {
+    /** Team entries in creation order; members in add order (routing priority). */
+    teams = [];
+    path;
+    /**
+     * @param path - the snapshot file; an empty path keeps the store in memory.
+     */
+    constructor(path) {
+        this.path = path;
+        this.restore();
+    }
+    /** Load a persisted snapshot, if present and well-formed. */
+    restore() {
+        if (this.path === '' || !existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            if (!Array.isArray(snapshot?.teams))
+                return;
+            const kept = [];
+            for (const entry of snapshot.teams) {
+                if (entry === null || typeof entry !== 'object')
+                    continue;
+                if (validName(String(entry.name)) === undefined)
+                    continue;
+                const members = Array.isArray(entry.members)
+                    ? entry.members.filter((id) => typeof id === 'string' && id !== '').slice(0, CANVAS_MEMBER_CAP)
+                    : [];
+                if (kept.some(t => t.name === entry.name))
+                    continue;
+                kept.push({ name: String(entry.name), members });
+            }
+            this.teams = kept.slice(0, CANVAS_TEAM_CAP);
+        }
+        catch {
+            // A corrupt store is not fatal: the user re-creates teams; routing
+            // names simply stop resolving until then.
+        }
+    }
+    /** Persist the current snapshot (no-op without a path). */
+    persist() {
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            const snapshot = { teams: this.teams.map(t => ({ name: t.name, members: [...t.members] })) };
+            writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
+        }
+        catch {
+            // An unwritable home must not break the canvas; the store degrades to
+            // memory-only.
+        }
+    }
+    /** Every team name, in creation order. */
+    list() {
+        return this.teams.map(t => t.name);
+    }
+    /** Whether the named team exists. */
+    hasTeam(name) {
+        return this.teams.some(t => t.name === name);
+    }
+    /** The named team's member ids in routing-priority order (a copy). */
+    membersOf(name) {
+        const entry = this.teams.find(t => t.name === name);
+        return entry === undefined ? [] : [...entry.members];
+    }
+    /**
+     * The named team's remote member refs (zone-qualified team handles) in
+     * routing-priority order — the failover tier after the local live/cold
+     * tiers miss. Shape test only: whether the handle currently resolves is
+     * the directory's question at route time, not the store's.
+     */
+    remoteMembersOf(name) {
+        return this.membersOf(name).filter(isRemoteMemberRef);
+    }
+    /** Every team name the id is a member of, in team creation order. */
+    teamsOf(id) {
+        return this.teams.filter(t => t.members.includes(id)).map(t => t.name);
+    }
+    /**
+     * Create a named team; whitespace trims, duplicates are idempotent, and
+     * the cap rejects a team beyond {@link CANVAS_TEAM_CAP}.
+     * @param name - the raw user-supplied name.
+     * @returns the stored name, or undefined when rejected.
+     */
+    create(name) {
+        const clean = validName(name);
+        if (clean === undefined)
+            return undefined;
+        if (this.hasTeam(clean))
+            return clean;
+        if (this.teams.length >= CANVAS_TEAM_CAP)
+            return undefined;
+        this.teams.push({ name: clean, members: [] });
+        this.persist();
+        return clean;
+    }
+    /**
+     * Delete a team (with its memberships).
+     * @param name - the team name.
+     */
+    remove(name) {
+        const index = this.teams.findIndex(t => t.name === name);
+        if (index < 0)
+            return false;
+        this.teams.splice(index, 1);
+        this.persist();
+        return true;
+    }
+    /**
+     * Add one member (idempotent; duplicates keep the original priority slot).
+     * The team must exist — callers create it first so the cap applies once.
+     * @param name - the existing team name.
+     * @param id - the member session id.
+     */
+    addMember(name, id) {
+        if (id === '')
+            return false;
+        const entry = this.teams.find(t => t.name === name);
+        if (entry === undefined)
+            return false;
+        if (entry.members.includes(id))
+            return true;
+        if (entry.members.length >= CANVAS_MEMBER_CAP)
+            return false;
+        entry.members.push(id);
+        this.persist();
+        return true;
+    }
+    /**
+     * Remove one member from one team (a no-op when absent).
+     */
+    removeMember(name, id) {
+        const entry = this.teams.find(t => t.name === name);
+        if (entry === undefined)
+            return false;
+        const index = entry.members.indexOf(id);
+        if (index < 0)
+            return false;
+        entry.members.splice(index, 1);
+        this.persist();
+        return true;
+    }
+    /**
+     * Drop one id from every team — the leave and archive paths: a session
+     * leaving the network keeps no canvas membership anywhere.
+     * @param id - the departing session id.
+     */
+    dropMember(id) {
+        let dirty = false;
+        for (const entry of this.teams) {
+            const index = entry.members.indexOf(id);
+            if (index >= 0) {
+                entry.members.splice(index, 1);
+                dirty = true;
+            }
+        }
+        if (dirty)
+            this.persist();
+    }
+}

package/lib/card.js

@@ -104,6 +104,28 @@ function sessionTeams(wire) {
     }
     return entries;
 }
+/**
+ * The unsigned `teamMemberships` listing passes through only as an array of
+ * well-formed node→team entries; any other shape drops the field instead of
+ * rejecting the card — same posture as `sessionTeams`, because cards from
+ * nodes that declared no roster teams (or pre-roster versions) carry none.
+ * @param wire - the shape-checked card candidate.
+ * @returns the membership entries, or `undefined` when absent or malformed.
+ */
+function teamMemberships(wire) {
+    if (!Array.isArray(wire.teamMemberships))
+        return undefined;
+    const entries = [];
+    for (const entry of wire.teamMemberships) {
+        const membership = entry;
+        if (typeof membership?.node !== 'string' || membership.node === '')
+            continue;
+        if (typeof membership.team !== 'string' || membership.team === '')
+            continue;
+        entries.push({ node: membership.node, team: membership.team });
+    }
+    return entries;
+}
 /**
  * Verify a parsed card: shape, signature, and expiry, in that order.
  * @param candidate - the JSON value fetched from a peer's agent-card URL.
@@ -144,6 +166,7 @@ export function verifyCard(candidate, now) {
     }
     const peers = referrals(wire);
     const teams = sessionTeams(wire);
+    const memberships = teamMemberships(wire);
     return {
         ok: true,
         card: {
@@ -151,7 +174,9 @@ export function verifyCard(candidate, now) {
             expiresAt: wire.expiresAt,
             ...(peers !== undefined ? { peers } : {}),
             ...(teams !== undefined && teams.length > 0 ? { sessionTeams: teams } : {}),
+            ...(memberships !== undefined && memberships.length > 0 ? { teamMemberships: memberships } : {}),
             ...(typeof wire.lanIp === 'string' && wire.lanIp !== '' ? { lanIp: wire.lanIp } : {}),
+            ...(typeof wire.version === 'string' && wire.version !== '' ? { version: wire.version } : {}),
             publicKey: wire.publicKey,
             signature: wire.signature,
         },