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

package/dist/a2a/delegation-stores.js

@@ -0,0 +1,56 @@
+"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.delegationStoresFor = delegationStoresFor;
+const path = __importStar(require("node:path"));
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+function delegationStoresFor(agentRoot) {
+    const friendsDir = path.join(agentRoot, "friends");
+    const missionsDir = (0, friends_1.missionsDirFor)(friendsDir);
+    const grantsDir = (0, friends_1.grantsDirFor)(friendsDir);
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_delegation_stores_init",
+        message: "initialized A2A delegation stores (mission + grant)",
+        meta: { missionsDir, grantsDir },
+    });
+    return {
+        missionStore: new friends_1.FileMissionStore(missionsDir),
+        grantStore: new friends_1.FileGrantStore(grantsDir),
+        missionsDir,
+        grantsDir,
+    };
+}

package/dist/a2a/did-resolution.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeDidResolution = makeDidResolution;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+/** Why a record could not move, in words an owner can read. A reason a later friends adds fails the type check. */
+const MOVE_FAILURE_WORDS = {
+    rotation_not_accepted: "this agent's saved keys do not show the change cleanly",
+    rotation_chain_invalid: "its chain of key changes loops or is too long",
+    record_not_found: "its friend record was not found under any of its earlier keys",
+    successor_already_linked: "another friend record already holds the new key",
+};
+/** At most this many earlier DIDs are followed back from a rotated pin (friends' `MAX_ROTATION_HOPS`). */
+const MAX_PREDECESSOR_HOPS = 16;
+function refused(fromAgentId, reason, message) {
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_did_resolve_refused", message, meta: { fromAgentId, reason } });
+    return null;
+}
+/**
+ * Build the friends `DidResolution` for did:key peers. `resolveAndPin` is the verify-and-pin core the inbound bridge
+ * consumes. friends calls it with the SIGNED sender DID as both `fromAgentId` and `did`, so pins are keyed by DID:
+ *   unparseable or empty DID, or a retired pin  → refused (null)
+ *   pinned                                       → the pinned key (a did:key's key cannot change under the same DID)
+ *   not pinned, with a successor statement       → `evaluateRotation` from the old DID (at the OLD record's trust);
+ *                                                  accepted: `applyAcceptedRotation` moves the record, then the new key
+ *                                                  rejected: refused, never a silent first contact
+ *   not pinned, no statement                     → first contact (TOFU `pinOnFirstContact`)
+ * The receive paths call `settleSender` first, so by the time `resolveAndPin` runs a rotation is already applied.
+ */
+function makeDidResolution(input) {
+    const { sodium, store, successorFor } = input;
+    const toldOwner = new Set();
+    /** Tell the owner, once per rotation, that the record could not follow and how to fix it. */
+    function tellOwner(oldDid, newDid, record, holder, reason) {
+        const notify = input.notifyOwner;
+        const key = `${oldDid}>${newDid}`;
+        if (!notify || toldOwner.has(key))
+            return;
+        toldOwner.add(key);
+        const agent = input.agentName ?? "<agent>";
+        const [cause, command] = holder
+            ? [
+                `Its new key is already linked to another friend record, ${holder.name} (${holder.id}). If that is the same peer, merge the two records`,
+                `ouro friend merge --agent ${agent} --into ${record.id} ${holder.id} --apply`,
+            ]
+            : [
+                `The record could not move because ${MOVE_FAILURE_WORDS[reason]}. Link the record to the new key`,
+                `ouro friend link ${agent} --friend ${record.id} --provider a2a-agent --external-id ${newDid}`,
+            ];
+        // The command sits on its own line with nothing after it, so it can be copied as is.
+        const notice = {
+            noticeId: `a2a-rotation-unmoved:${(0, node_crypto_1.createHash)("sha256").update(key).digest("hex").slice(0, 32)}`,
+            text: [
+                `${record.name} changed its A2A key to ${newDid}, but its friend record could not move to the new key, so this agent refuses its messages until this is fixed.`,
+                `${cause}. Run:`,
+                command,
+                `${record.name}'s next message then moves the record.`,
+            ].join("\n\n"),
+        };
+        notify(notice).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "channels",
+                event: "channel.a2a_rotation_notice_failed",
+                message: "could not tell the owner that a rotated peer's record did not move",
+                meta: { oldDid, newDid, error: error instanceof Error ? error.message : String(error) },
+            });
+        });
+    }
+    /** Move the peer's record along the rotation chain to `newDid`. On failure, warn and tell the owner. */
+    async function moveRecord(friends, pinStore, oldDid, newDid, record) {
+        const moved = await (0, a2a_client_1.applyAcceptedRotation)({ store: friends, pinStore, oldDid, newDid });
+        if (moved.ok)
+            return true;
+        // The pins moved but the friend record did not follow (another record already holds the new DID, or the chain is
+        // broken). Refuse rather than run the message under a record that does not carry the old trust.
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "channels",
+            event: "channel.a2a_rotation_record_not_moved",
+            message: "A2A key rotation verified but the friend record could not follow; refusing the message",
+            meta: { oldDid, newDid, reason: moved.reason },
+        });
+        tellOwner(oldDid, newDid, record, await friends.findByExternalId("a2a-agent", newDid), moved.reason);
+        return false;
+    }
+    /** Judge a successor statement for an unpinned DID and, when accepted, move the record. */
+    async function rotateIn(pinStore, did, ed25519Pub, statement) {
+        // A rotation is judged at the trust of the peer the OLD DID belongs to: the new DID itself is still unknown.
+        const oldRecord = store ? await store.findByExternalId("a2a-agent", statement.oldDid) : null;
+        const oldTrust = oldRecord?.trustLevel ?? "stranger";
+        const decision = (0, a2a_client_1.evaluateRotation)({
+            sodium,
+            pinStore,
+            fromAgentId: statement.oldDid,
+            trustOfSource: oldTrust,
+            newDid: did,
+            newEd25519Pub: ed25519Pub,
+            rotationProof: statement.rotationProof,
+            successorProof: statement.successorProof,
+            issuedAt: statement.issuedAt,
+        });
+        if (decision.decision !== "accepted") {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "channels",
+                event: "channel.a2a_rotation_rejected",
+                message: "A2A key rotation rejected",
+                /* v8 ignore next -- the new DID has no pin, so evaluateRotation cannot call it unchanged @preserve */
+                meta: { oldDid: statement.oldDid, newDid: did, trustOfSource: oldTrust, reason: decision.decision === "rejected" ? decision.reason : decision.decision },
+            });
+            return false;
+        }
+        // Accepted means the old record is family or friend, which was read from `store`, so both are present.
+        if (!(await moveRecord(store, pinStore, statement.oldDid, did, oldRecord)))
+            return false;
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_rotation_accepted",
+            message: "A2A signed key rotation accepted",
+            meta: { oldDid: statement.oldDid, newDid: did, trustOfSource: oldTrust },
+        });
+        return true;
+    }
+    /**
+     * A pin that a rotation moved to `did`: if the peer's record still sits at an earlier DID on the chain, the move
+     * failed earlier, so retry it. Returns false while the record still cannot follow.
+     */
+    async function finishMove(pinStore, did) {
+        if (!store || typeof pinStore.predecessorOf !== "function")
+            return true;
+        const chain = [];
+        for (let prev = pinStore.predecessorOf(did); prev !== undefined && chain.length < MAX_PREDECESSOR_HOPS; prev = pinStore.predecessorOf(prev)) {
+            chain.unshift(prev);
+        }
+        for (const earlier of chain) {
+            const record = await store.findByExternalId("a2a-agent", earlier);
+            if (!record)
+                continue;
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_rotation_record_retry",
+                message: "a rotated peer's friend record is still at its old DID; retrying the move",
+                meta: { oldDid: earlier, newDid: did },
+            });
+            if (!(await moveRecord(store, pinStore, chain[0], did, record)))
+                return false;
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_rotation_record_moved",
+                message: "moved a rotated peer's friend record to its new DID",
+                meta: { oldDid: earlier, newDid: did },
+            });
+            return true;
+        }
+        return true;
+    }
+    return {
+        async settleSender({ did, pinStore }) {
+            const parsed = (0, a2a_client_1.parseDidKey)(did);
+            // An unusable DID is refused by `resolveAndPin` itself.
+            if (!parsed)
+                return true;
+            const pinned = pinStore.get(did);
+            if (pinned)
+                return pinned.rotatedAt !== undefined && pinned.retiredBy === undefined ? finishMove(pinStore, did) : true;
+            const statement = successorFor?.(did, parsed.ed25519Pub);
+            return statement ? rotateIn(pinStore, did, parsed.ed25519Pub, statement) : true;
+        },
+        async resolveAndPin(args) {
+            const { fromAgentId, did, pinStore } = args;
+            if (!did)
+                return refused(fromAgentId, "empty_did", "A2A DID resolve refused (empty DID)");
+            const parsed = (0, a2a_client_1.parseDidKey)(did);
+            if (!parsed)
+                return refused(fromAgentId, "parse_failed", "A2A DID resolve refused (unparseable did:key)");
+            const pinned = pinStore.get(fromAgentId);
+            // A retired pin is a tombstone: the old key must never verify again (friends requires hosts to enforce this).
+            if (pinned?.retiredBy !== undefined)
+                return refused(fromAgentId, "retired_pin", "A2A DID resolve refused (the DID was rotated away)");
+            if (pinned) {
+                const decision = (0, a2a_client_1.evaluateRotation)({ sodium, pinStore, fromAgentId, trustOfSource: args.trustOfSource, newDid: did, newEd25519Pub: parsed.ed25519Pub });
+                if (decision.decision === "unchanged")
+                    return { ed25519Pub: parsed.ed25519Pub };
+                // A did:key encodes its key, so a differing pin means the pin was filed under another DID (or edited by hand).
+                /* v8 ignore next -- evaluateRotation only returns "accepted" with a proof, and none is passed here @preserve */
+                return refused(fromAgentId, decision.decision === "rejected" ? decision.reason : "key_changed", "A2A DID resolve refused (pinned key differs)");
+            }
+            const statement = successorFor?.(did, parsed.ed25519Pub);
+            if (!statement) {
+                // First contact (TOFU): accept + pin the (did, key) under fromAgentId.
+                (0, a2a_client_1.pinOnFirstContact)({ pinStore, fromAgentId, did, ed25519Pub: parsed.ed25519Pub });
+                (0, runtime_1.emitNervesEvent)({
+                    component: "channels",
+                    event: "channel.a2a_pin_first_contact",
+                    message: "A2A DID pinned on first contact",
+                    meta: { fromAgentId, did },
+                });
+                return { ed25519Pub: parsed.ed25519Pub };
+            }
+            return (await rotateIn(pinStore, did, parsed.ed25519Pub, statement)) ? { ed25519Pub: parsed.ed25519Pub } : null;
+        },
+    };
+}

