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

package/dist/a2a/outbox-wire.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTBOX_ERROR_INVALID = exports.OUTBOX_ERROR_REFUSED = exports.OUTBOX_METHODS = void 0;
+exports.isOutboxMethod = isOutboxMethod;
+exports.encodeOutboxCommand = encodeOutboxCommand;
+exports.parseOutboxCommand = parseOutboxCommand;
+exports.handleOutboxCommand = handleOutboxCommand;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const escalation_grants_1 = require("./escalation-grants");
+const resolution_proof_1 = require("./resolution-proof");
+const outbox_store_1 = require("./outbox-store");
+const failure_reports_1 = require("../heart/failure-reports");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The outbox methods ride the same sealed, signed chat envelope as `a2a message`: the request is a `message` whose
+ * signed text is `{"ouro":"a2a-method","method":...,"params":...}`, posted under the JSON-RPC method of the same name.
+ * The server verifies the sender exactly as it does for a chat (unseal, pinned key, signature, replay guard, friend
+ * record), requires the signed method to equal the JSON-RPC method, and then decides access itself from the verified
+ * friend record. A sender can only ever name its own outbox: no parameter selects another peer's.
+ *
+ *   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", "relay/contact"];
+exports.OUTBOX_ERROR_REFUSED = -32003;
+exports.OUTBOX_ERROR_INVALID = -32602;
+const MAX_ACK_IDS = 100;
+function isOutboxMethod(method) {
+    return typeof method === "string" && exports.OUTBOX_METHODS.includes(method);
+}
+function encodeOutboxCommand(method, params) {
+    return JSON.stringify({ ouro: "a2a-method", method, params });
+}
+function parseOutboxCommand(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const command = parsed;
+    if (command.ouro !== "a2a-method" || !isOutboxMethod(command.method))
+        return null;
+    const params = command.params === undefined ? {} : command.params;
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return null;
+    return { method: command.method, params: params };
+}
+const refuse = (message) => ({ ok: false, code: exports.OUTBOX_ERROR_REFUSED, message });
+const invalid = (message) => ({ ok: false, code: exports.OUTBOX_ERROR_INVALID, message });
+/** Runs one verified outbox command for `friend`. `friend` must be the record found by the signed sender DID. */
+async function handleOutboxCommand(input) {
+    const { agentRoot, friend, method, params } = input;
+    if (!friend || friend.admissionState !== "active") {
+        (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;
+        if (since !== undefined && typeof since !== "string")
+            return invalid("since must be a string cursor");
+        if (limit !== undefined && (typeof limit !== "number" || !Number.isFinite(limit)))
+            return invalid("limit must be a number");
+        return { ok: true, result: { ...outbox.list(friend.id, { ...(since !== undefined ? { since } : {}), ...(limit !== undefined ? { limit: Math.min(limit, outbox_store_1.OUTBOX_LIST_MAX_LIMIT) } : {}) }) } };
+    }
+    if (method === "outbox/ack") {
+        const { ids } = params;
+        if (!Array.isArray(ids) || ids.length === 0 || ids.length > MAX_ACK_IDS || ids.some((id) => typeof id !== "string"))
+            return invalid(`ids must be 1 to ${MAX_ACK_IDS} strings`);
+        return { ok: true, result: { ...outbox.ack(friend.id, ids) } };
+    }
+    if (!(0, escalation_grants_1.holdsEscalation)(agentRoot, friend, input.now)) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_report_resolve_refused", message: "refused report/resolve from a peer without the escalation grant", meta: { friendId: friend.id } });
+        return refuse("report/resolve needs the escalation grant");
+    }
+    const { id, version, note, resolvedAt, proof } = params;
+    if (typeof id !== "string" || typeof version !== "string" || typeof note !== "string" || typeof resolvedAt !== "string")
+        return invalid("id, version, note and resolvedAt must be strings");
+    // The key is the DID the operator pinned in the root-owned grant, never the friend record; and the A2A-verified caller must be that same DID.
+    const holderDid = (0, escalation_grants_1.pinnedHolderDid)(agentRoot, friend.id, input.now);
+    if (!holderDid || input.verifiedDid !== holderDid) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_report_resolve_refused", message: "refused report/resolve from a caller whose verified DID is not the pinned holder DID", meta: { friendId: friend.id } });
+        return refuse("report not resolved: the caller is not the pinned escalation holder");
+    }
+    const checked = (0, resolution_proof_1.verifyResolution)({ sodium: await (0, a2a_client_1.ready)(), claim: { reportId: id, version, note, resolvedAt }, proof, holderDid });
+    if (!checked.ok)
+        return refuse(`report not resolved: the resolution is not signed by your key (${checked.reason})`);
+    const resolved = await (0, failure_reports_1.resolveFailureReport)(agentRoot, { id, version, note, byFriendId: friend.id, resolvedAt, proof }, input.now);
+    return resolved.ok ? { ok: true, result: { id: resolved.id, status: resolved.status } } : refuse(`report not resolved: ${resolved.reason}`);
+}

