@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.920

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, input.now)) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_report_resolve_refused", message: "refused report/resolve from a peer without the escalation grant", meta: { friendId: friend.id } });
+        return refuse("report/resolve needs the escalation grant");
+    }
+    const { id, version, note, resolvedAt, proof } = params;
+    if (typeof id !== "string" || typeof version !== "string" || typeof note !== "string" || typeof resolvedAt !== "string")
+        return invalid("id, version, note and resolvedAt must be strings");
+    // The key is the DID the operator pinned in the root-owned grant, never the friend record; and the A2A-verified caller must be that same DID.
+    const holderDid = (0, escalation_grants_1.pinnedHolderDid)(agentRoot, friend.id, input.now);
+    if (!holderDid || input.verifiedDid !== holderDid) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_report_resolve_refused", message: "refused report/resolve from a caller whose verified DID is not the pinned holder DID", meta: { friendId: friend.id } });
+        return refuse("report not resolved: the caller is not the pinned escalation holder");
+    }
+    const checked = (0, resolution_proof_1.verifyResolution)({ sodium: await (0, a2a_client_1.ready)(), claim: { reportId: id, version, note, resolvedAt }, proof, holderDid });
+    if (!checked.ok)
+        return refuse(`report not resolved: the resolution is not signed by your key (${checked.reason})`);
+    const resolved = await (0, failure_reports_1.resolveFailureReport)(agentRoot, { id, version, note, byFriendId: friend.id, resolvedAt, proof }, input.now);
+    return resolved.ok ? { ok: true, result: { id: resolved.id, status: resolved.status } } : refuse(`report not resolved: ${resolved.reason}`);
+}

package/dist/a2a/pin-store.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileA2APinStore = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const runtime_1 = require("../nerves/runtime");
+function pinFileName(fromAgentId) {
+    return `${(0, node_crypto_1.createHash)("sha256").update(fromAgentId).digest("hex")}.json`;
+}
+class FileA2APinStore {
+    dir;
+    cache = new Map();
+    constructor(agentRoot) {
+        this.dir = path.join(agentRoot, "state", "a2a", "pins");
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.loadExisting();
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_store_init",
+            message: "initialized durable A2A pin store",
+            meta: { dir: this.dir, pins: this.cache.size },
+        });
+    }
+    get size() {
+        return this.cache.size;
+    }
+    get(fromAgentId) {
+        if (!fromAgentId)
+            return undefined;
+        const pinned = this.cache.get(fromAgentId);
+        if (!pinned)
+            return undefined;
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_hit",
+            message: "A2A pin hit",
+            meta: { fromAgentId, did: pinned.did },
+        });
+        return pinned;
+    }
+    set(fromAgentId, pinned) {
+        // An empty-string DID is never a matchable key (security: it can never index a
+        // pin). Stay inert rather than writing an unkeyed pin file.
+        if (!fromAgentId)
+            return;
+        const existed = this.cache.has(fromAgentId);
+        // Faithfully persist the pinned identity's DID (which may differ from
+        // fromAgentId after a rotation), not fromAgentId itself.
+        const stored = {
+            fromAgentId,
+            did: pinned.did,
+            pinnedKey: (0, a2a_client_1.base58btcEncode)(pinned.ed25519Pub),
+        };
+        fs.writeFileSync(path.join(this.dir, pinFileName(fromAgentId)), `${JSON.stringify(stored, null, 2)}\n`, "utf-8");
+        this.cache.set(fromAgentId, { did: pinned.did, ed25519Pub: pinned.ed25519Pub });
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_pin_set",
+            message: "set durable A2A pin",
+            meta: { fromAgentId, did: pinned.did, rotated: existed },
+        });
+    }
+    /** Reload every persisted pin from disk into the in-memory cache (the restart
+     * replay). Corrupt/undecodable files are skipped so one bad file can never
+     * wedge the store. */
+    loadExisting() {
+        let entries;
+        try {
+            entries = fs.readdirSync(this.dir);
+        }
+        catch {
+            /* v8 ignore next -- the constructor mkdirSync's the dir before this runs; unreadable dir is unreachable in practice @preserve */
+            return;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".json"))
+                continue;
+            let stored;
+            try {
+                stored = JSON.parse(fs.readFileSync(path.join(this.dir, name), "utf-8"));
+            }
+            catch {
+                continue;
+            }
+            // `fromAgentId` is the cache key; fall back to `did` for any pre-rotation
+            // file written before the key/did split (back-compat).
+            const key = stored.fromAgentId ?? stored.did;
+            if (!key || !stored.did || !stored.pinnedKey)
+                continue;
+            const ed25519Pub = (0, a2a_client_1.base58btcDecode)(stored.pinnedKey);
+            if (!ed25519Pub)
+                continue;
+            this.cache.set(key, { did: stored.did, ed25519Pub });
+        }
+    }
+}
+exports.FileA2APinStore = FileA2APinStore;