package/dist/a2a/escalation-grants.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ESCALATION_GRANTS_FILE = void 0;
+exports.escalationGrantsPath = escalationGrantsPath;
+exports.viewEscalationGrants = viewEscalationGrants;
+exports.readEscalationGrants = readEscalationGrants;
+exports.setEscalationGrant = setEscalationGrant;
+exports.pinnedHolderDid = pinnedHolderDid;
+exports.holdsEscalation = holdsEscalation;
+exports.escalationHolders = escalationHolders;
+const runtime_1 = require("../nerves/runtime");
+const replay_grant_holders_1 = require("./replay-grant-holders");
+const operator_trust_1 = require("./operator-trust");
+exports.ESCALATION_GRANTS_FILE = "escalation-grants.json";
+function escalationGrantsPath(agentRoot) {
+    return (0, operator_trust_1.operatorTrustFile)(agentRoot, exports.ESCALATION_GRANTS_FILE);
+}
+function validGrant(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const grant = value;
+    const keys = Object.keys(grant).sort().join(",");
+    return (keys === "did,grantedAt,scope,source" || keys === "did,expiresAt,grantedAt,scope,source")
+        && (grant.expiresAt === undefined || typeof grant.expiresAt === "string")
+        && 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;
+}
+/** The file's trust state and every well-formed grant in it, keyed by friend id. */
+function viewEscalationGrants(agentRoot) {
+    return (0, operator_trust_1.readGrantFile)(agentRoot, exports.ESCALATION_GRANTS_FILE, validGrant);
+}
+/** Every well-formed grant in the file, keyed by friend id. Anything else in the file is ignored. */
+function readEscalationGrants(agentRoot) {
+    return viewEscalationGrants(agentRoot).grants;
+}
+/** 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()) {
+    return (0, operator_trust_1.withTrustedWriteLock)(agentRoot, () => setEscalationGrantLocked(agentRoot, friendId, change, now));
+}
+function setEscalationGrantLocked(agentRoot, friendId, change, now) {
+    const current = readEscalationGrants(agentRoot);
+    const had = current[friendId];
+    if (change.grant ? had?.did === change.did && had.expiresAt === change.expiresAt : had === undefined)
+        return { changed: false, backup: null };
+    const next = { ...current };
+    if (change.grant)
+        next[friendId] = { scope: "escalation", grantedAt: now.toISOString(), source: change.source, did: change.did, ...(change.expiresAt ? { expiresAt: change.expiresAt } : {}) };
+    else
+        delete next[friendId];
+    const { backup } = (0, operator_trust_1.writeTrustedFile)(agentRoot, exports.ESCALATION_GRANTS_FILE, `${JSON.stringify({ schemaVersion: 1, grants: next }, null, 2)}\n`, now);
+    (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 };
+}
+/** A grant is in force when its trusted expiry has not passed; a grant with no expiry for a friend on the root-owned replay list is never in force. */
+function inForce(agentRoot, friendId, grant, now) {
+    if (!grant)
+        return false;
+    if (grant.expiresAt === undefined)
+        return !(0, replay_grant_holders_1.isReplayGrantHolder)(agentRoot, friendId);
+    const expiresAt = Date.parse(grant.expiresAt);
+    return Number.isFinite(expiresAt) && expiresAt > now;
+}
+/** The DID the operator pinned for this holder, or null when it holds no (complete, unexpired) grant. */
+function pinnedHolderDid(agentRoot, friendId, now = Date.now()) {
+    const grant = readEscalationGrants(agentRoot)[friendId];
+    return inForce(agentRoot, friendId, grant, now) ? grant.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, now = Date.now()) {
+    return inForce(agentRoot, friend.id, readEscalationGrants(agentRoot)[friend.id], now)
+        && friend.trustLevel === "family"
+        && friend.admissionState === "active";
+}
+async function escalationHolders(agentRoot, store, now = Date.now()) {
+    const friends = await store.listAll?.() ?? [];
+    return friends.filter((friend) => holdsEscalation(agentRoot, friend, now));
+}

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/identity.js

