@nelsonlongxiang/dsh-open-a2a-net 0.6.33 → 0.6.34

package/lib/direct-forward.js

@@ -0,0 +1,61 @@
+/** H-side one-hop forwarding. Never resolves or dispatches local candidates again. */
+import { DEFAULT_HOP_BUDGET, guardHeader, mintGuard } from "./recursion-guard.js";
+import { briefOf } from "./task-ledger.js";
+import { parseReceipt } from "./receipt.js";
+export function createDirectForward(d) {
+    return async (request) => {
+        const refuse = (why) => ({ ok: false, code: -32000, task_id: request.taskId, error: 'not forwarded: ' + why });
+        if (!d.enabled())
+            return refuse('forwardDirect is off');
+        if (d.isolated())
+            return refuse('host is isolated');
+        if (request.guarded)
+            return refuse('an inbound X-A2A-Guard is present; already forwarded');
+        if (!request.localCliProof || !d.deposited(request.caller))
+            return refuse('caller is not a proven online local CLI deposit');
+        const scope = await d.scope(request.caller, request.team);
+        if (!scope.ok)
+            return refuse('target is outside sender scope: ' + scope.error);
+        const failures = [];
+        const directory = await d.candidates(request.team, failures, request.caller);
+        const guard = guardHeader({ ...mintGuard(), hopBudget: DEFAULT_HOP_BUDGET - 1 });
+        for (const url of directory.urls) {
+            if (!d.deposited(request.caller))
+                return refuse('local CLI deposit expired before dispatch');
+            if (request.team.includes('/canvas/')) {
+                const card = await directory.card(url);
+                const org = card?.canvasOrg?.find(row => row.team === request.team);
+                const receivers = org?.members.filter(member => member !== request.caller) ?? [];
+                if (receivers.length === 0 || receivers.some(member => !d.memberLinked(member))) {
+                    failures.push(url + ': forwarding a canvas requires a direct operator link to every receiving member for its receipt return path');
+                    continue;
+                }
+            }
+            const answer = await d.dispatch(url, request, guard);
+            const result = !answer.ok && answer.ownBudgetExhausted === true ? { ...answer, code: -32005 } : answer;
+            d.activity(request.team, url, result.ok);
+            if (result.ok || result.code === -32005) {
+                // A receipt owes no receipt; native bridge rounds have no A2A receipt contract.
+                // Match routeTrunk/trackOwedTask rather than manufacturing an unpayable debt.
+                if (parseReceipt(request.message) !== null)
+                    return { ...result, receipt: 'none' };
+                if (result.ok && result.bridge !== undefined)
+                    return { ...result, receipt: 'none' };
+                const card = await directory.card(url);
+                const birth = { forwarded: true, ...(card?.publicKey ? { peerKey: card.publicKey } : {}), ...(card?.session ? { peerHost: card.session } : {}), deliveredTo: result.ok ? result.deliveredTo ?? request.team : request.team };
+                // Exactly one outbound row. A completed sync response is receiptless bookkeeping.
+                if (result.ok && (result.task_status === 'TASK_STATE_COMPLETED' || result.receipt === 'none'))
+                    d.ledger.trackReceiptless(request.taskId, request.team, url, request.contextId, briefOf(request.message), { kind: 'cli', id: request.caller }, birth);
+                else
+                    d.ledger.track(request.taskId, request.team, url, request.contextId, briefOf(request.message), { kind: 'cli', id: request.caller }, birth);
+                return result;
+            }
+            // The shared dispatcher's sync recovery query may prove a definitive failed
+            // outcome; like routeTrunk, that is an eligible miss, not an uncertain -32005.
+            failures.push(url + ': ' + result.error);
+            if (result.code === -32002 || result.code === -32003)
+                return { ...result, task_id: request.taskId };
+        }
+        return { ok: false, code: -32004, task_id: request.taskId, error: 'forwarding to "' + request.team + '" failed: ' + (failures.join('; ') || 'no eligible peer candidate') };
+    };
+}

package/lib/faces/admin.js

