@ouro.bot/cli 0.1.0-alpha.989 → 0.1.0-alpha.990

package/dist/a2a/server.js

@@ -58,6 +58,8 @@ const delegation_stores_1 = require("./delegation-stores");
 const task_store_1 = require("./task-store");
 const delegated_command_1 = require("./delegated-command");
 const refusals_1 = require("./refusals");
+const relay_inbox_1 = require("./relay-inbox");
+const relay_retirements_1 = require("./relay-retirements");
 const outbox_wire_1 = require("./outbox-wire");
 const failure_reports_1 = require("../heart/failure-reports");
 const MAX_A2A_REQUEST_BYTES = 128 * 1024;
@@ -143,7 +145,7 @@ function metadataString(message, key) {
     return metadataStringFromRecord(metadataRecord(message), key);
 }
 function headerString(req, key) {
-    const value = req.headers[key];
+    const value = req?.headers[key];
     /* v8 ignore next -- Node lower-cases singular request headers here; array values are defensive compatibility @preserve */
     if (Array.isArray(value))
         return value[0];
@@ -430,6 +432,171 @@ async function startA2AServer(options) {
         }
     };
     let confirmTimer;
+    // The message/send branch as one function, so a sealed message that arrives through the relay inbox runs exactly the
+    // path a direct POST runs. `req` is absent for a relayed message: there are no HTTP headers to take a sender hint from.
+    const handleMessageSend = async (rpc, req) => {
+        const responseStyle = rpc.method === "message/send" ? "legacy" : "latest";
+        const parsedInbound = messageFromParams(rpc.params);
+        const inbound = parsedInbound ? { ...parsedInbound, kind: parsedInbound.kind ?? "message" } : null;
+        // HARNESS-OWNED RESULT WIRE (runs BEFORE the friends-share branch). A
+        // `mission_result`-tagged DataPart is NOT a FriendsKind — it routes to
+        // `importMissionResult` (assignee/correlation-gated, store-only, NO turn), never
+        // to `receiveShare`. Recognized by the `ouroKind` discriminator.
+        if (inbound && inboundShareDeps && (0, mission_result_wire_1.isMissionResultDataPart)(inbound)) {
+            const imported = await (0, mission_result_wire_1.receiveInboundMissionResult)(inbound, {
+                sodium: inboundShareDeps.sodium,
+                store: inboundShareDeps.store,
+                missionStore: inboundShareDeps.missionStore,
+                // The SAME authentication seam the share bridge uses — so a forged-sender
+                // result is rejected by the DidVerifier exactly like a forged share.
+                pinStore: inboundShareDeps.pinStore,
+                seen: inboundShareDeps.seen,
+                didResolution: inboundShareDeps.didResolution,
+                identity: inboundShareDeps.identity,
+            });
+            if (imported.outcome === "rejected") {
+                return refusalResponse(rpc.id, "result", imported.reason);
+            }
+            // imported (store-only, no turn): acknowledge with a minimal completed task.
+            /* v8 ignore next -- "not-a-result" is unreachable here (gated by isMissionResultDataPart) @preserve */
+            const ackText = imported.outcome === "imported"
+                ? `[a2a] imported mission result from ${imported.verifiedDid}`
+                /* v8 ignore next -- defensive: the gate above guarantees imported|rejected @preserve */
+                : "[a2a] mission result";
+            const contextId = inbound.contextId ?? "default";
+            const taskId = (0, node_crypto_1.randomUUID)();
+            const accessToken = (0, node_crypto_1.randomUUID)();
+            const ackTask = taskFor({ taskId, accessToken, contextId, inbound, state: "TASK_STATE_COMPLETED", response: ackText });
+            taskStore.put(ackTask, accessTokenScope(accessToken));
+            return jsonResponse(rpc.id, publicTask(ackTask, accessToken, responseStyle, true));
+        }
+        // Inbound friends-DataPart branch (runs BEFORE the legacy text path). A
+        // sealed DataPart is unwrapped + verified through the bridge; the turn is
+        // then keyed on the VERIFIED sender DID (replacing the unauthenticated
+        // sentinel). A non-friends (text) message falls through unchanged.
+        let verifiedPeerAgentId;
+        let verifiedPeerName;
+        let verifiedShareText;
+        let verifiedChat;
+        if (inbound && inboundShareDeps && messageHasDataPart(inbound)) {
+            const bridged = await (0, inbound_share_1.receiveInboundShare)(inbound, inboundShareDeps);
+            if (bridged.outcome === "rejected") {
+                return refusalResponse(rpc.id, "share", bridged.reason);
+            }
+            // A message with a data part always resolves to completed|rejected — the
+            // bridge only returns "not-a-share" when there is NO data part, which the
+            // `messageHasDataPart` gate above excludes. So this is the completed path.
+            /* v8 ignore next -- "not-a-share" is unreachable here (gated by messageHasDataPart) @preserve */
+            if (bridged.outcome === "completed") {
+                verifiedPeerAgentId = bridged.verifiedDid;
+                verifiedPeerName = bridged.verifiedDid;
+                if (bridged.message) {
+                    // Authenticated chat: the signed, sealed text IS the turn.
+                    verifiedShareText = bridged.message.text;
+                    /* v8 ignore next -- a completed chat always has a friend record: an unknown DID reads as stranger and the message is refused @preserve */
+                    verifiedPeerName = bridged.friend?.name ?? bridged.verifiedDid;
+                    verifiedChat = { did: bridged.verifiedDid, friend: bridged.friend, ...(bridged.message.onBehalfOf ? { onBehalfOf: bridged.message.onBehalfOf } : {}), bindingId: bridged.bindingId, issuedAt: bridged.message.issuedAt };
+                }
+                else {
+                    verifiedShareText = `[a2a] received ${bridged.friendsKind} (${bridged.status}) from ${bridged.verifiedDid}`;
+                }
+            }
+        }
+        const text = verifiedShareText ?? textFromMessage(inbound);
+        if (!inbound || !text) {
+            return errorResponse(rpc.id, -32602, "SendMessage requires a text message");
+        }
+        if (text.length > MAX_A2A_MESSAGE_TEXT_CHARS) {
+            return errorResponse(rpc.id, -32602, `SendMessage text exceeds ${MAX_A2A_MESSAGE_TEXT_CHARS} characters`);
+        }
+        const senderHint = senderHintFromMessage(req, inbound);
+        // The verified DID wins as the turn's peer identity; otherwise the legacy
+        // unauthenticated sentinel (text path, behavior-preserved).
+        const peerAgentId = verifiedPeerAgentId ?? untrustedTurnPeerExternalId();
+        const peerName = verifiedPeerName ?? senderHint.name;
+        const continuationToken = accessTokenFromParams(rpc.params);
+        const continuationTask = inbound.taskId && continuationToken
+            ? taskStore.get(inbound.taskId, accessTokenScope(continuationToken))
+            : null;
+        if (inbound.taskId && continuationToken && (!continuationTask || !taskAuthorized(continuationTask, continuationToken))) {
+            return errorResponse(rpc.id, -32001, "task not found");
+        }
+        if (continuationTask && isTerminalTaskState(continuationTask.status.state)) {
+            return errorResponse(rpc.id, -32002, "task is terminal; start a new task");
+        }
+        const contextId = inbound.contextId ?? continuationTask?.contextId ?? "default";
+        const taskId = continuationTask?.id ?? (0, node_crypto_1.randomUUID)();
+        const accessToken = continuationToken && continuationTask ? continuationToken : (0, node_crypto_1.randomUUID)();
+        const tokenScope = accessTokenScope(accessToken);
+        const clientTaskId = continuationTask ? taskA2AMetadata(continuationTask).clientTaskId : inbound.taskId;
+        let relationshipAuthorization = verifiedChat?.friend
+            ? a2aChatRelationship(agentRoot, verifiedChat.friend, taskId)
+            : undefined;
+        let turnText = text;
+        let delegatedCommand;
+        // Only the server writes the delegated banner. Any turn that is not about to be admitted as a delegated command
+        // (verified or not, including a plain unauthenticated text turn) gets a typed banner marked as the sender's own words.
+        if (verifiedChat?.onBehalfOf !== "principal")
+            turnText = (0, delegated_command_1.shieldDelegatedBanner)(text);
+        if (verifiedChat?.onBehalfOf === "principal") {
+            // A delegated command runs with the principal's authority only after the
+            // server, never the model, has checked the grant and told the principal.
+            let registry;
+            try {
+                registry = (0, relationship_authorization_1.loadRelationshipCapabilityRegistry)(agentRoot);
+            }
+            catch {
+                registry = undefined;
+            }
+            /* v8 ignore next -- a completed chat always carries the sender's friend record (see the receipt above) @preserve */
+            if (!verifiedChat.friend)
+                throw new Error("verified chat has no friend record");
+            const admission = await (0, delegated_command_1.admitDelegatedCommand)({ friend: verifiedChat.friend, did: verifiedChat.did, text, commandId: commandIdFor(verifiedChat), store: inboundShareDeps.store, registry, options: options.delegation });
+            if (!admission.ok) {
+                // The code and the "delegated command refused: <reason>" prefix stay: the replay gate and older CLIs match them.
+                // Only an active family peer is told why: anyone else gets no_grant whatever the real reason was (a broken trust file, a key mismatch), which stays in the local log and nerves.
+                const activeFamily = verifiedChat.friend.trustLevel === "family" && verifiedChat.friend.admissionState === "active";
+                const shown = activeFamily ? admission.reason : "no_grant";
+                const guidance = (0, delegated_command_1.delegationRefusalGuidance)(shown, { legacyRecordGrant: activeFamily && verifiedChat.friend.delegationGrant !== undefined });
+                return errorResponse(rpc.id, -32004, `delegated command refused: ${shown} (${guidance.message}). Nothing ran. Next: ${guidance.next}`, { reason: shown, nothingRan: true, retry: guidance.retry, next: guidance.next });
+            }
+            relationshipAuthorization = admission.relationship;
+            turnText = admission.turnText;
+            delegatedCommand = admission.context;
+        }
+        taskStore.put(taskFor({ taskId, accessToken, contextId, inbound, state: "TASK_STATE_WORKING", clientTaskId, previousTask: continuationTask ?? undefined }), tokenScope);
+        const turn = await turnRunner({
+            agentName: options.agentName,
+            peerAgentId,
+            peerName,
+            sessionKey: contextId,
+            message: turnText,
+            ...(relationshipAuthorization ? { relationshipAuthorization } : {}),
+            ...(delegatedCommand ? { delegatedCommand } : {}),
+        });
+        let responseParts;
+        if (verifiedChat) {
+            // A verified chat's reply is sealed to the sender and stored sealed, so neither
+            // the wire nor a later GetTask ever carries the plaintext.
+            const pinned = inboundShareDeps.pinStore.get(verifiedChat.did);
+            /* v8 ignore next 4 -- receiveShare pins the verified sender before it reports a completed chat; refuse rather than reply in plaintext @preserve */
+            if (!pinned) {
+                return errorResponse(rpc.id, -32003, "A2A chat reply cannot be sealed to the sender");
+            }
+            responseParts = (0, sealed_chat_1.sealChatMessage)({
+                sodium: inboundShareDeps.sodium,
+                from: options.identity,
+                recipientDid: verifiedChat.did,
+                recipientEd25519Pub: pinned.ed25519Pub,
+                text: turn.response,
+                conversationId: contextId,
+            }).parts;
+        }
+        const task = taskFor({ taskId, accessToken, contextId, inbound, state: "TASK_STATE_COMPLETED", response: turn.response, responseParts, clientTaskId, previousTask: continuationTask ?? undefined });
+        taskStore.put(task, tokenScope);
+        return jsonResponse(rpc.id, publicTask(task, accessToken, responseStyle, true));
+    };
+    let relayInbox;
     let publicBaseUrl = options.baseUrl;
     const server = http.createServer(async (req, res) => {
         /* v8 ignore next -- Node always supplies url/host for accepted HTTP requests; fallback keeps malformed local calls safe @preserve */
@@ -484,7 +651,11 @@ async function startA2AServer(options) {
                     writeJson(res, 200, errorResponse(rpc.id, outbox_wire_1.OUTBOX_ERROR_INVALID, "the signed method does not match the requested method"));
                     return;
                 }
-                const outcome = await (0, outbox_wire_1.handleOutboxCommand)({ agentRoot, friend: bridged.friend, method: command.method, params: command.params, verifiedDid: bridged.verifiedDid });
+                const ownRelay = relayInbox?.registration();
+                const outcome = await (0, outbox_wire_1.handleOutboxCommand)({
+                    agentRoot, friend: bridged.friend, method: command.method, params: command.params, verifiedDid: bridged.verifiedDid,
+                    relayContact: ownRelay ? { url: ownRelay.relayUrl, handle: ownRelay.handle, sendCredential: ownRelay.sendCredential } : null,
+                });
                 if (!outcome.ok) {
                     writeJson(res, 200, errorResponse(rpc.id, outcome.code, outcome.message));
                     return;
@@ -506,175 +677,7 @@ async function startA2AServer(options) {
                 return;
             }
             if (rpc.method === "SendMessage" || rpc.method === "message/send") {
-                const responseStyle = rpc.method === "message/send" ? "legacy" : "latest";
-                const parsedInbound = messageFromParams(rpc.params);
-                const inbound = parsedInbound ? { ...parsedInbound, kind: parsedInbound.kind ?? "message" } : null;
-                // HARNESS-OWNED RESULT WIRE (runs BEFORE the friends-share branch). A
-                // `mission_result`-tagged DataPart is NOT a FriendsKind — it routes to
-                // `importMissionResult` (assignee/correlation-gated, store-only, NO turn), never
-                // to `receiveShare`. Recognized by the `ouroKind` discriminator.
-                if (inbound && inboundShareDeps && (0, mission_result_wire_1.isMissionResultDataPart)(inbound)) {
-                    const imported = await (0, mission_result_wire_1.receiveInboundMissionResult)(inbound, {
-                        sodium: inboundShareDeps.sodium,
-                        store: inboundShareDeps.store,
-                        missionStore: inboundShareDeps.missionStore,
-                        // The SAME authentication seam the share bridge uses — so a forged-sender
-                        // result is rejected by the DidVerifier exactly like a forged share.
-                        pinStore: inboundShareDeps.pinStore,
-                        seen: inboundShareDeps.seen,
-                        didResolution: inboundShareDeps.didResolution,
-                        identity: inboundShareDeps.identity,
-                    });
-                    if (imported.outcome === "rejected") {
-                        writeJson(res, 200, refusalResponse(rpc.id, "result", imported.reason));
-                        return;
-                    }
-                    // imported (store-only, no turn): acknowledge with a minimal completed task.
-                    /* v8 ignore next -- "not-a-result" is unreachable here (gated by isMissionResultDataPart) @preserve */
-                    const ackText = imported.outcome === "imported"
-                        ? `[a2a] imported mission result from ${imported.verifiedDid}`
-                        /* v8 ignore next -- defensive: the gate above guarantees imported|rejected @preserve */
-                        : "[a2a] mission result";
-                    const contextId = inbound.contextId ?? "default";
-                    const taskId = (0, node_crypto_1.randomUUID)();
-                    const accessToken = (0, node_crypto_1.randomUUID)();
-                    const ackTask = taskFor({ taskId, accessToken, contextId, inbound, state: "TASK_STATE_COMPLETED", response: ackText });
-                    taskStore.put(ackTask, accessTokenScope(accessToken));
-                    writeJson(res, 200, jsonResponse(rpc.id, publicTask(ackTask, accessToken, responseStyle, true)));
-                    return;
-                }
-                // Inbound friends-DataPart branch (runs BEFORE the legacy text path). A
-                // sealed DataPart is unwrapped + verified through the bridge; the turn is
-                // then keyed on the VERIFIED sender DID (replacing the unauthenticated
-                // sentinel). A non-friends (text) message falls through unchanged.
-                let verifiedPeerAgentId;
-                let verifiedPeerName;
-                let verifiedShareText;
-                let verifiedChat;
-                if (inbound && inboundShareDeps && messageHasDataPart(inbound)) {
-                    const bridged = await (0, inbound_share_1.receiveInboundShare)(inbound, inboundShareDeps);
-                    if (bridged.outcome === "rejected") {
-                        writeJson(res, 200, refusalResponse(rpc.id, "share", bridged.reason));
-                        return;
-                    }
-                    // A message with a data part always resolves to completed|rejected — the
-                    // bridge only returns "not-a-share" when there is NO data part, which the
-                    // `messageHasDataPart` gate above excludes. So this is the completed path.
-                    /* v8 ignore next -- "not-a-share" is unreachable here (gated by messageHasDataPart) @preserve */
-                    if (bridged.outcome === "completed") {
-                        verifiedPeerAgentId = bridged.verifiedDid;
-                        verifiedPeerName = bridged.verifiedDid;
-                        if (bridged.message) {
-                            // Authenticated chat: the signed, sealed text IS the turn.
-                            verifiedShareText = bridged.message.text;
-                            /* v8 ignore next -- a completed chat always has a friend record: an unknown DID reads as stranger and the message is refused @preserve */
-                            verifiedPeerName = bridged.friend?.name ?? bridged.verifiedDid;
-                            verifiedChat = { did: bridged.verifiedDid, friend: bridged.friend, ...(bridged.message.onBehalfOf ? { onBehalfOf: bridged.message.onBehalfOf } : {}), bindingId: bridged.bindingId, issuedAt: bridged.message.issuedAt };
-                        }
-                        else {
-                            verifiedShareText = `[a2a] received ${bridged.friendsKind} (${bridged.status}) from ${bridged.verifiedDid}`;
-                        }
-                    }
-                }
-                const text = verifiedShareText ?? textFromMessage(inbound);
-                if (!inbound || !text) {
-                    writeJson(res, 200, errorResponse(rpc.id, -32602, "SendMessage requires a text message"));
-                    return;
-                }
-                if (text.length > MAX_A2A_MESSAGE_TEXT_CHARS) {
-                    writeJson(res, 200, errorResponse(rpc.id, -32602, `SendMessage text exceeds ${MAX_A2A_MESSAGE_TEXT_CHARS} characters`));
-                    return;
-                }
-                const senderHint = senderHintFromMessage(req, inbound);
-                // The verified DID wins as the turn's peer identity; otherwise the legacy
-                // unauthenticated sentinel (text path, behavior-preserved).
-                const peerAgentId = verifiedPeerAgentId ?? untrustedTurnPeerExternalId();
-                const peerName = verifiedPeerName ?? senderHint.name;
-                const continuationToken = accessTokenFromParams(rpc.params);
-                const continuationTask = inbound.taskId && continuationToken
-                    ? taskStore.get(inbound.taskId, accessTokenScope(continuationToken))
-                    : null;
-                if (inbound.taskId && continuationToken && (!continuationTask || !taskAuthorized(continuationTask, continuationToken))) {
-                    writeJson(res, 200, errorResponse(rpc.id, -32001, "task not found"));
-                    return;
-                }
-                if (continuationTask && isTerminalTaskState(continuationTask.status.state)) {
-                    writeJson(res, 200, errorResponse(rpc.id, -32002, "task is terminal; start a new task"));
-                    return;
-                }
-                const contextId = inbound.contextId ?? continuationTask?.contextId ?? "default";
-                const taskId = continuationTask?.id ?? (0, node_crypto_1.randomUUID)();
-                const accessToken = continuationToken && continuationTask ? continuationToken : (0, node_crypto_1.randomUUID)();
-                const tokenScope = accessTokenScope(accessToken);
-                const clientTaskId = continuationTask ? taskA2AMetadata(continuationTask).clientTaskId : inbound.taskId;
-                let relationshipAuthorization = verifiedChat?.friend
-                    ? a2aChatRelationship(agentRoot, verifiedChat.friend, taskId)
-                    : undefined;
-                let turnText = text;
-                let delegatedCommand;
-                // Only the server writes the delegated banner. Any turn that is not about to be admitted as a delegated command
-                // (verified or not, including a plain unauthenticated text turn) gets a typed banner marked as the sender's own words.
-                if (verifiedChat?.onBehalfOf !== "principal")
-                    turnText = (0, delegated_command_1.shieldDelegatedBanner)(text);
-                if (verifiedChat?.onBehalfOf === "principal") {
-                    // A delegated command runs with the principal's authority only after the
-                    // server, never the model, has checked the grant and told the principal.
-                    let registry;
-                    try {
-                        registry = (0, relationship_authorization_1.loadRelationshipCapabilityRegistry)(agentRoot);
-                    }
-                    catch {
-                        registry = undefined;
-                    }
-                    /* v8 ignore next -- a completed chat always carries the sender's friend record (see the receipt above) @preserve */
-                    if (!verifiedChat.friend)
-                        throw new Error("verified chat has no friend record");
-                    const admission = await (0, delegated_command_1.admitDelegatedCommand)({ friend: verifiedChat.friend, did: verifiedChat.did, text, commandId: commandIdFor(verifiedChat), store: inboundShareDeps.store, registry, options: options.delegation });
-                    if (!admission.ok) {
-                        // The code and the "delegated command refused: <reason>" prefix stay: the replay gate and older CLIs match them.
-                        // Only an active family peer is told why: anyone else gets no_grant whatever the real reason was (a broken trust file, a key mismatch), which stays in the local log and nerves.
-                        const activeFamily = verifiedChat.friend.trustLevel === "family" && verifiedChat.friend.admissionState === "active";
-                        const shown = activeFamily ? admission.reason : "no_grant";
-                        const guidance = (0, delegated_command_1.delegationRefusalGuidance)(shown, { legacyRecordGrant: activeFamily && verifiedChat.friend.delegationGrant !== undefined });
-                        writeJson(res, 200, errorResponse(rpc.id, -32004, `delegated command refused: ${shown} (${guidance.message}). Nothing ran. Next: ${guidance.next}`, { reason: shown, nothingRan: true, retry: guidance.retry, next: guidance.next }));
-                        return;
-                    }
-                    relationshipAuthorization = admission.relationship;
-                    turnText = admission.turnText;
-                    delegatedCommand = admission.context;
-                }
-                taskStore.put(taskFor({ taskId, accessToken, contextId, inbound, state: "TASK_STATE_WORKING", clientTaskId, previousTask: continuationTask ?? undefined }), tokenScope);
-                const turn = await turnRunner({
-                    agentName: options.agentName,
-                    peerAgentId,
-                    peerName,
-                    sessionKey: contextId,
-                    message: turnText,
-                    ...(relationshipAuthorization ? { relationshipAuthorization } : {}),
-                    ...(delegatedCommand ? { delegatedCommand } : {}),
-                });
-                let responseParts;
-                if (verifiedChat) {
-                    // A verified chat's reply is sealed to the sender and stored sealed, so neither
-                    // the wire nor a later GetTask ever carries the plaintext.
-                    const pinned = inboundShareDeps.pinStore.get(verifiedChat.did);
-                    /* v8 ignore next 4 -- receiveShare pins the verified sender before it reports a completed chat; refuse rather than reply in plaintext @preserve */
-                    if (!pinned) {
-                        writeJson(res, 200, errorResponse(rpc.id, -32003, "A2A chat reply cannot be sealed to the sender"));
-                        return;
-                    }
-                    responseParts = (0, sealed_chat_1.sealChatMessage)({
-                        sodium: inboundShareDeps.sodium,
-                        from: options.identity,
-                        recipientDid: verifiedChat.did,
-                        recipientEd25519Pub: pinned.ed25519Pub,
-                        text: turn.response,
-                        conversationId: contextId,
-                    }).parts;
-                }
-                const task = taskFor({ taskId, accessToken, contextId, inbound, state: "TASK_STATE_COMPLETED", response: turn.response, responseParts, clientTaskId, previousTask: continuationTask ?? undefined });
-                taskStore.put(task, tokenScope);
-                writeJson(res, 200, jsonResponse(rpc.id, publicTask(task, accessToken, responseStyle, true)));
+                writeJson(res, 200, await handleMessageSend(rpc, req));
                 return;
             }
             if (rpc.method === "GetTask" || rpc.method === "tasks/get") {
@@ -759,6 +762,19 @@ async function startA2AServer(options) {
         confirmTimer = setInterval(() => { void confirmReports(); }, options.escalation.confirmIntervalMs ?? exports.ESCALATION_CONFIRM_INTERVAL_MS);
         confirmTimer.unref();
     }
+    if (options.relay && inboundShareDeps) {
+        const seen = inboundShareDeps.seen;
+        relayInbox = (0, relay_inbox_1.startRelayInbox)({
+            ...options.relay,
+            // Each old relay's failure clock, and a retirement waiting only for its vault write, survive a restart here.
+            retirements: (0, relay_retirements_1.fileRelayRetirements)(agentRoot),
+            did: inboundShareDeps.identity.did,
+            agentName: options.agentName,
+            handle: (rpc) => handleMessageSend(rpc),
+            // Asked only after a handler throws: was this copy verified (and so recorded) before it failed?
+            seen: seen.has.bind(seen),
+        });
+    }
     (0, runtime_1.emitNervesEvent)({
         component: "channels",
         event: "channel.a2a_server_started",
@@ -769,9 +785,11 @@ async function startA2AServer(options) {
         server,
         url: publicBaseUrl,
         endpointUrl: endpointUrl.toString(),
+        ...(relayInbox ? { relay: relayInbox } : {}),
         close: () => new Promise((resolve, reject) => {
             if (confirmTimer)
                 clearInterval(confirmTimer);
+            relayInbox?.stop();
             server.close((error) => {
                 if (error) {
                     reject(error);

package/dist/a2a/transport.js

@@ -3,43 +3,98 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeA2ATransport = makeA2ATransport;
 const runtime_1 = require("../nerves/runtime");
 const client_1 = require("./client");
-/** The not-wired marker for the relay/mailbox rungs (the stubbed seam). */
-const RELAY_NOT_WIRED = "A2A relay/mailbox transport is not wired — see ourostack/friends-relay";
+const relay_client_1 = require("./relay-client");
+/** Failures that prove the request never reached the peer's agent. */
+const NOT_SENT_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "UND_ERR_CONNECT_TIMEOUT"]);
+function causeCodes(error) {
+    const cause = error.cause;
+    const codes = [cause?.code, ...(cause?.errors ?? []).map((inner) => inner.code)];
+    return codes.filter((code) => typeof code === "string");
+}
+/** Gateway answers that can come after the request reached the agent: a bad gateway after the agent failed mid-turn,
+ * a gateway timeout, and Cloudflare's origin errors and timeouts. */
+const MAY_HAVE_ARRIVED_STATUSES = new Set([502, 504, 520, 521, 522, 523, 524]);
+/** True when the direct attempt certainly did not reach the agent: a refused or unroutable connection, or a reply from
+ * something other than the agent (a tunnel or proxy page, except a gateway answer that can follow a delivery). */
+function certainlyNotArrived(error) {
+    if (error instanceof client_1.A2AHttpStatusError)
+        return !MAY_HAVE_ARRIVED_STATUSES.has(error.status);
+    /* v8 ignore next -- fetch only throws Error instances @preserve */
+    if (!(error instanceof Error))
+        return false;
+    const codes = causeCodes(error);
+    return codes.length > 0 && codes.every((code) => NOT_SENT_CODES.has(code));
+}
+/** The not-wired marker for rungs friends may name but the harness does not deliver on (the git mailbox). */
+const NOT_WIRED = "A2A transport is not wired for this rung; the harness delivers direct, with the peer's friends-relay inbox as the fallback";
+function describe(error) {
+    /* v8 ignore next -- fetch and the relay client only throw Error instances @preserve */
+    if (!(error instanceof Error))
+        return String(error);
+    const code = error.cause?.code;
+    return typeof code === "string" ? `${error.message} (${code})` : error.message;
+}
 /**
- * Build the harness `A2ATransport` (the outbound delivery seam friends' `sendShare`
- * calls). Only the `direct` rung is wired in this slice: it HTTP-POSTs the sealed,
- * `wrapInDataPart`-wrapped message to the peer's `endpointUrl` (the `address`) as a
- * JSON-RPC `message/send`, reusing the harness `client.ts` plumbing. The `relay` and
- * `mailbox` rungs are a TYPED-but-STUBBED seam: they throw a clear not-wired error
- * naming the `ourostack/friends-relay` dependency, so a future relay slice has an
- * exact insertion point without this slice shipping an untrusted relay.
+ * Build the harness `A2ATransport` (the outbound seam friends' `sendShare` calls). The direct rung HTTP-POSTs the
+ * sealed message to the peer's endpoint as a JSON-RPC `message/send`. A JSON-RPC answer, result or error, means the
+ * peer was reached and decided. Anything else (a refused connection, a timeout, a tunnel or proxy page) means the
+ * peer is not there, and the SAME sealed message is queued at the peer's relay inbox, if the peer shared one. Sending
+ * identical bytes is what makes a double delivery harmless: the peer's seen ledger rejects the second copy.
  */
 function makeA2ATransport(input = {}) {
     return {
         async send(target, message) {
-            if (target.rung === "direct") {
+            if (target.rung !== "direct") {
                 (0, runtime_1.emitNervesEvent)({
                     component: "channels",
-                    event: "channel.a2a_transport_direct_send",
-                    message: "delivering sealed A2A message over the direct rung",
-                    meta: { address: target.address },
+                    event: "channel.a2a_transport_not_wired",
+                    message: "refused A2A transport over a rung the harness does not deliver on",
+                    meta: { rung: target.rung, address: target.address },
                 });
+                throw new Error(`${NOT_WIRED} (rung: ${target.rung})`);
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_transport_direct_send",
+                message: "delivering sealed A2A message over the direct rung",
+                meta: { address: target.address },
+            });
+            let directError;
+            try {
                 await (0, client_1.postA2AMessageEnvelope)({
                     endpointUrl: target.address,
                     message,
                     ...(input.fetchImpl ? { fetchImpl: input.fetchImpl } : {}),
                 });
+                input.onDelivered?.("direct");
                 return;
             }
-            // relay / mailbox: the typed-but-stubbed seam. Loud refusal (security-relevant:
-            // we never silently fall through to an untrusted relay).
+            catch (error) {
+                if (error instanceof client_1.A2ARpcError)
+                    throw error;
+                directError = error;
+            }
+            const contact = input.relayContact;
+            if (!contact) {
+                const fate = certainlyNotArrived(directError) ? "it was not delivered" : "it may not have been delivered";
+                throw new Error(`${describe(directError)}; ${fate}, and the peer has shared no relay contact to queue it for later`);
+            }
             (0, runtime_1.emitNervesEvent)({
                 component: "channels",
-                event: "channel.a2a_transport_not_wired",
-                message: "refused A2A transport over a non-direct rung (not wired)",
-                meta: { rung: target.rung, address: target.address, dependency: "ourostack/friends-relay" },
+                event: "channel.a2a_transport_relay_fallback",
+                message: "peer not reachable directly; queuing the sealed A2A message at its relay",
+                meta: { address: target.address, relayUrl: contact.url, directError: describe(directError) },
             });
-            throw new Error(`${RELAY_NOT_WIRED} (rung: ${target.rung})`);
+            try {
+                await (0, relay_client_1.relaySend)({ url: contact.url, handle: contact.handle, sendCredential: contact.sendCredential, message, fetchImpl: input.fetchImpl });
+            }
+            catch (error) {
+                if (error instanceof relay_client_1.RelayHttpError && [401, 403, 404].includes(error.status))
+                    input.onRelayContactRefused?.();
+                const fate = certainlyNotArrived(directError) ? "the message was not delivered" : "the message may not have been delivered";
+                throw new Error(`peer not reachable directly (${describe(directError)}) or through its relay (${describe(error)}); ${fate}`);
+            }
+            input.onDelivered?.("relay", { directMayHaveArrived: !certainlyNotArrived(directError) });
         },
     };
 }

package/dist/repertoire/guardrails.js

@@ -71,6 +71,10 @@ const PROTECTED_PATH_SEGMENTS = [
     "state/policy/",
     // The pre-trust-directory home of the escalation grants; the file is no longer read, and a model must not recreate it.
     "state/a2a/escalation-grants.json",
+    // Where to queue mail for offline peers; a model that rewrote a contact could send a peer's mail to its own relay.
+    "state/a2a/relay-contacts/",
+    // Relay retirements awaiting their vault write; a forged marker would skip draining an old relay inbox.
+    "state/a2a/relay-retired/",
     "state/outbox/",
     "state/reports/",
 ];