@@ -0,0 +1,258 @@
+"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.PUBLIC_A2A_IDENTITY_FILE = void 0;
+exports.readStoredA2ASeed = readStoredA2ASeed;
+exports.loadOrMintA2AIdentity = loadOrMintA2AIdentity;
+exports.loadSelfA2AIdentity = loadSelfA2AIdentity;
+exports.publishOwnA2ADid = publishOwnA2ADid;
+exports.readPublishedA2ADid = readPublishedA2ADid;
+exports.readOwnA2ADid = readOwnA2ADid;
+exports.loadOrMintA2AIdentityFile = loadOrMintA2AIdentityFile;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const runtime_1 = require("../nerves/runtime");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const machine_identity_1 = require("../heart/machine-identity");
+/** The number of raw bytes in an Ed25519 seed. */
+const ED25519_SEED_BYTES = 32;
+/** The machine-config key path for the persisted seed: `a2a.identity.ed25519Seed`. */
+function a2aIdentityConfig(config) {
+    const a2a = config.a2a;
+    if (!a2a || typeof a2a !== "object" || Array.isArray(a2a))
+        return undefined;
+    const identity = a2a.identity;
+    if (!identity || typeof identity !== "object" || Array.isArray(identity))
+        return undefined;
+    return identity;
+}
+/** Read the stored Ed25519 seed string from a machine-config object, or undefined. */
+function readStoredA2ASeed(config) {
+    const identity = a2aIdentityConfig(config);
+    const seed = identity?.ed25519Seed;
+    return typeof seed === "string" && seed.length > 0 ? seed : undefined;
+}
+/** Decode + validate a stored seed string into 32 raw bytes. Throws on malformed. */
+function decodeSeed(seedString) {
+    let decoded;
+    try {
+        decoded = Buffer.from(seedString, "base64url");
+    }
+    catch {
+        /* v8 ignore next -- Buffer.from(base64url) does not throw on bad chars; this guards future decoders @preserve */
+        throw new Error("malformed A2A identity seed: not decodable");
+    }
+    // base64url is lenient (it silently drops invalid chars), so the length check is
+    // the real gate: a real Ed25519 seed is exactly 32 bytes.
+    if (decoded.length !== ED25519_SEED_BYTES) {
+        throw new Error(`malformed A2A identity seed: expected ${ED25519_SEED_BYTES}-byte seed, got ${decoded.length}`);
+    }
+    return new Uint8Array(decoded);
+}
+/** Mint a fresh 32-byte Ed25519 seed (Node keygen → JWK `d`, the raw seed). */
+function mintSeed() {
+    const { privateKey } = crypto.generateKeyPairSync("ed25519");
+    const jwk = privateKey.export({ format: "jwk" });
+    /* v8 ignore next -- Node always emits the `d` field for an Ed25519 private JWK; guard protects future runtimes @preserve */
+    if (typeof jwk.d !== "string")
+        throw new Error("failed to mint A2A identity seed: missing JWK d");
+    return decodeSeed(jwk.d);
+}
+/** Derive the full did:key identity from a 32-byte seed (deterministic). */
+function deriveIdentity(sodium, seed) {
+    const keypair = sodium.crypto_sign_seed_keypair(seed);
+    const didIdentity = (0, a2a_client_1.didKeyIdentityFromEd25519)({
+        sodium,
+        ed25519Pub: keypair.publicKey,
+        ed25519Priv: keypair.privateKey,
+    });
+    return { ...didIdentity, seed: Buffer.from(seed).toString("base64url") };
+}
+/**
+ * Load the agent's A2A identity from the machine-local config, or mint + persist
+ * one on first use. A malformed stored seed FAILS FAST (it never silently
+ * re-mints, which would change the agent's DID). The mint path persists the new
+ * seed via `upsert` before deriving; the load path performs no writes.
+ */
+async function loadOrMintA2AIdentity(input) {
+    const stored = readStoredA2ASeed(input.config);
+    if (stored) {
+        // Load path: a malformed seed throws (no re-mint).
+        const seed = decodeSeed(stored);
+        const identity = deriveIdentity(input.sodium, seed);
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_identity_loaded",
+            message: "loaded A2A identity from machine config",
+            meta: { agentName: input.agentName, did: identity.did },
+        });
+        return identity;
+    }
+    // Mint path: generate a seed, persist it under a2a.identity.*, then derive.
+    const seed = mintSeed();
+    const seedString = Buffer.from(seed).toString("base64url");
+    const a2a = (input.config.a2a && typeof input.config.a2a === "object" && !Array.isArray(input.config.a2a)
+        ? input.config.a2a
+        : {});
+    const identityBlock = (a2a.identity && typeof a2a.identity === "object" && !Array.isArray(a2a.identity)
+        ? a2a.identity
+        : {});
+    const nextConfig = {
+        ...input.config,
+        a2a: { ...a2a, identity: { ...identityBlock, ed25519Seed: seedString } },
+    };
+    await input.upsert(nextConfig);
+    const identity = deriveIdentity(input.sodium, seed);
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_identity_minted",
+        message: "minted new A2A identity and persisted seed to machine config",
+        meta: { agentName: input.agentName, did: identity.did },
+    });
+    return identity;
+}
+/**
+ * Load (or mint-on-first-use) THIS agent's own A2A identity from the machine-local
+ * runtime config — the convenience entry the main-process tools use to obtain the
+ * self identity that signs outbound sealed envelopes. Mirrors the a2a sense
+ * entrypoint's load (use a cached seed when present, otherwise refresh machine
+ * config → `loadOrMintA2AIdentity` → merge a fresh seed under the right machine
+ * id). `sodium` is optional (defaults to `ready()`).
+ */
+async function loadSelfA2AIdentity(input) {
+    const sodium = input.sodium ?? await (0, a2a_client_1.ready)();
+    const machineId = (0, machine_identity_1.loadOrCreateMachineIdentity)({ homeDir: os.homedir() }).machineId;
+    const cached = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(input.agentName);
+    const read = cached.ok && readStoredA2ASeed(cached.config)
+        ? cached
+        : await (0, runtime_credentials_1.refreshMachineRuntimeCredentialConfig)(input.agentName, machineId);
+    if (!read.ok && read.reason !== "missing") {
+        throw new Error(`A2A identity requires readable machine runtime config at ${read.itemPath}: ${read.error}`);
+    }
+    const config = read.ok ? read.config : {};
+    return loadOrMintA2AIdentity({
+        agentName: input.agentName,
+        sodium,
+        config,
+        upsert: async (next) => {
+            const seed = readStoredA2ASeed(next);
+            await (0, runtime_credentials_1.mergeMachineRuntimeCredentialConfig)(input.agentName, machineId, { a2a: { identity: { ed25519Seed: seed } } });
+        },
+    });
+}
+/** Where the agent publishes its own DID inside its bundle: a public value (a DID is a public key), never the seed. */
+exports.PUBLIC_A2A_IDENTITY_FILE = path.join("a2a", "public-identity.json");
+/**
+ * Publish this agent's own DID into its bundle so a one-off operator command (which has no vault access) can compare against it
+ * through the read-only bundle mount. Best effort: a read-only bundle just means the fallback stays unavailable.
+ */
+function publishOwnA2ADid(agentRoot, did) {
+    try {
+        const file = path.join(agentRoot, exports.PUBLIC_A2A_IDENTITY_FILE);
+        if (readPublishedA2ADid(agentRoot) === did)
+            return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify({ did }, null, 2)}\n`);
+    }
+    catch {
+        // The bundle may be mounted read-only; the DID then simply is not published.
+    }
+}
+/**
+ * The DID published in the bundle's public identity file, or null when it is absent or malformed. Read-only and ADVISORY: the agent can
+ * write its own bundle, so this value is never proof of which key is the agent's. Operator checks may report it, never rely on it alone.
+ */
+function readPublishedA2ADid(agentRoot) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(agentRoot, exports.PUBLIC_A2A_IDENTITY_FILE), "utf8"));
+        return typeof parsed.did === "string" && parsed.did.startsWith("did:key:") ? parsed.did : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * This agent's own A2A DID if its seed is already in this process's cached machine config, else null. Strictly read-only: it
+ * never mints a seed, never creates the machine identity file and never refreshes the vault, because an operator command only
+ * wants to compare, not to create or fetch anything. A one-off root command has no cached config, so it gets null and the caller
+ * falls back to the published DID (advisory only, see `readPublishedA2ADid`) and to comparing the DID against the friend records.
+ */
+async function readOwnA2ADid(agentName) {
+    try {
+        const cached = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agentName);
+        if (!cached.ok || !readStoredA2ASeed(cached.config))
+            return null;
+        /* v8 ignore next -- the seed is already stored here, so the load never reaches upsert; it exists only to make minting impossible @preserve */
+        const identity = await loadOrMintA2AIdentity({ agentName, sodium: await (0, a2a_client_1.ready)(), config: cached.config, upsert: async () => { throw new Error("readOwnA2ADid never mints"); } });
+        return identity.did;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A file-backed A2A identity for a client that is not an ouro agent (for example a
+ * coding harness talking to an agent over A2A). The file holds the Ed25519 seed, so
+ * it is treated like an SSH private key: created 0600 inside a 0700 directory, and
+ * REFUSED if group or other can read it.
+ */
+async function loadOrMintA2AIdentityFile(input) {
+    const sodium = input.sodium ?? await (0, a2a_client_1.ready)();
+    return fs.existsSync(input.filePath) ? readA2AIdentityFile(sodium, input.filePath) : mintA2AIdentityFile(sodium, input.filePath);
+}
+function readA2AIdentityFile(sodium, filePath) {
+    const mode = fs.statSync(filePath).mode & 0o077;
+    if (mode !== 0)
+        throw new Error(`A2A identity file ${filePath} is readable by group or other; chmod 600 it`);
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (typeof parsed.seed !== "string")
+        throw new Error(`A2A identity file ${filePath} has no seed`);
+    return deriveIdentity(sodium, decodeSeed(parsed.seed));
+}
+function mintA2AIdentityFile(sodium, filePath) {
+    const identity = deriveIdentity(sodium, mintSeed());
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(filePath, `${JSON.stringify({ version: 1, did: identity.did, seed: identity.seed }, null, 2)}\n`, { mode: 0o600 });
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_client_identity_minted",
+        message: "minted file-backed A2A client identity",
+        meta: { did: identity.did },
+    });
+    return identity;
+}