@ouro.bot/cli 0.1.0-alpha.877 → 0.1.0-alpha.879

package/dist/a2a/escalation-wiring.js

@@ -0,0 +1,60 @@
+"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.RUNNING_HARNESS_VERSION = void 0;
+exports.escalationOptionsFor = escalationOptionsFor;
+exports.sendOwnerNoticeViaTelegram = sendOwnerNoticeViaTelegram;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The version of the harness that is running, read from its own package.json once when this module loads. A fix is
+ * "live" only when this process carries it, so the value must not follow whatever an upgrade later writes to disk.
+ */
+exports.RUNNING_HARNESS_VERSION = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../../package.json"), "utf8")).version;
+/**
+ * What every A2A server entry point passes as `escalation`: confirm-when-live notices go to the owner through the same
+ * owner-notice path as delegated commands. Only the Butler files and confirms failure reports.
+ */
+function escalationOptionsFor(agentName, sendOwnerNotice) {
+    if (agentName !== "sanctuary")
+        return {};
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_escalation_wired", message: "A2A server will confirm resolved failure reports to the owner", meta: { agentName, runningVersion: exports.RUNNING_HARNESS_VERSION } });
+    return { escalation: { runningVersion: exports.RUNNING_HARNESS_VERSION, notifyOwner: sendOwnerNotice } };
+}
+async function sendOwnerNoticeViaTelegram(agentName, notice) {
+    const { sendTelegramOwnerNotice } = await Promise.resolve().then(() => __importStar(require("../senses/telegram")));
+    await sendTelegramOwnerNotice(agentName, { ...notice, signal: AbortSignal.timeout(30_000) });
+}

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}`);
+}

package/dist/a2a/resolution-proof.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signResolution = signResolution;
+exports.friendDid = friendDid;
+exports.verifyResolution = verifyResolution;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The proof that an escalation holder, and nobody who can write the Butler's files, said a failure report is fixed.
+ * The holder signs `{reportId, version, note, resolvedAt}` with its DID key (canonical JSON, detached Ed25519), and
+ * the Butler keeps the signature next to the resolution. The holder's private key never leaves the holder's machine,
+ * so a forged report file cannot carry a valid one.
+ */
+const PURPOSE = "ouro.report-resolve.v1";
+function envelopeOf(claim) {
+    return { purpose: PURPOSE, reportId: claim.reportId, version: claim.version, note: claim.note, resolvedAt: claim.resolvedAt };
+}
+function signResolution(input) {
+    const { claim } = input;
+    return (0, a2a_client_1.signEnvelope)({
+        sodium: input.sodium,
+        envelope: envelopeOf(claim),
+        signerEd25519Priv: input.identity.ed25519Priv,
+        signerDid: input.identity.did,
+        signerKeyId: input.identity.keyId,
+    });
+}
+/** The DID a friend record names. Used only by the operator command that pins it into the grant; never to verify a resolution. */
+function friendDid(friend) {
+    return (0, friends_1.resolveAgentIdentity)(friend.agentMeta).did ?? null;
+}
+function verifyResolution(input) {
+    const fail = (reason) => {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_resolution_proof_rejected", message: "rejected a report resolution without a valid holder signature", meta: { reportId: input.claim.reportId, reason } });
+        return { ok: false, reason };
+    };
+    const proof = input.proof;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof))
+        return fail("no_proof");
+    if (!input.holderDid)
+        return fail("no_holder_did");
+    const parsed = (0, a2a_client_1.parseDidKey)(input.holderDid);
+    if (!parsed || proof.signerDid !== input.holderDid)
+        return fail("wrong_signer");
+    const valid = (0, a2a_client_1.verifyEnvelopeSignature)({
+        sodium: input.sodium,
+        envelope: envelopeOf(input.claim),
+        proof: proof,
+        signerEd25519Pub: parsed.ed25519Pub,
+    });
+    return valid ? { ok: true } : fail("bad_signature");
+}

package/dist/a2a/server.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ESCALATION_CONFIRM_INTERVAL_MS = void 0;
 exports.a2aChatRelationship = a2aChatRelationship;
 exports.startA2AServer = startA2AServer;
 const http = __importStar(require("node:http"));
@@ -55,8 +56,11 @@ const mission_result_wire_1 = require("./mission-result-wire");
 const delegation_stores_1 = require("./delegation-stores");
 const task_store_1 = require("./task-store");
 const delegated_command_1 = require("./delegated-command");
+const outbox_wire_1 = require("./outbox-wire");
+const failure_reports_1 = require("../heart/failure-reports");
 const MAX_A2A_REQUEST_BYTES = 128 * 1024;
 const MAX_A2A_MESSAGE_TEXT_CHARS = 16_000;
+exports.ESCALATION_CONFIRM_INTERVAL_MS = 5 * 60 * 1000;
 class A2ARequestError extends Error {
     status;
     code;
@@ -394,6 +398,19 @@ async function startA2AServer(options) {
             identity: options.identity,
         };
     }
+    // Resolved failure reports are confirmed to the owner once the running version reaches the fix: now, after each
+    // resolution, and on a timer, so a fix that lands with a restart is announced without anyone calling again.
+    const confirmReports = async () => {
+        if (!options.escalation)
+            return;
+        try {
+            await (0, failure_reports_1.confirmResolvedReports)(agentRoot, { ...options.escalation, ...(inboundShareDeps ? { friends: inboundShareDeps.store } : {}) });
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "channels", event: "channel.a2a_escalation_confirm_error", message: "confirming resolved failure reports failed", meta: { agentName: options.agentName, error: error instanceof Error ? error.message : String(error) } });
+        }
+    };
+    let confirmTimer;
     let publicBaseUrl = options.baseUrl;
     const server = http.createServer(async (req, res) => {
         /* v8 ignore next -- Node always supplies url/host for accepted HTTP requests; fallback keeps malformed local calls safe @preserve */
@@ -427,6 +444,48 @@ async function startA2AServer(options) {
             return;
         }
         try {
+            if ((0, outbox_wire_1.isOutboxMethod)(rpc.method)) {
+                // Peer outbox methods: signed and sealed like a chat, access decided here from the verified friend record.
+                const outboxInbound = messageFromParams(rpc.params);
+                if (!outboxInbound || !inboundShareDeps) {
+                    writeJson(res, 200, errorResponse(rpc.id, outbox_wire_1.OUTBOX_ERROR_REFUSED, "outbox calls need a signed message and an A2A identity"));
+                    return;
+                }
+                const bridged = await (0, inbound_share_1.receiveInboundShare)({ ...outboxInbound, kind: outboxInbound.kind ?? "message" }, inboundShareDeps);
+                if (bridged.outcome === "rejected") {
+                    writeJson(res, 200, errorResponse(rpc.id, rejectionErrorCode(bridged.reason), `A2A outbox call rejected: ${bridged.reason}`));
+                    return;
+                }
+                if (bridged.outcome !== "completed" || !bridged.message) {
+                    writeJson(res, 200, errorResponse(rpc.id, outbox_wire_1.OUTBOX_ERROR_REFUSED, "outbox calls must be a signed chat message"));
+                    return;
+                }
+                const command = (0, outbox_wire_1.parseOutboxCommand)(bridged.message.text);
+                if (!command || command.method !== rpc.method) {
+                    writeJson(res, 200, errorResponse(rpc.id, outbox_wire_1.OUTBOX_ERROR_INVALID, "the signed method does not match the requested method"));
+                    return;
+                }
+                const outcome = await (0, outbox_wire_1.handleOutboxCommand)({ agentRoot, friend: bridged.friend, method: command.method, params: command.params, verifiedDid: bridged.verifiedDid });
+                if (!outcome.ok) {
+                    writeJson(res, 200, errorResponse(rpc.id, outcome.code, outcome.message));
+                    return;
+                }
+                if (command.method === "report/resolve")
+                    await confirmReports();
+                /* v8 ignore next -- receiveShare pins the verified sender before it reports a completed message @preserve */
+                const outboxPinned = inboundShareDeps.pinStore.get(bridged.verifiedDid);
+                const contextId = outboxInbound.contextId ?? "default";
+                const reply = (0, sealed_chat_1.sealChatMessage)({
+                    sodium: inboundShareDeps.sodium,
+                    from: options.identity,
+                    recipientDid: bridged.verifiedDid,
+                    recipientEd25519Pub: outboxPinned.ed25519Pub,
+                    text: JSON.stringify(outcome.result),
+                    conversationId: contextId,
+                });
+                writeJson(res, 200, jsonResponse(rpc.id, { kind: "message", role: "ROLE_AGENT", messageId: (0, node_crypto_1.randomUUID)(), contextId, parts: reply.parts }));
+                return;
+            }
             if (rpc.method === "SendMessage" || rpc.method === "message/send") {
                 const responseStyle = rpc.method === "message/send" ? "legacy" : "latest";
                 const parsedInbound = messageFromParams(rpc.params);
@@ -671,6 +730,11 @@ async function startA2AServer(options) {
     endpointUrl.pathname = a2aPath;
     endpointUrl.search = "";
     endpointUrl.hash = "";
+    if (options.escalation) {
+        await confirmReports();
+        confirmTimer = setInterval(() => { void confirmReports(); }, options.escalation.confirmIntervalMs ?? exports.ESCALATION_CONFIRM_INTERVAL_MS);
+        confirmTimer.unref();
+    }
     (0, runtime_1.emitNervesEvent)({
         component: "channels",
         event: "channel.a2a_server_started",
@@ -682,6 +746,8 @@ async function startA2AServer(options) {
         url: publicBaseUrl,
         endpointUrl: endpointUrl.toString(),
         close: () => new Promise((resolve, reject) => {
+            if (confirmTimer)
+                clearInterval(confirmTimer);
             server.close((error) => {
                 if (error) {
                     reject(error);

package/dist/a2a/trusted-files.js

@@ -0,0 +1,98 @@
+"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.TRUSTED_UID = void 0;
+exports.overrideTrustedUidForTests = overrideTrustedUidForTests;
+exports.isTrustedDirectory = isTrustedDirectory;
+exports.readTrustedJson = readTrustedJson;
+const fs = __importStar(require("node:fs"));
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Operator-set state lives in the agent bundle, which the agent's own process (and anything a prompt-injected model can
+ * run through its shell) can write. Such state only counts when root owns it and nobody else can write it, the same
+ * rule the replay window follows. Anything else reads as "not there", so every consumer fails closed.
+ */
+exports.TRUSTED_UID = 0;
+let uidOverride;
+/** Only a test runner sets VITEST; the running Butler (and its prompt-injected shell) cannot reach this process's environment. */
+const underTestRunner = () => process.env.VITEST !== undefined;
+/** Tests run as an ordinary user, so they declare that user trusted. Refused outside a test runner, and ignored there too. */
+function overrideTrustedUidForTests(uid) {
+    if (!underTestRunner())
+        throw new Error("overrideTrustedUidForTests is for tests only");
+    uidOverride = uid;
+}
+const effectiveTrustedUid = () => (underTestRunner() ? uidOverride : undefined) ?? exports.TRUSTED_UID;
+/** A real directory (no symlink), owned by the trusted uid, writable by neither group nor other. */
+function isTrustedDirectory(target, trustedUid = effectiveTrustedUid()) {
+    let stat;
+    try {
+        stat = fs.lstatSync(target);
+    }
+    catch {
+        return false;
+    }
+    const trusted = stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === trustedUid && (stat.mode & 0o022) === 0;
+    if (!trusted)
+        rejected(target, "directory is not a real directory owned by the trusted uid and closed to group and other writes");
+    return trusted;
+}
+function rejected(target, reason) {
+    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_trusted_file_rejected", message: "ignored operator-set state the agent could have written", meta: { target, reason } });
+}
+/**
+ * Parses a JSON file only if the file actually opened is trusted. The path is opened once with O_NOFOLLOW, then the
+ * descriptor itself is checked (regular file, trusted owner, not group- or other-writable) and read, so a rename loop
+ * cannot swap a different file in between the check and the read. Any error is `undefined`.
+ */
+function readTrustedJson(file, trustedUid = effectiveTrustedUid()) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.uid !== trustedUid || (stat.mode & 0o022) !== 0) {
+            rejected(file, "file is not a regular file owned by the trusted uid and closed to group and other writes");
+            return undefined;
+        }
+        return JSON.parse(fs.readFileSync(fd, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}