package/dist/a2a/pin-store.js

@@ -0,0 +1,167 @@
+"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.FileA2APinStore = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const runtime_1 = require("../nerves/runtime");
+function pinFileName(fromAgentId) {
+    return `${(0, node_crypto_1.createHash)("sha256").update(fromAgentId).digest("hex")}.json`;
+}
+function pinnedFromStored(stored, ed25519Pub) {
+    return {
+        did: stored.did,
+        ed25519Pub,
+        ...(typeof stored.rotatedAt === "string" ? { rotatedAt: stored.rotatedAt } : {}),
+        ...(typeof stored.retiredBy === "string" ? { retiredBy: stored.retiredBy } : {}),
+    };
+}
+class FileA2APinStore {
+    dir;
+    cache = new Map();
+    constructor(agentRoot) {
+        this.dir = path.join(agentRoot, "state", "a2a", "pins");
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.loadExisting();
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_store_init",
+            message: "initialized durable A2A pin store",
+            meta: { dir: this.dir, pins: this.cache.size },
+        });
+    }
+    get size() {
+        return this.cache.size;
+    }
+    get(fromAgentId) {
+        if (!fromAgentId)
+            return undefined;
+        const pinned = this.cache.get(fromAgentId);
+        if (!pinned)
+            return undefined;
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_hit",
+            message: "A2A pin hit",
+            meta: { fromAgentId, did: pinned.did },
+        });
+        return pinned;
+    }
+    set(fromAgentId, pinned) {
+        // An empty-string DID is never a matchable key (security: it can never index a
+        // pin). Stay inert rather than writing an unkeyed pin file.
+        if (!fromAgentId)
+            return;
+        const existed = this.cache.has(fromAgentId);
+        this.write(fromAgentId, pinned);
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_set",
+            message: "set durable A2A pin",
+            meta: { fromAgentId, did: pinned.did, rotated: existed },
+        });
+    }
+    /** Keep a tombstone under `fromAgentId`: the old DID and key, marked retired in favour of `retiredBy`. friends
+     * calls this after it moves the pin to the successor DID; `receiveShare` then refuses the old DID as `retired_pin`. */
+    retire(fromAgentId, retiredBy, rotatedAt) {
+        const pinned = this.cache.get(fromAgentId);
+        if (!fromAgentId || !pinned)
+            return;
+        this.write(fromAgentId, { ...pinned, retiredBy, rotatedAt });
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "channels",
+            event: "channel.a2a_pin_retired",
+            message: "retired an A2A pin after a verified rotation",
+            meta: { fromAgentId, retiredBy, rotatedAt },
+        });
+    }
+    /** The DID whose retired pin names `did` as its successor, if any (a rotation chain followed backwards). */
+    predecessorOf(did) {
+        for (const [fromAgentId, pinned] of this.cache) {
+            if (pinned.retiredBy === did)
+                return fromAgentId;
+        }
+        return undefined;
+    }
+    /** Persist a pin (its DID, which may differ from fromAgentId, its key, and the rotation fields) and cache it. */
+    write(fromAgentId, pinned) {
+        const stored = {
+            fromAgentId,
+            did: pinned.did,
+            pinnedKey: (0, a2a_client_1.base58btcEncode)(pinned.ed25519Pub),
+            ...(pinned.rotatedAt !== undefined ? { rotatedAt: pinned.rotatedAt } : {}),
+            ...(pinned.retiredBy !== undefined ? { retiredBy: pinned.retiredBy } : {}),
+        };
+        fs.writeFileSync(path.join(this.dir, pinFileName(fromAgentId)), `${JSON.stringify(stored, null, 2)}\n`, "utf-8");
+        this.cache.set(fromAgentId, pinnedFromStored(stored, pinned.ed25519Pub));
+    }
+    /** Reload every persisted pin from disk into the in-memory cache (the restart
+     * replay). Corrupt/undecodable files are skipped so one bad file can never
+     * wedge the store. */
+    loadExisting() {
+        let entries;
+        try {
+            entries = fs.readdirSync(this.dir);
+        }
+        catch {
+            /* v8 ignore next -- the constructor mkdirSync's the dir before this runs; unreadable dir is unreachable in practice @preserve */
+            return;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".json"))
+                continue;
+            let stored;
+            try {
+                stored = JSON.parse(fs.readFileSync(path.join(this.dir, name), "utf-8"));
+            }
+            catch {
+                continue;
+            }
+            // `fromAgentId` is the cache key; fall back to `did` for any pre-rotation
+            // file written before the key/did split (back-compat).
+            const key = stored.fromAgentId ?? stored.did;
+            if (!key || !stored.did || !stored.pinnedKey)
+                continue;
+            const ed25519Pub = (0, a2a_client_1.base58btcDecode)(stored.pinnedKey);
+            if (!ed25519Pub)
+                continue;
+            this.cache.set(key, pinnedFromStored(stored, ed25519Pub));
+        }
+    }
+}
+exports.FileA2APinStore = FileA2APinStore;

