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

package/changelog.json

@@ -1,6 +1,17 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.990",
+      "changes": [
+        "An agent can now reach a friend that is offline. A sealed A2A message goes direct first; if the friend does not answer, the same sealed message is queued at the friend's friends-relay inbox and the friend handles it when it comes back, through the same checks as a direct message. The relay only holds ciphertext.",
+        "An agent learns where to queue mail for a friend by asking it over a sealed call after a direct message goes through; only active friend or family peers get the answer. The tools say when a message, delegation or result was queued rather than delivered, and when a failed direct attempt may still have arrived.",
+        "A sender keeps a friend's relay contact only when the friend's own DID answered with it, and counts a message as queued only when the relay returns a queue id. An agent moved to another relay drains the old inbox until it is empty before removing it, and a move never waits for an older relay.",
+        "To make an agent reachable while offline, set `a2a.relay.url` and `a2a.relay.inviteToken` in its machine vault config and restart; the A2A sense registers, keeps the registration in the vault and polls the inbox. To stop waiting for every old relay at once after a move, set `a2a.relay.previousRegistrations` to an empty value. See docs/a2a-relay.md.",
+        "Compatibility: agents without a relay behave as before. A peer on an older harness refuses the contact request; that is cached as no relay and asked again a day later.",
+        "Fixes: an old relay no longer holds up a move. The agent retires it once the relay itself says it no longer knows the agent, or once attempts on it have failed for more than 7 days in a row; one failed attempt never deletes its credentials or tells the owner anything was lost. Relay requests time out after 30 seconds, and a relay answer that is not the relay's JSON counts as a failure, not an empty inbox. The inbox keeps running when the settings could not be read for retiring. A direct reply that is not a JSON-RPC answer to the message now counts as not delivered, so the relay is tried. A broken entry in the inbox no longer stops the messages behind it, a peer whose contact request fails is asked again only once a day, and the setup recipe now prompts for the invite instead of putting it on the command line. Each old-relay retirement record the agent writes is now logged, with the relay address but never its credentials."
+      ]
+    },
     {
       "version": "0.1.0-alpha.989",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.989",
+  "runtimeVersion": "0.1.0-alpha.990",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.989</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.990</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/a2a/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.A2ARpcError = void 0;
+exports.A2AHttpStatusError = exports.A2ARpcError = void 0;
 exports.cardDid = cardDid;
 exports.endpointForCard = endpointForCard;
 exports.fetchA2AAgentCard = fetchA2AAgentCard;
@@ -70,16 +70,48 @@ class A2ARpcError extends Error {
     }
 }
 exports.A2ARpcError = A2ARpcError;
-async function postJsonRpc(endpointUrl, request, fetchImpl, protocolVersion = "1.0") {
+/**
+ * POST one JSON-RPC request. `strict` (the sealed delivery path) accepts a 2xx reply only when it is a JSON-RPC response
+ * to this request (`jsonrpc: "2.0"`, the same id, a result or an error); anything else (`{}`, a parked-domain page,
+ * another service on the same host) throws `A2AHttpStatusError`, because the peer was not reached.
+ */
+async function postJsonRpc(endpointUrl, request, fetchImpl, protocolVersion = "1.0", options = {}) {
     const response = await fetchImpl(endpointUrl, {
         method: "POST",
         headers: { "content-type": "application/json", "A2A-Version": protocolVersion },
         body: JSON.stringify(request),
     });
     if (!response.ok) {
-        throw new Error(`A2A JSON-RPC request failed (${response.status} ${response.statusText})`);
+        // A JSON-RPC body on a non-2xx status is still the peer's answer (the server sends 400 and 413 that way).
+        const answer = parseJsonRpcEnvelope(await response.text().catch(() => ""));
+        if (answer)
+            return answer;
+        throw new A2AHttpStatusError(response.status, response.statusText);
+    }
+    if (!options.strict)
+        return await response.json();
+    const answer = parseJsonRpcEnvelope(await response.text());
+    if (!answer || answer.id !== request.id)
+        throw new A2AHttpStatusError(response.status, `${response.statusText}, not a JSON-RPC answer`);
+    return answer;
+}
+/** A non-2xx HTTP reply that is not a JSON-RPC answer: something other than the agent (a tunnel, a proxy) replied. */
+class A2AHttpStatusError extends Error {
+    status;
+    constructor(status, statusText) {
+        super(`A2A JSON-RPC request failed (${status} ${statusText})`);
+        this.status = status;
+    }
+}
+exports.A2AHttpStatusError = A2AHttpStatusError;
+function parseJsonRpcEnvelope(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && parsed.jsonrpc === "2.0" && ("error" in parsed || "result" in parsed) ? parsed : null;
+    }
+    catch {
+        return null;
     }
-    return await response.json();
 }
 function methodNotFound(response) {
     return "error" in response && response.error.code === -32601;
@@ -166,9 +198,9 @@ async function postA2AMessageEnvelope(input) {
         message: "posting sealed A2A message envelope (direct rung)",
         meta: { endpointUrl: input.endpointUrl },
     });
