@ouro.bot/cli 0.1.0-alpha.88 → 0.1.0-alpha.880

package/dist/a2a/mission-result-wire.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapMissionResultDataPart = wrapMissionResultDataPart;
+exports.isMissionResultDataPart = isMissionResultDataPart;
+exports.receiveInboundMissionResult = receiveInboundMissionResult;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * THE HARNESS-OWNED RESULT WIRE.
+ *
+ * A mission RESULT is NOT a `FriendsKind` (`FriendsKind` = profile_share |
+ * mission_share | coordination) — `prepareMissionResult`/`importMissionResult` are
+ * transport-agnostic + store-only, and the result does NOT ride `sendShare`/
+ * `receiveShare`. So the HARNESS owns the wire: the result envelope is sealed (reusing
+ * the sign-then-seal crypto) and wrapped in a DataPart carrying a distinct `ouroKind:
+ * "mission_result"` discriminator. The inbound bridge recognizes that tag and routes
+ * it to `importMissionResult` — NEVER to `receiveShare`, which would mis-route a
+ * non-`FriendsKind` envelope. This is "a DataPart variant + an inbound route branch"
+ * (the carrier is the friends `unwrapDataPart` shape + one extra tag field — no
+ * structural change beyond that).
+ *
+ * SECURITY — the wire AUTHENTICATES the sender exactly like the share path
+ * (`receiveShare` in friends' `adapter.ts`). `openSealedEnvelope` does AEAD
+ * decryption ONLY — it does NOT verify the signature (its docstring names the
+ * adapter's `DidVerifier` as "the single authentication gate"). The decrypted
+ * `envelope.fromAgentId` is therefore attacker-controlled plaintext: the recipient's
+ * X25519 pubkey is public (derived from the published DID), so any party can SEAL a
+ * forged result to us. Authentication is the ONLY barrier. Before trusting the
+ * claimed sender we therefore replicate `receiveShare`'s gate:
+ *   1. binding check — `opened.signerDid === opened.fromAgentId` (and non-empty),
+ *   2. resolve + pin the sender DID (TOFU pin + signed-rotation evaluation),
+ *   3. hand `importMissionResult` a REAL `DidVerifier` bound to the pinned key, so
+ *      `verifier.verify(fromAgentId, proof)` runs the Ed25519 signature check against
+ *      the pinned key — NOT the no-op `tofuVerifier` the importer defaults to.
+ * Replay is deduped on the seal nonce (durable `SeenLedger`), matching the share path.
+ */
+const OURO_RESULT_KIND = "mission_result";
+/** Wrap a sealed result envelope into the harness-owned `mission_result` DataPart. */
+function wrapMissionResultDataPart(input) {
+    return {
+        messageId: `result-${Math.random().toString(36).slice(2)}`,
+        role: "agent",
+        parts: [{
+                kind: "data",
+                data: {
+                    v: input.sealedEnvelope.v,
+                    sealed: input.sealedEnvelope.sealed,
+                    recipientDid: input.recipientDid,
+                    ouroKind: OURO_RESULT_KIND,
+                },
+            }],
+    };
+}
+/** Whether an inbound message carries the harness-owned `mission_result` DataPart. */
+function isMissionResultDataPart(message) {
+    if (!Array.isArray(message.parts))
+        return false;
+    return message.parts.some((p) => p && p.kind === "data" && typeof p.data === "object" && p.data !== null
+        && p.data.ouroKind === OURO_RESULT_KIND);
+}
+/** Extract the sealed envelope from a `mission_result` DataPart, or null. */
+function unwrapMissionResultDataPart(message) {
+    if (!Array.isArray(message.parts) || message.parts.length !== 1)
+        return null;
+    const part = message.parts[0];
+    if (!part || part.kind !== "data" || !part.data)
+        return null;
+    const data = part.data;
+    if (data.ouroKind !== OURO_RESULT_KIND)
+        return null;
+    if (typeof data.v !== "number" || typeof data.recipientDid !== "string" || !data.sealed)
+        return null;
+    return { sealed: { v: data.v, sealed: data.sealed }, recipientDid: data.recipientDid };
+}
+/**
+ * Route an inbound `mission_result` DataPart to `importMissionResult`, AUTHENTICATING
+ * the sender exactly like `receiveShare` does for every other inbound kind.
+ *
+ * Ordering (mirrors the share bridge's trust trap + authentication gate):
+ *   1. recognize + unwrap the harness `mission_result` carrier (else `not-a-result`).
+ *   2. replay dedup on the seal nonce (durable `SeenLedger`) — before any state change.
+ *   3. `openSealedEnvelope` → AEAD-decrypt only (unseal/recipient failures → reject).
+ *   4. binding check — reject unless `opened.signerDid === opened.fromAgentId` (and
+ *      non-empty): the advisory `signerDid` (outer, unsigned) must match the claimed
+ *      sender. A divergence is a forged/spoofed bundle (`sender_binding_mismatch`).
+ *   5. `resolveAndPin` the sender DID (TOFU pin / signed-rotation) → the pinned key
+ *      (unresolvable/failed-binding/failed-rotation → `resolve_failed`).
+ *   6. build a `DidVerifier` bound to THIS envelope + the pinned key, mark the nonce
+ *      seen, then call `importMissionResult({ envelope, fromAgentId: <signed DID>,
+ *      trustOfSource }, { verifier })`. The verifier runs the REAL signature check
+ *      against the pinned key — a result signed with a key that is not the pinned key
+ *      for the claimed DID is rejected (`untrusted_source`). Every authorization gate
+ *      (no_mission / no_delegation / assignee_mismatch, fail-closed on a legacy
+ *      assignee-less delegation) is still enforced by the importer.
+ */
+async function receiveInboundMissionResult(message, deps) {
+    const payload = unwrapMissionResultDataPart(message);
+    if (!payload)
+        return { outcome: "not-a-result" };
+    // Replay dedup BEFORE any state change, keyed on the seal nonce (matches receiveShare).
+    if (deps.seen.isSeen(payload.sealed.sealed.n)) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (replayed seal nonce)",
+            meta: { reason: "replayed" },
+        });
+        return { outcome: "rejected", reason: "replayed" };
+    }
+    const recipientIdentity = { x25519Priv: deps.identity.x25519Priv, x25519Pub: deps.identity.x25519Pub };
+    const opened = (0, a2a_client_1.openSealedEnvelope)({
+        sodium: deps.sodium,
+        sealedEnvelope: payload.sealed,
+        recipientDid: deps.identity.did,
+        recipientIdentity,
+    });
+    if (!opened.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (unseal/recipient)",
+            meta: { reason: opened.error },
+        });
+        return { outcome: "rejected", reason: opened.error };
+    }
+    // SECURITY (binding): the trustworthy sender identity is the SIGNED `fromAgentId`.
+    // `openSealedEnvelope` does NOT verify the signature, so `fromAgentId` is untrusted
+    // until the DidVerifier confirms the pinned key signed THIS envelope. The advisory
+    // `signerDid` (from the outer, unsigned sealed plaintext) must match the claimed
+    // sender; a divergence is a forged/spoofed bundle (e.g. an attacker signing with its
+    // OWN key while claiming a victim's DID). Reject before resolving or importing.
+    const senderDid = opened.fromAgentId;
+    if (senderDid.length === 0 || opened.signerDid !== senderDid) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (sender binding mismatch — forged sender)",
+            meta: { reason: "sender_binding_mismatch", claimedDid: senderDid, signerDid: opened.signerDid },
+        });
+        return { outcome: "rejected", reason: "sender_binding_mismatch" };
+    }
+    // Read trust from the friend store BY the verified DID — never defaulted, never from
+    // the envelope. Unknown (or empty) DID ⇒ stranger.
+    const record = await (0, friends_1.findFriendByDid)(deps.store, senderDid);
+    const trust = record?.trustLevel ?? "stranger";
+    // Resolve + pin the SENDER's DID (async — BEFORE the sync verifier/importer).
+    const resolved = await deps.didResolution.resolveAndPin({
+        fromAgentId: senderDid,
+        did: senderDid,
+        pinStore: deps.pinStore,
+        trustOfSource: trust,
+    });
+    if (!resolved) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_rejected",
+            message: "rejected inbound mission_result (sender DID resolve/pin failed)",
+            meta: { reason: "resolve_failed", verifiedDid: senderDid, trust },
+        });
+        return { outcome: "rejected", reason: "resolve_failed" };
+    }
+    // Build the sync verifier bound to THIS envelope + the pinned sender key. This is the
+    // single authentication gate (the importer would otherwise default to the no-op TOFU
+    // verifier). `verify` confirms the agentId===did binding AND the Ed25519 signature
+    // over the envelope against the pinned key.
+    const verifier = new a2a_client_1.DidVerifier({
+        sodium: deps.sodium,
+        pinnedEd25519Pub: resolved.ed25519Pub,
+        pinnedDid: senderDid,
+        envelope: opened.envelope,
+    });
+    // Mark seen now (idempotent imports + the replay guard above keep this safe).
+    deps.seen.markSeen(payload.sealed.sealed.n);
+    const result = await (0, friends_1.importMissionResult)(deps.missionStore, {
+        envelope: opened.envelope,
+        fromAgentId: senderDid,
+        trustOfSource: trust,
+    }, { verifier });
+    if (result.ok) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_result_imported",
+            message: "imported inbound mission_result (authenticated, quarantined, attributed)",
+            meta: { verifiedDid: senderDid, trust, status: result.status },
+        });
+        return { outcome: "imported", verifiedDid: senderDid };
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_result_rejected",
+        message: "rejected inbound mission_result (import gate)",
+        meta: { reason: result.status, verifiedDid: senderDid, trust },
+    });
+    return { outcome: "rejected", reason: result.status };
+}