package/dist/a2a/refusals.js

@@ -0,0 +1,53 @@
+"use strict";
+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.";
+const REFUSALS = {
+    malformed_message: { message: "the message is not a sealed A2A data part", next: UPGRADE, retry: false },
+    malformed_plaintext: { message: "the sealed message did not open to a valid envelope", next: UPGRADE, retry: false },
+    unseal_failed: { message: "the message could not be opened with this agent's key", next: "Fetch this agent's card again (its key may have changed) and resend.", retry: false },
+    recipient_mismatch: { message: "the message was sealed to a different agent", next: "Check the recipient's DID and resend.", retry: false },
+    signed_recipient_mismatch: { message: "the signed envelope names a different recipient", next: "Check the recipient's DID and resend.", retry: false },
+    signed_kind_mismatch: { message: "the signed envelope's kind does not match how it was sealed", next: UPGRADE, retry: false },
+    sender_binding_mismatch: { message: "the claimed sender does not match the signer", next: "Send from the identity the message claims.", retry: false },
+    malformed_binding: { message: "the envelope's signed binding is malformed", next: UPGRADE, retry: false },
+    unbound_envelope: { message: "the envelope has no signed binding (the sender runs an older harness)", next: UPGRADE, retry: false },
+    unbound_delegation: { message: "the delegated command has no signed binding (the sender runs an older harness)", next: UPGRADE, retry: false },
+    stale_envelope: { message: "the envelope is more than 7 days old or dated in the future", next: `Check the sender's clock. ${RESEND}`, retry: false },
+    stale_delegation: { message: "the delegated command is more than 10 minutes old", next: `Check the sender's clock. ${RESEND}`, retry: false },
+    replayed: { message: "this message was already received", next: `Nothing to do if it was delivered; otherwise ${RESEND.toLowerCase()}`, retry: false },
+    in_flight: { message: "the same message is being handled right now", next: "Retry in a moment.", retry: true },
+    resolve_failed: { message: "the sender's DID could not be resolved or pinned (it is not a did:key, its pinned key differs, or a key rotation was refused)", next: "Send from the identity this agent knows you by, or ask the operator to re-link you.", retry: false },
+    retired_pin: { message: "the sender's DID was rotated to a successor and no longer verifies", next: "Send from the successor identity.", retry: false },
+    bad_signature: { message: "the signature does not verify against the sender's pinned key", next: "Send from the key this agent pinned for you, or ask the operator to re-link you.", retry: false },
+    untrusted_source: { message: "this agent does not trust the sender enough for this kind of message", next: "Ask the operator to connect you as a friend.", retry: false },
+    import_failed: { message: "the message verified but could not be stored", next: RESEND, retry: false },
+    // Mission results (the harness result wire).
+    no_mission: { message: "this agent has no mission with that key", next: "Check the mission key; the delegator may have dropped the mission.", retry: false },
+    no_delegation: { message: "this agent delegated no task with that request id", next: "Check the request id the delegation gave you.", retry: false },
+    assignee_mismatch: { message: "the task was delegated to a different agent", next: "Only the assignee can send this result.", retry: false },
+};
+const UNKNOWN = { message: "the message was refused", next: "Check the agent's logs.", retry: false };
+/** The wording for one refusal reason (an unknown reason gets a generic line). */
+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 } });
+    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 });
+    }
+}