@@ -20,11 +20,13 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { canvasNameReserved as reservedCanvasName, isRemoteMemberRef, validRemoteMemberRef } from "../canvas-store.js";
 import { refreshPeerCard, registerCanvasNotify } from "./canvas-notify.js";
+import { CLI_HANDLE_RE } from "../cli-deposit.js";
 import { applyOwnerSettings } from "../owner-settings.js";
 import { rosterOp } from "../roster-op.js";
 import { resolveStageMount } from "../stage-mount.js";
 import { ARCHIVE_CAP, archivedEndedBy } from "../task-ledger.js";
 import { MAX_LAYOUT_BODY_BYTES } from "../transport-caps.js";
+import { queuedFor } from "../queue-guard.js";
 /**
  * Register the admin faces on a settled web server.
  * @param webServer - the settled host web server.
@@ -54,6 +56,14 @@ export function registerAdminFaces(webServer, d) {
                 // or not. (The prune above already took their join intents; this
                 // covers never-joined live roots and any intent a restart left.)
                 const isArchived = archivedSessionFilter();
+                const liveStatusOf = (agent) => {
+                    try {
+                        return agent.status === 'running' ? 'running' : agent.status === 'idle' ? 'idle' : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                };
                 const tFacts0 = Date.now();
                 const sessions = [...liveRoots.values()]
                     .filter(agent => isArchived?.(String(agent.id)) !== true)
@@ -68,6 +78,10 @@ export function registerAdminFaces(webServer, d) {
                         ...nodeMetadataOf(agent),
                         joined: sessionNodes.has(String(agent.id)),
                         live: true,
+                        // Owner 2026-11-03: whether the session is mid-turn right now, and how many
+                        // receipt-owing tasks wait on it (the gh#224 queue count) — the board's 工作中/空闲.
+                        status: liveStatusOf(agent),
+                        queued: queuedFor(taskLedger.list(), sessionTeamOf(agent)),
                         teams: [...teamMemberships.teamsOf(String(agent.id))],
                         // #19 D3: the session's exposure tier (linked floor /
                         // fleet opt-up) — readable on the state face.
@@ -138,7 +152,7 @@ export function registerAdminFaces(webServer, d) {
                                             rows.push({ id: localId, team: `${config.team}/${id8(localId)}`, joined: sessionNodes.has(localId) || joinedSessions.has(localId), live: sessionNodes.has(localId) });
                                             continue;
                                         }
-                                        rows.push({ id, team: id, remote: true });
+                                        rows.push({ id, team: id, remote: true, ...(CLI_HANDLE_RE.test(id) ? { cliHome: canvasStore.cliHomeOf(id) ?? null, cliHeld: cliDeposits.directoryRows().some(row => row.team === id) } : {}) });
                                         continue;
                                     }
                                     if (seenLocal.has(id))
@@ -238,6 +252,7 @@ export function registerAdminFaces(webServer, d) {
                         ...(row.brief !== undefined ? { brief: row.brief } : {}),
                         ...(row.summary !== undefined && row.summary !== '' ? { summary: row.summary.slice(0, 160) } : {}),
                         ...(row.sender !== undefined ? { sender: row.sender } : {}),
+                        ...(row.forwarded === true ? { forwarded: true } : {}),
                         ...(row.auth !== undefined ? { auth: row.auth } : {}),
                         // #114 S4: who settled it and how they stood on the chain.
                         ...(row.settledBy !== undefined ? { settledBy: row.settledBy } : {}),
@@ -688,10 +703,24 @@ export function registerAdminFaces(webServer, d) {
         kind: 'exact',
         path: '/__dsh_a2a/canvas',
         handler: controlRoute((req, res) => {
-            readJsonBody(req, res, (body) => {
+            readJsonBody(req, res, async (body) => {
                 const action = body.action;
                 let payload;
-                if (action === 'create') {
+                if (action === 'cli-home-options') {
+                    const name = typeof body.name === 'string' ? body.name : '';
+                    const id = typeof body.id === 'string' ? body.id : '';
+                    if (!CLI_HANDLE_RE.test(id) || !canvasStore.membersOf(name).includes(id))
+                        payload = JSON.stringify({ ok: false, error: 'an existing canvas CLI member is required' });
+                    else {
+                        try {
+                            payload = JSON.stringify({ ok: true, ...await d.cliHomeOptions(id) });
+                        }
+                        catch {
+                            payload = JSON.stringify({ ok: false, error: 'fresh home card lookup failed' });
+                        }
+                    }
+                }
+                else if (action === 'create') {
                     const name = typeof body.name === 'string' ? body.name : '';
                     const stored = canvasNameReserved(name) ? undefined : canvasStore.create(name);
                     payload = JSON.stringify(stored === undefined ? { ok: false, error: 'invalid, roster-reserved name or team cap reached' } : { ok: true, name: stored, teams: canvasStore.list() });
@@ -717,8 +746,15 @@ export function registerAdminFaces(webServer, d) {
                         payload = JSON.stringify({ ok: false, error: 'name and a member (joined session id, or a zone-qualified remote team handle like zone/a1b2c3d4) are required' });
                     }
                     else {
-                        canvasStore.create(name);
-                        payload = JSON.stringify({ ok: canvasStore.addMember(name, id), teams: canvasStore.list(), members: canvasStore.membersOf(name) });
+                        const pin = await d.cliHomeForAdd(id, body.home).catch(() => ({ ok: false, error: 'linked home card lookup failed' }));
+                        if (!pin.ok)
+                            payload = JSON.stringify({ ok: false, error: pin.error });
+                        else {
+                            canvasStore.create(name);
+                            const explicitHome = body.home !== undefined;
+                            const home = explicitHome ? pin.home : canvasStore.cliHomeOf(id) ?? pin.home;
+                            payload = JSON.stringify({ ok: canvasStore.addMember(name, id, home, { replaceHome: explicitHome }), teams: canvasStore.list(), members: canvasStore.membersOf(name) });
+                        }
                     }
                 }
                 else if (action === 'remove-member') {

package/lib/faces/wire.js

@@ -1,4 +1,5 @@
 import { isRemoteMemberRef, validRemoteMemberRef } from "../canvas-store.js";
+import { CLI_HANDLE_RE } from "../cli-deposit.js";
 import { TRANSCRIPT_DEFAULT_LIMIT, TRANSCRIPT_MAX_LIMIT } from "../session-transcript.js";
 import { refuseIfBudgetExhausted } from "../recursion-guard.js";
 import { peerPayloadFingerprint, WIRE_ERROR_IDEMPOTENCY_CONFLICT, WIRE_ERROR_REPLAY_REJECTED } from "../idempotency-store.js";
@@ -74,7 +75,7 @@ export function settlerClaimFields(claim, originOf) {
  * @param d - the captures listed on {@link WireDeps}.
  */
 export function registerWireFaces(webServer, d) {
-    const { ctx, logger, config, cliDeposits, canvasStore, canvasNameReserved, sessionNodes, joinedSessions, idempotencyStore, verifyOriginClaim, callerLinkedToThisHost, recordActivity, secretEqual, a2aCallerRefusal, a2aCallerAdmission, allowlistVersionNow, observeAuthorization, scanSessionLogList, readSessionLogTail, taskLedger, refuseIfFlooded, settleAndAnnounce, session, resolveAgentForTeam, parseCanvasTeamName, canvasLiveAgent, wakeColdTeam, probeConsumption, sessionTeamOf, localSessionOfHandle, steerRelay, fromClause, sanitizeFromClause, armReceiptAutosend, eventCountOf, receiptExpectationOf, armAsyncNudge, liveAgent, callerIsAgent, selfRouteText, noWakeFaceText, archivedColdMatchText, noColdMatchText, nativeTeamsPrepare, nativeTeamsRound, routeIntoAgent, } = d;
+    const { ctx, logger, config, cliDeposits, canvasStore, canvasNameReserved, sessionNodes, joinedSessions, idempotencyStore, verifyOriginClaim, remoteCliProof, callerLinkedToThisHost, recordActivity, secretEqual, a2aCallerRefusal, a2aCallerAdmission, allowlistVersionNow, observeAuthorization, scanSessionLogList, readSessionLogTail, taskLedger, refuseIfFlooded, refuseIfQueueFull, settleAndAnnounce, session, resolveAgentForTeam, parseCanvasTeamName, canvasLiveAgent, wakeColdTeam, probeConsumption, sessionTeamOf, localSessionOfHandle, steerRelay, fromClause, sanitizeFromClause, armReceiptAutosend, eventCountOf, receiptExpectationOf, armAsyncNudge, liveAgent, callerIsAgent, selfRouteText, noWakeFaceText, archivedColdMatchText, noColdMatchText, nativeTeamsPrepare, nativeTeamsRound, routeIntoAgent, } = d;
     // gh#45 CLI 户口卡面 (peer face, unsigned card serve): the deposited
     // CLI's SIGNED card is served verbatim under its own base URL — an
     // OriginClaim verification of a CLI envelope fetches exactly here
@@ -168,11 +169,19 @@ export function registerWireFaces(webServer, d) {
                             // gh#131: a handle is stored as sent, even one of this host's own — the
                             // local tiers read it as the session it names at route time.
                             const memberValid = isRemoteMemberRef(rawId) ? validRemoteMemberRef(rawId) : rawId !== '' && (sessionNodes.has(rawId) || joinedSessions.has(rawId));
-                            payload = !canvasStore.hasTeam(name) && canvasNameReserved(name)
-                                ? { ok: false, error: 'roster reserves this canvas name' }
-                                : name === '' || !memberValid
-                                    ? { ok: false, error: 'name and a member (joined session id, or a zone-qualified remote team handle) are required' }
-                                    : (canvasStore.create(name), { ok: canvasStore.addMember(name, rawId), members: canvasStore.membersOf(name) });
+                            if (!canvasStore.hasTeam(name) && canvasNameReserved(name))
+                                payload = { ok: false, error: 'roster reserves this canvas name' };
+                            else if (name === '' || !memberValid)
+                                payload = { ok: false, error: 'name and a member (joined session id, or a zone-qualified remote team handle) are required' };
+                            else {
+                                // A peer may compose references, never decide this operator's CLI home pin.
+                                if (body.home !== undefined)
+                                    payload = { ok: false, error: 'CLI home pins may only be set by this host local control route' };
+                                else {
+                                    canvasStore.create(name);
+                                    payload = { ok: canvasStore.addMember(name, rawId), members: canvasStore.membersOf(name) };
+                                }
+                            }
                         }
                         else if (op === 'remove-member') {
                             // Either shape may be stored (an older edit kept the handle): remove both (review of PR #151 P2-1).
@@ -484,7 +493,12 @@ export function registerWireFaces(webServer, d) {
                 // (0.6.15: the rule now lives in a2aCallerRefusal so the
                 // read-only /a2a/log face admits callers by exactly the same
                 // standard as message delivery.)
-                const admission = a2aCallerAdmission(caller, team);
+                // F1: only a FOREIGN CLI handle needs a bound host claim and live home card
+                // before admission. Every other caller keeps the existing admission-first order.
+                const foreignCli = config.teamScopeRouting && CLI_HANDLE_RE.test(caller) && cliDeposits.get(caller) === undefined;
+                const earlyClaim = foreignCli ? await verifyOriginClaim(req, { cli: true }) : undefined;
+                const cliProof = foreignCli && earlyClaim?.ok ? await remoteCliProof(caller, earlyClaim).catch(() => undefined) : undefined;
+                const admission = a2aCallerAdmission(caller, team, cliProof);
                 const callerRefusal = refusalOf(admission);
                 if (callerRefusal !== undefined || !admission.ok) {
                     recordActivity('in', team, caller === '' ? 'anonymous' : caller, false);
@@ -504,7 +518,7 @@ export function registerWireFaces(webServer, d) {
                 // after the window closes it rejects like a failed signature —
                 // N3 proves a NAME's linkability, never key possession.
                 // gh#133: the delivery face is where a deposited CLI identity signs its routes.
-                const claim = await verifyOriginClaim(req, { cli: true });
+                const claim = earlyClaim ?? await verifyOriginClaim(req, { cli: true });
                 if (!claim.ok) {
                     if (claim.reason !== 'absent' || config.originClaimWindow === false) {
                         recordActivity('in', team, caller, false);
@@ -518,11 +532,12 @@ export function registerWireFaces(webServer, d) {
                 // A verified claim proves the caller only when its signed zone covers it (review of PR #134 P1),
                 // and the host face only when it was signed from this very host (round 2: a zone name is not an origin).
                 const callerProof = !claim.ok ? 'legacy-window'
-                    : claim.cli === true ? (claimCovers(caller, claim.caller) ? 'cli-identity' : 'claim-mismatch')
-                        : claim.bound !== true ? 'unbound'
-                            : !isRootOriginUrl(claim.callerUrl) ? 'claim-mismatch'
-                                : admission.rule === 'host-face' && originOf(claim.callerUrl) !== originOf(d.ownCardUrl) ? 'claim-mismatch'
-                                    : claimCovers(caller, claim.caller) ? 'origin-claim' : 'claim-mismatch';
+                    : admission.rule === 'remote-ref-cli' ? 'origin-claim'
+                        : claim.cli === true ? (claimCovers(caller, claim.caller) ? 'cli-identity' : 'claim-mismatch')
+                            : claim.bound !== true ? 'unbound'
+                                : !isRootOriginUrl(claim.callerUrl) ? 'claim-mismatch'
+                                    : admission.rule === 'host-face' && originOf(claim.callerUrl) !== originOf(d.ownCardUrl) ? 'claim-mismatch'
+                                        : claimCovers(caller, claim.caller) ? 'origin-claim' : 'claim-mismatch';
                 const proofClause = callerProof === 'origin-claim' && claim.ok ? `已验证来源 ${originOf(claim.callerUrl)}`
                     : callerProof === 'cli-identity' ? '未验证（cli-identity）' : `未验证（${callerProof}）`;
                 const directHeader = (from) => `[A2A direct] (task ${taskId}) ${proofClause} ${sanitizeFromClause(from)} (routed to ${team}) sent:`;
@@ -551,6 +566,8 @@ export function registerWireFaces(webServer, d) {
                 }
                 if (refuseIfFlooded(caller, message, team, taskId, res))
                     return;
+                if (refuseIfQueueFull(caller, message, team, taskId, cliDeposits.get(team) !== undefined, res))
+                    return;
                 // The caller-side receipt correlation: a message shaped as a
                 // receipt resolves the task it echoes, whichever wait semantics
                 // carried it here. Correlation is bookkeeping only — the message
@@ -585,6 +602,17 @@ export function registerWireFaces(webServer, d) {
                 // Inbound routing is foreground demand: boot prewarm yields for a
                 // quiet window around it.
                 d.touchWakeDemand();
+                const forwardMiss = async (original) => {
+                    const result = await d.forwardDirect({ team, message, caller, taskId, contextId, noWait,
+                        localCliProof: claim.ok && claim.cli === true && claim.bound && claim.caller === caller, guarded: req.headers['x-a2a-guard'] !== undefined }).catch((error) => ({ ok: false, error: `forwarding unavailable: ${String(error)}`, code: -32000, task_id: taskId }));
+                    if (!result.ok && result.code !== -32005)
+                        idempotencyStore.recordOutcome(taskId, { status: 'failed', error: original + ' — ' + result.error });
+                    else if (result.ok && result.task_status === 'TASK_STATE_COMPLETED')
+                        idempotencyStore.recordOutcome(taskId, { status: 'completed', reply: result.reply });
+                    const payload = JSON.stringify(result.ok ? { routed: true, ...(result.task_status === 'TASK_STATE_DELIVERED' ? { delivered: true } : { result: { text: result.reply } }), team, task_id: taskId, context_id: contextId, task_status: result.task_status, consumed: result.consumed, bridge: result.bridge, receipt: result.receipt, forwarded: true } : { error: original + ' — ' + result.error, code: result.code ?? -32000, receipt: result.receipt, task_id: taskId, team, task_status: result.code === -32005 ? 'TASK_STATE_DELIVERED' : 'TASK_STATE_FAILED' });
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+                    res.end(payload);
+                };
                 // wait:false delivers without the final-reply hold: steer resolves
                 // synchronously inside routeIntoAgentFor, so by the time the agent
                 // lookup settles the message is already in — answer delivered and
@@ -675,6 +703,7 @@ export function registerWireFaces(webServer, d) {
                                 caller,
                                 proof: callerProof,
                                 ...(claim.ok ? { claim: { caller: claim.caller, origin: originOf(claim.callerUrl) } } : {}),
+                                ...(admission.rule === 'remote-ref-cli' && claim.ok ? { carrierUrl: originOf(claim.callerUrl) } : {}),
                                 ingress: 'wire',
                                 allowlistVersion: admittedAt.version,
                                 target: team,
@@ -702,6 +731,7 @@ export function registerWireFaces(webServer, d) {
                                 task_status: 'TASK_STATE_DELIVERED',
                                 artifacts: [],
                                 consumed: consumedProbe,
+                                ...(req.headers['x-a2a-guard'] !== undefined ? { delivered_to: deliveredTo } : {}),
                                 receipt: receiptExpectation === 'process-label' || deliveredReceipt ? 'none' : 'routed',
                             });
                             res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
@@ -739,7 +769,7 @@ export function registerWireFaces(webServer, d) {
                         // success. Past prepare, the round fires detached (noWait means
                         // delivery, not settlement); its late outcome corrects the
                         // activity ring and the log.
-                        const standardMiss = () => {
+                        const standardMiss = async () => {
                             if (team === config.team) {
                                 const live = liveAgent();
                                 if (live !== undefined) {
@@ -755,6 +785,10 @@ export function registerWireFaces(webServer, d) {
                                     return;
                                 }
                             }
+                            if (wake?.kind === 'no-match') {
+                                await forwardMiss(noColdMatchText(team));
+                                return;
+                            }
                             refuseNoWait(wake?.kind === 'no-face' ? noWakeFaceText(team) : wake?.kind === 'archived' ? archivedColdMatchText(team) : noColdMatchText(team), false);
                         };
                         const prepared = await nativeTeamsPrepare(team);
@@ -763,7 +797,7 @@ export function registerWireFaces(webServer, d) {
                                 refuseNoWait(prepared.error);
                                 return;
                             }
-                            standardMiss();
+                            await standardMiss();
                             return;
                         }
                         recordActivity('in', team, caller, true);
@@ -791,7 +825,11 @@ export function registerWireFaces(webServer, d) {
                     })();
                     return;
                 }
-                void routeIntoAgent(team, message, caller, taskId, proofClause, directHeader).then((outcome) => {
+                void routeIntoAgent(team, message, caller, taskId, proofClause, directHeader).then(async (outcome) => {
+                    if (!outcome.ok && outcome.localMiss) {
+                        await forwardMiss(outcome.error);
+                        return;
+                    }
                     recordActivity('in', team, caller, outcome.ok);
                     // W7 slice-2 hook 1: record the settled outcome on the claim row.
                     // Ruling: a non-COMPLETED status (TASK_STATE_DELIVERED — the
@@ -818,6 +856,7 @@ export function registerWireFaces(webServer, d) {
                             team,
                             session,
                             result: { text: outcome.reply },
+                            ...(req.headers['x-a2a-guard'] !== undefined ? ((target) => target === undefined ? {} : { delivered_to: sessionTeamOf(target) })(resolveAgentForTeam(team) ?? canvasLiveAgent(parseCanvasTeamName(team))) : {}),
                             task_id: taskId,
                             context_id: contextId,
                             task_status: outcome.status ?? 'TASK_STATE_COMPLETED',