@ouro.bot/cli 0.1.0-alpha.876 → 0.1.0-alpha.878

package/dist/a2a/escalation-grants.js

@@ -0,0 +1,122 @@
+"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.escalationGrantsPath = escalationGrantsPath;
+exports.readEscalationGrants = readEscalationGrants;
+exports.setEscalationGrant = setEscalationGrant;
+exports.pinnedHolderDid = pinnedHolderDid;
+exports.holdsEscalation = holdsEscalation;
+exports.escalationHolders = escalationHolders;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const trusted_files_1 = require("./trusted-files");
+function escalationGrantsPath(agentRoot) {
+    return path.join(agentRoot, "state", "a2a", "escalation-grants.json");
+}
+function validGrant(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const grant = value;
+    return Object.keys(grant).sort().join(",") === "did,grantedAt,scope,source"
+        && typeof grant.did === "string" && grant.did.startsWith("did:") && grant.did.length <= 512
+        && grant.scope === "escalation"
+        && typeof grant.grantedAt === "string" && !Number.isNaN(Date.parse(grant.grantedAt))
+        && typeof grant.source === "string" && grant.source.trim().length > 0;
+}
+/** Every well-formed grant in the file, keyed by friend id. Anything else in the file is ignored. */
+function readEscalationGrants(agentRoot) {
+    const file = escalationGrantsPath(agentRoot);
+    if (!(0, trusted_files_1.isTrustedDirectory)(path.dirname(file)))
+        return {};
+    const parsed = (0, trusted_files_1.readTrustedJson)(file);
+    const grants = parsed?.grants;
+    if (!grants || typeof grants !== "object" || Array.isArray(grants))
+        return {};
+    return Object.fromEntries(Object.entries(grants).filter((entry) => validGrant(entry[1])));
+}
+/** Run as root, the operator's grant leaves the file and its directory root-owned and closed to everyone else, even if an earlier recursive chown had handed them to the resident. */
+function ownAsRoot(target, mode) {
+    fs.chownSync(target, 0, 0);
+    fs.chmodSync(target, mode);
+}
+/** Writes or removes one grant. The previous file is kept beside it as a timestamped backup before the change. */
+function setEscalationGrant(agentRoot, friendId, change, now = new Date()) {
+    const file = escalationGrantsPath(agentRoot);
+    // Root repairs the directory first; a grants file the resident owns stays untrusted and is replaced, never blessed.
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o755 });
+    if (process.geteuid?.() === 0)
+        ownAsRoot(path.dirname(file), 0o755);
+    const current = readEscalationGrants(agentRoot);
+    const had = current[friendId];
+    if (change.grant ? had?.did === change.did : had === undefined)
+        return { changed: false, backup: null };
+    let backup = null;
+    if (fs.existsSync(file)) {
+        backup = `${file}.bak-${now.toISOString().replace(/[:.]/gu, "-")}`;
+        fs.copyFileSync(file, backup);
+    }
+    const next = { ...current };
+    if (change.grant)
+        next[friendId] = { scope: "escalation", grantedAt: now.toISOString(), source: change.source, did: change.did };
+    else
+        delete next[friendId];
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify({ schemaVersion: 1, grants: next }, null, 2)}\n`, { mode: 0o644 });
+    fs.renameSync(tmp, file);
+    if (process.geteuid?.() === 0)
+        ownAsRoot(file, 0o644);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.a2a_escalation_grant_changed",
+        message: change.grant ? "granted escalation to an A2A peer" : "revoked an A2A peer's escalation grant",
+        meta: { friendId, granted: change.grant },
+    });
+    return { changed: true, backup };
+}
+/** The DID the operator pinned for this holder, or null when it holds no (complete) grant. */
+function pinnedHolderDid(agentRoot, friendId) {
+    return readEscalationGrants(agentRoot)[friendId]?.did ?? null;
+}
+/** True only for an active family friend that the operator listed in the grants file, with a pinned DID. */
+function holdsEscalation(agentRoot, friend) {
+    return readEscalationGrants(agentRoot)[friend.id] !== undefined
+        && friend.trustLevel === "family"
+        && friend.admissionState === "active";
+}
+async function escalationHolders(agentRoot, store) {
+    const friends = await store.listAll?.() ?? [];
+    return friends.filter((friend) => holdsEscalation(agentRoot, friend));
+}

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