package/dist/a2a/replay-grant-holders.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLAY_GRANT_HOLDERS_FILE = void 0;
+exports.isReplayGrantHolder = isReplayGrantHolder;
+const runtime_1 = require("../nerves/runtime");
+const operator_trust_1 = require("./operator-trust");
+/**
+ * The friends the replay gate provisioned as replay peers, kept by the gate itself as root inside the operator trust directory
+ * (`replay-identities.json`, `{ schemaVersion: 1, grants: { <friend id>: { who, name, did } } }`). A grant for one of them must
+ * carry an expiry (and so must every grant when this file is present but cannot be trusted), so a permanent grant can never be left behind by a replay run. This list is the authority for that rule: the
+ * bundle's own replay registry and a grant's free-text source are the agent's to edit and decide nothing here.
+ */
+exports.REPLAY_GRANT_HOLDERS_FILE = "replay-identities.json";
+function validHolder(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const holder = value;
+    return typeof holder.who === "string" && typeof holder.name === "string" && typeof holder.did === "string";
+}
+/**
+ * True when a grant with no expiry for this friend must be refused. That is the case for a friend the list names, for an entry in the list
+ * that is malformed (its id is read from the file but its content is not trusted), and for every friend when the list is present but
+ * untrusted or malformed: a list the Butler cannot rely on must never let a permanent replay grant through. A list that does not exist
+ * yet (no replay gate has run) names nobody.
+ */
+function isReplayGrantHolder(agentRoot, friendId) {
+    const view = (0, operator_trust_1.readGrantFile)(agentRoot, exports.REPLAY_GRANT_HOLDERS_FILE, validHolder);
+    if (view.state === "untrusted") {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_replay_list_untrusted", message: "the replay list is present but cannot be trusted, so no grant without an expiry is honoured", meta: { file: exports.REPLAY_GRANT_HOLDERS_FILE } });
+        return true;
+    }
+    return Object.prototype.hasOwnProperty.call(view.grants, friendId) || view.ignored.includes(friendId);
+}