-    let rpc = await postJsonRpc(input.endpointUrl, request, fetchImpl, "0.3");
+    let rpc = await postJsonRpc(input.endpointUrl, request, fetchImpl, "0.3", { strict: true });
     if (methodNotFound(rpc)) {
-        rpc = await postJsonRpc(input.endpointUrl, { ...request, method: "SendMessage" }, fetchImpl);
+        rpc = await postJsonRpc(input.endpointUrl, { ...request, method: "SendMessage" }, fetchImpl, "1.0", { strict: true });
     }
     if ("error" in rpc) {
         throw new A2ARpcError(rpc.error);

package/dist/a2a/outbox-client.js

@@ -19,6 +19,8 @@ async function callOutboxMethod(input) {
     const peerDid = (0, client_1.cardDid)(card);
     if (!peerDid)
         throw new Error(`A2A card ${input.cardUrl} serves no DID; outbox calls need one`);
+    if (input.expectedDid && peerDid !== input.expectedDid)
+        throw new Error(`A2A card ${input.cardUrl} serves ${peerDid}, not ${input.expectedDid}`);
     const parsed = (0, a2a_client_1.parseDidKey)(peerDid);
     if (!parsed || !(0, a2a_client_1.verifyCardDidBinding)({ card: { did: peerDid, url: input.cardUrl }, did: peerDid, didDoc: null })) {
         throw new Error(`A2A card↔DID binding failed for ${peerDid}`);

package/dist/a2a/outbox-wire.js

@@ -21,8 +21,9 @@ const runtime_1 = require("../nerves/runtime");
  *   outbox/list     { since?: string, limit?: number }  -> { entries, nextCursor, more }       any active friend, own outbox
  *   outbox/ack      { ids: string[] }                    -> { acked, unknown }                  any active friend, own outbox
  *   report/resolve  { id, version, note, resolvedAt, proof }             -> { id, status: "resolved" }          escalation holders, own reports
+ *   relay/contact   {}                                   -> { contact: { url, handle, sendCredential } | null }   active friend or family
  */
-exports.OUTBOX_METHODS = ["outbox/list", "outbox/ack", "report/resolve"];
+exports.OUTBOX_METHODS = ["outbox/list", "outbox/ack", "report/resolve", "relay/contact"];
 exports.OUTBOX_ERROR_REFUSED = -32003;
 exports.OUTBOX_ERROR_INVALID = -32602;
 const MAX_ACK_IDS = 100;
@@ -59,6 +60,16 @@ async function handleOutboxCommand(input) {
         (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_outbox_refused", message: "refused an outbox call from a peer that is not an active friend", meta: { method, friendId: friend?.id ?? null } });
         return refuse("only an active friend can use its outbox");
     }
+    if (method === "relay/contact") {
+        // The send credential lets its holder queue messages here, so only peers trusted as friend or family get it.
+        if (friend.trustLevel !== "friend" && friend.trustLevel !== "family") {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_relay_contact_refused", message: "refused relay/contact to a peer below friend trust", meta: { friendId: friend.id, trustLevel: friend.trustLevel ?? null } });
+            return refuse("relay/contact needs friend or family trust");
+        }
+        const contact = input.relayContact ?? null;
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_relay_contact_shared", message: "answered relay/contact", meta: { friendId: friend.id, hasRelay: contact !== null } });
+        return { ok: true, result: { contact: contact ? { url: contact.url, handle: contact.handle, sendCredential: contact.sendCredential } : null } };
+    }
     const outbox = new outbox_store_1.FileOutboxStore(agentRoot);
     if (method === "outbox/list") {
         const { since, limit } = params;

package/dist/a2a/refusals.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.receiveRefusal = receiveRefusal;
 exports.receiveRefusalError = receiveRefusalError;
+exports.isRetryableReceiveRefusal = isRetryableReceiveRefusal;
 const runtime_1 = require("../nerves/runtime");
 const UPGRADE = "Upgrade the sending agent's harness (ouro) and send again.";
 const RESEND = "Send it again as a new message.";
@@ -35,9 +36,18 @@ const UNKNOWN = { message: "the message was refused", next: "Check the agent's l
 function receiveRefusal(reason) {
     return Object.hasOwn(REFUSALS, reason) ? REFUSALS[reason] : UNKNOWN;
 }
+/** Every `data` object `receiveRefusalError` made in this process, so a caller can tell a real receive refusal from an
+ * error that only looks like one (a delegated-command refusal also carries `retry`). */
+const ISSUED = new WeakSet();
 /** The JSON-RPC error text and data for a refused inbound message: `A2A <what> rejected: <reason>. <message>. Next: <next>`. */
 function receiveRefusalError(what, reason) {
     const refusal = receiveRefusal(reason);
     (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_receive_refused", message: "refused an inbound A2A message", meta: { what, reason, retry: refusal.retry } });
-    return { message: `A2A ${what} rejected: ${reason}. ${refusal.message}. Next: ${refusal.next}`, data: { reason, retry: refusal.retry, next: refusal.next } };
+    const data = { reason, retry: refusal.retry, next: refusal.next };
+    ISSUED.add(data);
+    return { message: `A2A ${what} rejected: ${reason}. ${refusal.message}. Next: ${refusal.next}`, data };
+}
+/** True only for the `data` of a refusal made here that says the same message can succeed later (such as `in_flight`). */
+function isRetryableReceiveRefusal(data) {
+    return typeof data === "object" && data !== null && ISSUED.has(data) && data.retry === true;
 }

package/dist/a2a/relay-client.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAY_REQUEST_TIMEOUT_MS = exports.RelayHttpError = void 0;
+exports.relayRegister = relayRegister;
+exports.relaySend = relaySend;
+exports.relayPull = relayPull;
+exports.relayAck = relayAck;
+exports.relayDeregister = relayDeregister;
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The four friends-relay calls the harness makes (ourostack/friends-relay `src/server/http.ts`): register a handle,
+ * send an opaque sealed message to a handle, pull a handle's inbox and ack one queued message. The relay is untrusted
+ * and content-blind: it only ever carries the sealed A2A message, byte for byte. Every non-2xx answer throws a
+ * `RelayHttpError` carrying the relay's status and error code. A 2xx answer that is not a JSON object (the relay
+ * always answers one), and a request with no answer within `RELAY_REQUEST_TIMEOUT_MS`, throw too.
+ */
+class RelayHttpError extends Error {
+    status;
+    code;
+    /** The answer was the relay's own JSON error (`{ error: "<code>" }`), not a proxy's or a load balancer's page. */
+    fromRelay;
+    constructor(status, code, fromRelay = false) {
+        super(`relay ${status} ${code}`);
+        this.status = status;
+        this.code = code;
+        this.fromRelay = fromRelay;
+    }
+}
+exports.RelayHttpError = RelayHttpError;
+exports.RELAY_REQUEST_TIMEOUT_MS = 30_000;
+async function relayRequest(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const headers = { "content-type": "application/json" };
+    if (input.bearer)
+        headers.authorization = `Bearer ${input.bearer}`;
+    const response = await fetchImpl(`${input.url.replace(/\/+$/, "")}${input.path}`, {
+        method: input.method,
+        headers,
+        ...(input.body === undefined ? {} : { body: JSON.stringify(input.body) }),
+        signal: AbortSignal.timeout(input.timeoutMs ?? exports.RELAY_REQUEST_TIMEOUT_MS),
+    });
+    const parsed = await response.json().catch(() => undefined);
+    const payload = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+    if (!response.ok) {
+        const fromRelay = typeof payload?.error === "string";
+        const code = fromRelay ? payload.error : "error";
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "channels", event: "channel.a2a_relay_http_error", message: "the A2A relay refused a request", meta: { path: input.path.split("/")[1], status: response.status, code } });
+        throw new RelayHttpError(response.status, code, fromRelay);
+    }
+    if (!payload)
+        throw new Error(`the relay answered ${response.status} without its JSON body`);
+    return payload;
+}
+/** Register (or re-register, which rotates both credentials) `handle` for `did`. */
+async function relayRegister(input) {
+    const grant = await relayRequest({
+        ...input,
+        method: "POST",
+        path: "/register",
+        body: { handle: input.handle, did: input.did, agentCard: input.agentCard, ...(input.inviteToken ? { inviteToken: input.inviteToken } : {}) },
+    });
+    if (typeof grant.inboxAuth !== "string" || typeof grant.sendCredential !== "string")
+        throw new Error("relay registration returned no credentials");
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_relay_registered", message: "registered an A2A relay inbox", meta: { relayUrl: input.url } });
+    return { handle: input.handle, inboxAuth: grant.inboxAuth, sendCredential: grant.sendCredential };
+}
+/** Queue `message` (already sealed and signed) in `handle`'s inbox. Returns the relay's queue id. */
+async function relaySend(input) {
+    const result = await relayRequest({ ...input, method: "POST", path: `/a2a/${encodeURIComponent(input.handle)}`, bearer: input.sendCredential, body: input.message });
+    // Something other than the relay (a captive portal, a proxy) can answer 2xx; only a queue id means it was queued.
+    if (typeof result.taskId !== "string")
+        throw new Error("the relay did not confirm the message was queued");
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_relay_sent", message: "queued a sealed A2A message at the relay", meta: { relayUrl: input.url } });
+    return result.taskId;
+}
+/**
+ * The queued messages in `handle`'s inbox (still sealed). An answer with no message list throws: it is not the relay's,
+ * so it says nothing about the inbox. An entry without a queue id cannot be acked, so it is logged
+ * (without its content) and skipped, and the rest of the queue is still handled. The relay has no way to drop an entry
+ * without its id, so a skipped entry stays queued until the relay's own expiry removes it.
+ */
+async function relayPull(input) {
+    const result = await relayRequest({ ...input, method: "GET", path: `/inbox/${encodeURIComponent(input.handle)}`, bearer: input.inboxAuth });
+    if (!Array.isArray(result.messages))
+        throw new Error("the relay's inbox answer has no message list");
+    const entries = result.messages;
+    const valid = [];
+    entries.forEach((entry, position) => {
+        const queueId = entry?.queueId;
+        if (entry && typeof entry === "object" && typeof queueId === "string" && queueId.length > 0) {
+            valid.push({ queueId, message: entry.message });
+            return;
+        }
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "channels", event: "channel.a2a_relay_entry_skipped", message: "skipped a relay inbox entry with no queue id; it cannot be acked and stays at the relay until it expires", meta: { relayUrl: input.url, position } });
+    });
+    return valid;
+}
+/** Remove one delivered message from `handle`'s inbox. Re-acking is harmless. */
+async function relayAck(input) {
+    await relayRequest({ ...input, method: "POST", path: `/inbox/${encodeURIComponent(input.handle)}/ack/${encodeURIComponent(input.queueId)}`, bearer: input.inboxAuth });
+}
+/** Remove `handle` and its queue from the relay (used when the agent moves to another relay). */
+async function relayDeregister(input) {
+    await relayRequest({ ...input, method: "DELETE", path: `/register/${encodeURIComponent(input.handle)}`, bearer: input.inboxAuth });
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_relay_deregistered", message: "deregistered an A2A relay inbox", meta: { relayUrl: input.url } });
+}

package/dist/a2a/relay-config-vault.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relayConfigFrom = relayConfigFrom;
+exports.vaultRelayConfigStore = vaultRelayConfigStore;
+const runtime_1 = require("../nerves/runtime");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function registrationFrom(value) {
+    const r = record(value);
+    const relayUrl = text(r?.relayUrl);
+    const handle = text(r?.handle);
+    const inboxAuth = text(r?.inboxAuth);
+    const sendCredential = text(r?.sendCredential);
+    return relayUrl && handle && inboxAuth && sendCredential ? { relayUrl, handle, inboxAuth, sendCredential } : undefined;
+}
+/** The `a2a.relay` settings in a machine runtime config, keeping only well-formed fields. */
+function relayConfigFrom(config) {
+    const relay = record(record(config.a2a)?.relay);
+    if (!relay)
+        return {};
+    const url = text(relay.url);
+    const inviteToken = text(relay.inviteToken);
+    const registration = registrationFrom(relay.registration);
+    const pending = record(relay.pendingRegistration);
+    const pendingRelayUrl = text(pending?.relayUrl);
+    const pendingHandle = text(pending?.handle);
+    const previousRegistrations = (Array.isArray(relay.previousRegistrations) ? relay.previousRegistrations : [])
+        .map(registrationFrom)
+        .filter((registration) => registration !== undefined);
+    return {
+        ...(url ? { url } : {}),
+        ...(inviteToken ? { inviteToken } : {}),
+        ...(registration ? { registration } : {}),
+        ...(pendingRelayUrl && pendingHandle ? { pendingRegistration: { relayUrl: pendingRelayUrl, handle: pendingHandle } } : {}),
+        ...(previousRegistrations.length > 0 ? { previousRegistrations } : {}),
+    };
+}
+/**
+ * The relay settings, read from and written to this machine's runtime config in the vault (beside the A2A identity
+ * seed). Every read goes to the vault, so a write decided on a fresh read (clearing the invite only if it is unchanged)
+ * sees an operator's newer value. A patch merges into `a2a.relay`; a key set to `undefined` is dropped when the merged
+ * config is serialized.
+ */
+function vaultRelayConfigStore(agentName, machineId) {
+    return {
+        async read() {
+            const result = await (0, runtime_credentials_1.refreshMachineRuntimeCredentialConfig)(agentName, machineId);
+            if (result.ok)
+                return relayConfigFrom(result.config);
+            if (result.reason === "missing")
+                return {};
+            throw new Error(`cannot read the A2A relay settings at ${result.itemPath}: ${result.error}`);
+        },
+        async write(patch) {
+            await (0, runtime_credentials_1.mergeMachineRuntimeCredentialConfig)(agentName, machineId, { a2a: { relay: patch } });
+            (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_relay_config_saved", message: "saved A2A relay settings to the vault", meta: { agentName, keys: Object.keys(patch) } });
+        },
+    };
+}

package/dist/a2a/relay-contacts.js

@@ -0,0 +1,120 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAY_CONTACT_FETCH_TIMEOUT_MS = exports.RELAY_CONTACT_REFRESH_MS = void 0;
+exports.readRelayContact = readRelayContact;
+exports.writeRelayContact = writeRelayContact;
+exports.markRelayContactStale = markRelayContactStale;
+exports.relayContactNeedsRefresh = relayContactNeedsRefresh;
+exports.refreshRelayContact = refreshRelayContact;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const outbox_client_1 = require("./outbox-client");
+exports.RELAY_CONTACT_REFRESH_MS = 24 * 60 * 60 * 1000;
+function contactFile(agentRoot, did) {
+    return path.join(agentRoot, "state", "a2a", "relay-contacts", `${(0, node_crypto_1.createHash)("sha256").update(did).digest("hex")}.json`);
+}
+function isContact(value) {
+    const c = value;
+    return !!c && typeof c === "object" && typeof c.url === "string" && typeof c.handle === "string" && typeof c.sendCredential === "string";
+}
+function readRelayContact(agentRoot, did) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(contactFile(agentRoot, did), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || parsed.did !== did || typeof parsed.fetchedAt !== "string")
+        return null;
+    return {
+        did,
+        fetchedAt: parsed.fetchedAt,
+        ...(isContact(parsed.contact) ? { contact: { url: parsed.contact.url, handle: parsed.contact.handle, sendCredential: parsed.contact.sendCredential } } : {}),
+        ...(parsed.stale === true ? { stale: true } : {}),
+        ...(typeof parsed.attemptedAt === "string" ? { attemptedAt: parsed.attemptedAt } : {}),
+    };
+}
+function writeRelayContact(agentRoot, entry) {
+    const file = contactFile(agentRoot, entry.did);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${(0, node_crypto_1.randomBytes)(6).toString("hex")}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    fs.renameSync(temp, file);
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_relay_contact_saved", message: "saved a peer's A2A relay contact", meta: { peerDid: entry.did, hasRelay: entry.contact !== undefined, stale: entry.stale === true } });
+}
+function markRelayContactStale(agentRoot, did) {
+    const entry = readRelayContact(agentRoot, did);
+    if (!entry)
+        return;
+    // A new refusal asks again at the next direct send, even if a refresh failed earlier today.
+    writeRelayContact(agentRoot, { did: entry.did, fetchedAt: entry.fetchedAt, ...(entry.contact ? { contact: entry.contact } : {}), stale: true });
+}
+/** True when the entry is missing, or its last fetch or failed attempt is more than a day old (at once when stale and not yet retried). */
+function relayContactNeedsRefresh(entry, now) {
+    if (!entry)
+        return true;
+    const attemptedAt = entry.attemptedAt === undefined ? Number.NaN : Date.parse(entry.attemptedAt);
+    if (entry.stale && !Number.isFinite(attemptedAt))
+        return true;
+    const fetchedAt = Date.parse(entry.fetchedAt);
+    const last = Math.max(Number.isFinite(fetchedAt) ? fetchedAt : -Infinity, Number.isFinite(attemptedAt) ? attemptedAt : -Infinity);
+    return now - last > exports.RELAY_CONTACT_REFRESH_MS;
+}
+exports.RELAY_CONTACT_FETCH_TIMEOUT_MS = 10_000;
+/**
+ * Ask a peer, over the sealed `relay/contact` method, where to queue messages for it while it is offline, and cache the
+ * answer. Runs after a successful direct send (the peer is online then), at most once a day per peer. A failure never
+ * throws: it keeps a contact already cached and records when it tried, and otherwise records "no relay", so either
+ * way the peer is not asked again today (a peer on an older harness answers "unknown method").
+ */
+async function refreshRelayContact(input) {
+    const fetchedAt = new Date(input.now ?? Date.now()).toISOString();
+    const baseFetch = input.fetchImpl ?? fetch;
+    const fetchImpl = ((url, init) => baseFetch(url, { ...init, signal: AbortSignal.timeout(exports.RELAY_CONTACT_FETCH_TIMEOUT_MS) }));
+    try {
+        const result = await (0, outbox_client_1.callOutboxMethod)({ cardUrl: input.cardUrl, method: "relay/contact", params: {}, identity: input.identity, fetchImpl, expectedDid: input.peerDid });
+        writeRelayContact(input.agentRoot, { did: input.peerDid, fetchedAt, ...(isContact(result.contact) ? { contact: { url: result.contact.url, handle: result.contact.handle, sendCredential: result.contact.sendCredential } } : {}) });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "channels", event: "channel.a2a_relay_contact_refresh_failed", message: "could not fetch a peer's relay contact", meta: { peerDid: input.peerDid, error: error instanceof Error ? error.message : /* v8 ignore next -- the outbox client only throws Error instances @preserve */ String(error) } });
+        // Keep a cached contact (it may still work) but record the attempt, so a failing peer is asked at most once a day.
+        const existing = readRelayContact(input.agentRoot, input.peerDid);
+        writeRelayContact(input.agentRoot, existing?.contact ? { ...existing, attemptedAt: fetchedAt } : { did: input.peerDid, fetchedAt });
+    }
+}