package/dist/a2a/onboarding.js

@@ -0,0 +1,133 @@
+"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.onboardA2APeer = onboardA2APeer;
+exports.onboardA2AClientByDid = onboardA2AClientByDid;
+const path = __importStar(require("node:path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const friends_1 = require("@ouro.bot/friends");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const client_1 = require("./client");
+function storeFor(options) {
+    if (options.store)
+        return options.store;
+    /* v8 ignore next -- default bundle root fallback is owned by identity path tests; CLI and onboarding tests inject explicit roots @preserve */
+    return new friends_1.FileFriendStore(path.join(options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${options.agentName}.ouro`, "friends"));
+}
+/** The normalized card URL (legacy URL-keyed identity for did-less cards). */
+function urlAgentId(cardUrl) {
+    const parsed = new URL(cardUrl);
+    parsed.hash = "";
+    return parsed.toString();
+}
+async function onboardA2APeer(options) {
+    // HTTP/URL glue stays harness-side: fetch the agent card, resolve its JSON-RPC
+    // endpoint, and derive the stable agentId. The record-shaping (mint/update the
+    // agent-peer friend) is delegated to @ouro.bot/friends' upsertAgentPeer.
+    const card = await (0, client_1.fetchA2AAgentCard)(options.cardUrl, options.fetchImpl);
+    const store = storeFor(options);
+    /* v8 ignore next -- fetchA2AAgentCard validates a usable endpoint or legacy url before returning a card @preserve */
+    const endpointUrl = (0, client_1.endpointForCard)(card) ?? options.cardUrl;
+    const protocolVersion = card.supportedInterfaces?.find((entry) => entry.url === endpointUrl)?.protocolVersion
+        ?? card.protocolVersion;
+    const name = options.name ?? card.name;
+    // THE FOOTGUN FIX: a DID-bearing card keys the record on its VERIFIED did:key
+    // (so an inbound sealed envelope — keyed on the signed DID — resolves to THIS
+    // record, not a stranger). A did-less (legacy) card keeps the URL-keyed identity
+    // unchanged (backward compatible). For did:key the binding is self-contained
+    // (`card.did === did`, `didDoc: null`); we ALSO require the served did:key to be a
+    // well-formed, parseable Ed25519 key (a malformed did:key could never key/verify
+    // an inbound envelope, so onboarding it would silently break the resolve later). A
+    // card whose DID is unparseable or fails the binding is REFUSED (no record
+    // written) — never TOFU-trust a mis-bound or malformed card.
+    const did = (0, client_1.cardDid)(card);
+    if (did) {
+        const parsed = (0, a2a_client_1.parseDidKey)(did);
+        const bound = parsed !== null && (0, a2a_client_1.verifyCardDidBinding)({ card: { did, url: options.cardUrl }, did, didDoc: null });
+        if (!bound) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "friends",
+                event: "friends.a2a_card_binding_rejected",
+                message: "refused A2A onboarding: card↔DID binding failed",
+                meta: { agentName: options.agentName, cardUrl: options.cardUrl, did, parseable: parsed !== null },
+            });
+            throw new Error(`A2A card↔DID binding failed for ${did}`);
+        }
+    }
+    // DID-keyed when present (externalId === did, a2a.did === did), else URL-keyed.
+    const externalId = did ?? urlAgentId(options.cardUrl);
+    const record = await (0, friends_1.upsertAgentPeer)(store, {
+        name,
+        agentId: externalId,
+        ...(options.trustLevel ? { trustLevel: options.trustLevel } : {}),
+        a2a: {
+            cardUrl: options.cardUrl,
+            endpointUrl,
+            agentId: externalId,
+            protocolVersion,
+            ...(did ? { did } : {}),
+        },
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.a2a_peer_onboarded",
+        message: "onboarded A2A peer into friend model",
+        meta: { agentName: options.agentName, friendId: record.id, peerName: record.name, trustLevel: record.trustLevel, ...(did ? { did } : {}) },
+    });
+    return record;
+}
+/**
+ * Onboard a client that serves no agent card (for example a coding harness with a
+ * file-backed identity) by its did:key alone. The record is keyed on the DID, so its
+ * signed, sealed messages resolve to this friend; the key must parse, or nothing is written.
+ */
+async function onboardA2AClientByDid(options) {
+    if ((0, a2a_client_1.parseDidKey)(options.did) === null)
+        throw new Error(`not a valid did:key: ${options.did}`);
+    const record = await (0, friends_1.upsertAgentPeer)(storeFor(options), {
+        name: options.name,
+        agentId: options.did,
+        ...(options.trustLevel ? { trustLevel: options.trustLevel } : {}),
+        a2a: { did: options.did, agentId: options.did },
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.a2a_client_onboarded",
+        message: "onboarded card-less A2A client into friend model",
+        meta: { agentName: options.agentName, friendId: record.id, peerName: record.name, trustLevel: record.trustLevel, did: options.did },
+    });
+    return record;
+}

package/dist/a2a/outbox-client.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callOutboxMethod = callOutboxMethod;
+const node_crypto_1 = require("node:crypto");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const client_1 = require("./client");
+const outbox_wire_1 = require("./outbox-wire");
+const sealed_chat_1 = require("./sealed-chat");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Calls one outbox method on an A2A agent as a verified friend. The request is sealed to the agent's card DID and
+ * signed by `identity`, and the reply is opened only if it was sealed by that same card key, so neither direction
+ * travels in plaintext. Throws with the agent's refusal text when the agent answers with a JSON-RPC error.
+ */
+async function callOutboxMethod(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const sodium = input.sodium ?? await (0, a2a_client_1.ready)();
+    const card = await (0, client_1.fetchA2AAgentCard)(input.cardUrl, fetchImpl);
+    const peerDid = (0, client_1.cardDid)(card);
+    if (!peerDid)
+        throw new Error(`A2A card ${input.cardUrl} serves no DID; outbox calls need one`);
+    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}`);
+    }
+    const endpointUrl = (0, client_1.endpointForCard)(card);
+    const conversationId = (0, node_crypto_1.randomUUID)();
+    const sealed = (0, sealed_chat_1.sealChatMessage)({
+        sodium, from: input.identity, recipientDid: peerDid, recipientEd25519Pub: parsed.ed25519Pub,
+        text: (0, outbox_wire_1.encodeOutboxCommand)(input.method, input.params), conversationId,
+    });
+    const request = {
+        jsonrpc: "2.0", id: (0, node_crypto_1.randomUUID)(), method: input.method,
+        params: { message: { kind: "message", role: "ROLE_USER", messageId: (0, node_crypto_1.randomUUID)(), contextId: conversationId, parts: sealed.parts } },
+    };
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_outbox_call_start", message: "calling an A2A outbox method", meta: { endpointUrl, peerDid, method: input.method } });
+    const rpc = await (0, client_1.postJsonRpc)(endpointUrl, request, fetchImpl);
+    if ("error" in rpc)
+        throw new Error(`A2A error ${rpc.error.code}: ${rpc.error.message}`);
+    const reply = rpc.result;
+    if (!reply || !Array.isArray(reply.parts))
+        throw new Error("A2A outbox call returned no reply message");
+    const opened = await (0, sealed_chat_1.openChatMessage)({ sodium, self: input.identity, message: reply, senderDid: peerDid, senderEd25519Pub: parsed.ed25519Pub });
+    if (!opened.ok)
+        throw new Error(`A2A outbox reply rejected: ${opened.reason}`);
+    let result;
+    try {
+        result = JSON.parse(opened.text);
+    }
+    catch {
+        throw new Error("A2A outbox reply was not JSON");
+    }
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        throw new Error("A2A outbox reply was not a JSON object");
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_outbox_call_end", message: "received an A2A outbox reply", meta: { endpointUrl, peerDid, method: input.method } });
+    return result;
+}

package/dist/a2a/outbox-store.js

@@ -0,0 +1,188 @@
+"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.FileOutboxStore = exports.OUTBOX_LIST_MAX_CHARS = exports.OUTBOX_LIST_MAX_LIMIT = exports.OUTBOX_LIST_DEFAULT_LIMIT = exports.OUTBOX_MAX_BODY_CHARS = exports.OUTBOX_MAX_ENTRIES = void 0;
+exports.isOutboxEntryId = isOutboxEntryId;
+exports.outboxRoot = outboxRoot;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const file_lock_1 = require("../heart/file-lock");
+const runtime_1 = require("../nerves/runtime");
+exports.OUTBOX_MAX_ENTRIES = 500;
+exports.OUTBOX_MAX_BODY_CHARS = 6_000;
+exports.OUTBOX_LIST_DEFAULT_LIMIT = 20;
+exports.OUTBOX_LIST_MAX_LIMIT = 50;
+/** One listing reply is a single sealed message of at most 16,000 characters, so a listing stops filling well before that. */
+exports.OUTBOX_LIST_MAX_CHARS = 12_000;
+const FRIEND_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const ENTRY_ID = /^\d{13}-[0-9a-f]{6}$/u;
+function isOutboxEntryId(value) {
+    return typeof value === "string" && ENTRY_ID.test(value);
+}
+function entryDir(agentRoot, friendId) {
+    if (!FRIEND_ID.test(friendId))
+        throw new Error("outbox friend id is invalid");
+    return path.join(agentRoot, "state", "outbox", friendId);
+}
+function outboxRoot(agentRoot) {
+    return path.join(agentRoot, "state", "outbox");
+}
+function readEntry(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!isOutboxEntryId(parsed.id) || typeof parsed.kind !== "string" || typeof parsed.createdAt !== "string" || typeof parsed.body !== "string")
+            return null;
+        return { id: parsed.id, kind: parsed.kind, createdAt: parsed.createdAt, body: parsed.body, ...(parsed.meta ? { meta: parsed.meta } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+function sortedIds(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((name) => name.endsWith(".json") && isOutboxEntryId(name.slice(0, -5))).map((name) => name.slice(0, -5)).sort();
+}
+class FileOutboxStore {
+    agentRoot;
+    constructor(agentRoot) {
+        this.agentRoot = agentRoot;
+    }
+    /** Adds one entry for `friendId`. The oldest entries beyond the cap are dropped so a peer that never reads cannot fill the disk. */
+    append(friendId, input, now = Date.now()) {
+        const dir = entryDir(this.agentRoot, friendId);
+        fs.mkdirSync(dir, { recursive: true });
+        const id = `${String(now).padStart(13, "0")}-${(0, node_crypto_1.randomBytes)(3).toString("hex")}`;
+        const entry = {
+            id,
+            kind: input.kind,
+            createdAt: new Date(now).toISOString(),
+            body: input.body.slice(0, exports.OUTBOX_MAX_BODY_CHARS),
+            ...(input.meta ? { meta: input.meta } : {}),
+        };
+        const file = path.join(dir, `${id}.json`);
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        const ids = sortedIds(dir);
+        const evicted = ids.slice(0, Math.max(0, ids.length - exports.OUTBOX_MAX_ENTRIES));
+        for (const stale of evicted)
+            fs.rmSync(path.join(dir, `${stale}.json`), { force: true });
+        if (evicted.length > 0) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.a2a_outbox_evicted",
+                message: "a peer outbox is full, so its oldest unread entries were dropped",
+                meta: { friendId, evicted: evicted.length, oldestDropped: evicted[0], cap: exports.OUTBOX_MAX_ENTRIES },
+            });
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.a2a_outbox_appended",
+            message: "queued a message in a peer outbox",
+            meta: { friendId, entryId: id, kind: input.kind },
+        });
+        return entry;
+    }
+    /** Like `append`, but a second call with the same `dedupeKey` while the first entry is still unacked returns that entry, so a retried delivery cannot double-post. */
+    async appendOnce(friendId, dedupeKey, input, now = Date.now()) {
+        const dir = entryDir(this.agentRoot, friendId);
+        // The check and the append happen under one cross-process lock, so two senses retrying the same delivery cannot both miss it.
+        return (0, file_lock_1.withFileLock)(path.join(this.agentRoot, "state", "outbox", ".locks"), `once-${friendId}`, () => {
+            for (const id of sortedIds(dir)) {
+                const entry = readEntry(path.join(dir, `${id}.json`));
+                if (entry?.meta?.dedupeKey === dedupeKey)
+                    return entry;
+            }
+            return this.append(friendId, { ...input, meta: { ...input.meta, dedupeKey } }, now);
+        });
+    }
+    /** Entries after `since` (exclusive), oldest first, within the count and size limits. */
+    list(friendId, options = {}) {
+        const dir = entryDir(this.agentRoot, friendId);
+        const limit = Math.min(Math.max(1, Math.floor(options.limit ?? exports.OUTBOX_LIST_DEFAULT_LIMIT)), exports.OUTBOX_LIST_MAX_LIMIT);
+        const since = options.since ?? "";
+        const ids = sortedIds(dir).filter((id) => id > since);
+        const entries = [];
+        let chars = 0;
+        let more = false;
+        for (const id of ids) {
+            const entry = readEntry(path.join(dir, `${id}.json`));
+            if (!entry)
+                continue;
+            const size = JSON.stringify(entry).length;
+            if (entries.length >= limit || (entries.length > 0 && chars + size > exports.OUTBOX_LIST_MAX_CHARS)) {
+                more = true;
+                break;
+            }
+            entries.push(entry);
+            chars += size;
+        }
+        return { entries, nextCursor: entries.length > 0 ? entries[entries.length - 1].id : null, more };
+    }
+    /** Removes the named entries from this friend's outbox only; ids that are malformed or not there come back as unknown. */
+    ack(friendId, ids) {
+        const dir = entryDir(this.agentRoot, friendId);
+        const acked = [];
+        const unknown = [];
+        for (const id of ids) {
+            const file = isOutboxEntryId(id) ? path.join(dir, `${id}.json`) : null;
+            if (file && fs.existsSync(file)) {
+                fs.rmSync(file, { force: true });
+                acked.push(id);
+            }
+            else {
+                unknown.push(id);
+            }
+        }
+        if (acked.length > 0) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.a2a_outbox_acked",
+                message: "a peer cleared entries from its outbox",
+                meta: { friendId, count: acked.length },
+            });
+        }
+        return { acked, unknown };
+    }
+}
+exports.FileOutboxStore = FileOutboxStore;

package/dist/a2a/outbox-wire.js

@@ -0,0 +1,95 @@
+"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
+ */
+exports.OUTBOX_METHODS = ["outbox/list", "outbox/ack", "report/resolve"];
+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");
+    }
+    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)) {
+        (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);
+    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}`);
+}