package/dist/a2a/replay-harness.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.REPLAY_WINDOW_MAX_MS = void 0;
+exports.replayWindowPath = replayWindowPath;
+exports.replaySinkPath = replaySinkPath;
+exports.replayIdentitiesPath = replayIdentitiesPath;
+exports.isReplayIdentity = isReplayIdentity;
+exports.isReplayWindowOpen = isReplayWindowOpen;
+exports.isAnyReplayWindowOpen = isAnyReplayWindowOpen;
+exports.appendReplayNotice = appendReplayNotice;
+exports.replayNoticeRecorded = replayNoticeRecorded;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../nerves/runtime");
+/**
+ * The replay gate drives the Butler over its real A2A path to check its behaviour after an upgrade. Every delegated
+ * command and every A2A-filed await would otherwise post to the owner's Telegram chat. While the host's gate holds a
+ * replay window open for a peer, those notices are appended to a local sink instead.
+ *
+ * The window narrows where a notice goes, never whether a command is authorized: the grant, family trust, sole owner
+ * and notify-before-run checks are unchanged, and "notify" means "the sink write succeeded". The window file lives
+ * under the bundle's state directory, is written by the host's gate and cleared when its run ends, and every entry
+ * expires on its own (and is ignored if it claims to last longer than the cap).
+ */
+exports.REPLAY_WINDOW_MAX_MS = 2 * 60 * 60 * 1000;
+function replayDir(agentRoot) {
+    return path.join(agentRoot, "state", "replay");
+}
+function replayWindowPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "window.json");
+}
+function replaySinkPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "notices.ndjson");
+}
+/** Permanent registry of replay identities, written by the host's provisioning and never cleared. */
+function replayIdentitiesPath(agentRoot) {
+    return path.join(replayDir(agentRoot), "identities.json");
+}
+function listsFriend(file, friendId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        // A missing file lists nobody; a file that exists but cannot be read or parsed fails closed.
+        return error.code !== "ENOENT";
+    }
+    const friends = parsed?.friends;
+    return !!friends && typeof friends === "object" && Object.hasOwn(friends, friendId);
+}
+/**
+ * True when `friendId` is a replay identity: listed in the permanent registry, or holding any window entry (open or
+ * expired). Unlike the window check this needs no trusted-owner proof, because the marker only ever restricts: forging
+ * an entry can block a friend from writing owner policy, never grant anything. Owner policy writes refuse these identities.
+ */
+function isReplayIdentity(agentRoot, friendId) {
+    return listsFriend(replayIdentitiesPath(agentRoot), friendId) || listsFriend(replayWindowPath(agentRoot), friendId);
+}
+/** A root-controlled directory: a real directory (no symlink), owned by the trusted uid, writable by neither group nor other. */
+function isTrustedDirectory(target, trustedUid) {
+    try {
+        const stat = fs.lstatSync(target);
+        return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === trustedUid && (stat.mode & 0o022) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the window 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 on
+ * the Butler's own state directory cannot swap a different file in between the check and the read. Any error is "no window".
+ */
+function readTrustedWindow(file, trustedUid) {
+    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)
+            return undefined;
+        return JSON.parse(fs.readFileSync(fd, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * True only when the window file lists `friendId` with an expiry that is in the future and within the cap. Any unreadable or malformed file means "closed".
+ * The state directory is the Butler's own, so it could swap in a directory and window of its own making: only a replay
+ * directory and window file that root owns, and nobody else can write, count; anything else fails toward Telegram.
+ */
+const windowEntryOpen = (entry, now) => {
+    const expiresAt = typeof entry?.expiresAt === "string"
+        ? Date.parse(entry.expiresAt)
+        : Number.NaN;
+    return Number.isFinite(expiresAt) && expiresAt > now && expiresAt <= now + exports.REPLAY_WINDOW_MAX_MS;
+};
+function isReplayWindowOpen(agentRoot, friendId, now = Date.now(), trustedUid = 0) {
+    if (!isTrustedDirectory(replayDir(agentRoot), trustedUid))
+        return false;
+    const parsed = readTrustedWindow(replayWindowPath(agentRoot), trustedUid);
+    const friends = parsed?.friends;
+    if (!friends || typeof friends !== "object")
+        return false;
+    return windowEntryOpen(friends[friendId], now);
+}
+/** True while any friend's replay window is open: the gate is running, and background work should stay out of its way. Same trust rules as `isReplayWindowOpen`. */
+function isAnyReplayWindowOpen(agentRoot, now = Date.now(), trustedUid = 0) {
+    if (!isTrustedDirectory(replayDir(agentRoot), trustedUid))
+        return false;
+    const parsed = readTrustedWindow(replayWindowPath(agentRoot), trustedUid);
+    const friends = parsed?.friends;
+    if (!friends || typeof friends !== "object")
+        return false;
+    return Object.values(friends).some((entry) => windowEntryOpen(entry, now));
+}
+/** Appends one notice to the sink, once per notice id and friend (a retry after a crash adds nothing); throws when it cannot be written, so the caller refuses exactly as a failed Telegram send does. */
+function appendReplayNotice(agentRoot, notice, now = Date.now()) {
+    if (replayNoticeRecorded(agentRoot, notice.noticeId, notice.friendId))
+        return;
+    fs.mkdirSync(replayDir(agentRoot), { recursive: true });
+    const line = JSON.stringify({ at: new Date(now).toISOString(), ...notice });
+    fs.appendFileSync(replaySinkPath(agentRoot), `${line}\n`, { mode: 0o600 });
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.a2a_replay_notice_sunk",
+        message: "wrote an owner notice to the replay sink instead of Telegram",
+        meta: { noticeId: notice.noticeId, friendId: notice.friendId },
+    });
+}
+/** True when the sink holds a notice with this id for this friend (a missing sink is "no"). The sink is Butler-writable: callers must also require a trusted window. */
+function replayNoticeRecorded(agentRoot, noticeId, friendId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(replaySinkPath(agentRoot), "utf8");
+    }
+    catch {
+        return false;
+    }
+    return raw.split("\n").some((line) => {
+        if (!line)
+            return false;
+        try {
+            const entry = JSON.parse(line);
+            return entry.noticeId === noticeId && entry.friendId === friendId;
+        }
+        catch {
+            return false;
+        }
+    });
+}

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/sealed-chat.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_CHAT_REPLY = void 0;
+exports.sealChatMessage = sealChatMessage;
+exports.openChatMessage = openChatMessage;
+/**
+ * Sealed agent-to-agent chat over A2A (friends `message` kind).
+ *
+ * Both directions use the same primitive: the text is signed by the sender and
+ * sealed to the recipient inside ONE friends DataPart, so a message is confidential
+ * and tamper-evident over any transport (tailnet, LAN, relay). The network is a
+ * pipe, not the lock.
+ *
+ * - `sealChatMessage` builds the single-DataPart A2A message for a recipient whose
+ *   Ed25519 key the sender already trusts (a pinned DID, or a did:key card).
+ * - `openChatMessage` opens one through the SAME `receiveShare` pipeline every
+ *   friends kind uses (unseal, sender binding, pinned-key signature, replay guard,
+ *   trust floor), pinned to the sender the opener expects. There is no second,
+ *   hand-rolled verification path.
+ */
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+/** What an agent replies when its turn produced no text; sealed like any reply. */
+exports.EMPTY_CHAT_REPLY = "(no reply)";
+/** Seal `text` from `from` to the recipient as a single friends DataPart. Returns
+ * the harness-shaped A2A message; callers add role/messageId/contextId. */
+function sealChatMessage(input) {
+    const text = input.text.trim() === "" ? exports.EMPTY_CHAT_REPLY : input.text.slice(0, friends_1.MAX_MESSAGE_TEXT_CHARS);
+    const prepared = (0, friends_1.prepareMessage)({
+        fromAgentId: input.from.did,
+        text,
+        ...(input.conversationId !== undefined ? { conversationId: input.conversationId } : {}),
+        ...(input.onBehalfOf ? { onBehalfOf: input.onBehalfOf } : {}),
+    });
+    /* v8 ignore next -- the text is normalized above and the sender DID comes from a real identity @preserve */
+    if (!prepared.ok)
+        throw new Error(`cannot prepare chat message: ${prepared.status}`);
+    const sealed = (0, a2a_client_1.sealEnvelope)({
+        sodium: input.sodium,
+        envelope: prepared.envelope,
+        friendsKind: "message",
+        fromIdentity: input.from,
+        recipientDid: input.recipientDid,
+        recipientX25519Pub: (0, a2a_client_1.keyAgreementFromDidKey)({ sodium: input.sodium, ed25519Pub: input.recipientEd25519Pub }),
+    });
+    const wrapped = (0, a2a_client_1.wrapInDataPart)({ sealedEnvelope: sealed, recipientDid: input.recipientDid });
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_chat_sealed",
+        message: "sealed an A2A chat message",
+        meta: { recipientDid: input.recipientDid, chars: text.length },
+    });
+    return { parts: wrapped.parts };
+}
+class MemorySeenLedger {
+    seen = new Set();
+    isSeen(nonce) { return this.seen.has(nonce); }
+    markSeen(nonce) { this.seen.add(nonce); }
+}
+/** A `message` receipt imports nothing, so the stores must never be reached. */
+function unreachableStore(name) {
+    return new Proxy({}, { get() { throw new Error(`sealed chat must not touch the ${name}`); } });
+}
+/** Open a sealed chat message from an expected sender through `receiveShare`. */
+async function openChatMessage(input) {
+    const pinStore = new a2a_client_1.MemoryPinStore();
+    (0, a2a_client_1.pinOnFirstContact)({ pinStore, fromAgentId: input.senderDid, did: input.senderDid, ed25519Pub: input.senderEd25519Pub });
+    const result = await (0, a2a_client_1.receiveShare)({
+        sodium: input.sodium,
+        store: unreachableStore("friend store"),
+        missionStore: unreachableStore("mission store"),
+        pinStore,
+        // Only the pre-pinned sender can verify: any other signer resolves to nothing.
+        didResolution: {
+            async resolveAndPin({ fromAgentId }) {
+                const pinned = pinStore.get(fromAgentId);
+                return pinned ? { ed25519Pub: pinned.ed25519Pub } : null;
+            },
+        },
+        seen: new MemorySeenLedger(),
+        a2aMessage: input.message,
+        recipientDid: input.self.did,
+        recipientIdentity: { x25519Priv: input.self.x25519Priv, x25519Pub: input.self.x25519Pub },
+        // The opener chose this sender; the signature, not this level, is the gate.
+        trustOfSource: "family",
+    });
+    if (result.state === "rejected") {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "channels",
+            event: "channel.a2a_chat_open_rejected",
+            message: "refused a sealed A2A chat message",
+            meta: { senderDid: input.senderDid, reason: result.reason },
+        });
+        return { ok: false, reason: result.reason };
+    }
+    /* v8 ignore next -- any other kind reaches a store, and these stores throw: only a message can complete here @preserve */
+    if (result.friendsKind !== "message" || !result.message)
+        return { ok: false, reason: "not_a_message" };
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_chat_opened",
+        message: "opened a verified A2A chat message",
+        meta: { senderDid: input.senderDid, chars: result.message.text.length },
+    });
+    return {
+        ok: true,
+        text: result.message.text,
+        ...(result.message.conversationId !== undefined ? { conversationId: result.message.conversationId } : {}),
+        issuedAt: result.message.issuedAt,
+    };
+}