@ouro.bot/cli 0.1.0-alpha.74 → 0.1.0-alpha.741

package/deploy/unraid/sanctuary.ouro/psyche/TACIT.md

@@ -0,0 +1,7 @@
+# Tacit
+
+- Read status, capacity, disk health, notifications, and bounded logs freely.
+- Restart only one exact existing container after a durable Telegram approval.
+- Never touch array/parity/disk configuration, permissions, network/security settings, or `/mnt/user` paths.
+- Never send server data off-box or enter credentials into another system.
+- When state is ambiguous, report what is known and stop.

package/deploy/unraid/sanctuary.ouro/tool-profiles.json

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "profiles": {
+    "sanctuary-telegram": [
+      "unraid_list_containers",
+      "unraid_get_container_logs",
+      "unraid_get_storage",
+      "unraid_get_disks",
+      "unraid_get_notifications",
+      "unraid_get_system",
+      "unraid_restart_container",
+      "ponder",
+      "settle",
+      "speak"
+    ],
+    "sanctuary-health-private": [
+      "send_message",
+      "rest"
+    ]
+  }
+}

package/deploy/unraid/sanctuary.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<Container version="2">
+  <Name>ouro-butler</Name>
+  <Repository>sha256:REPLACE_WITH_EXACT_LOCAL_IMAGE_ID</Repository>
+  <Registry/>
+  <Network>host</Network>
+  <Shell>sh</Shell>
+  <Privileged>false</Privileged>
+  <Support/>
+  <Project/>
+  <Overview>Mendelow Cloud Butler</Overview>
+  <Category>Tools:</Category>
+  <WebUI/>
+  <TemplateURL/>
+  <Icon/>
+  <ExtraParams>--restart=unless-stopped --user=10001:10001</ExtraParams>
+  <PostArgs/>
+  <CPUset/>
+  <DateInstalled>0</DateInstalled>
+  <DonateText/>
+  <DonateLink/>
+  <Requires/>
+  <Config Name="Runtime state" Target="/home/ouro/.ouro-cli" Default="/mnt/user/appdata/ouro-butler/runtime/.ouro-cli" Mode="rw" Description="Machine-scoped runtime" Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/ouro-butler/runtime/.ouro-cli</Config>
+  <Config Name="Agent bundle" Target="/home/ouro/AgentBundles/sanctuary.ouro" Default="/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro" Mode="rw" Description="Sanctuary bundle" Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro</Config>
+</Container>

package/dist/a2a/card.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildA2AAgentCard = buildA2AAgentCard;
+const runtime_1 = require("../nerves/runtime");
+const config_1 = require("./config");
+function buildA2AAgentCard(options) {
+    const endpoint = (0, config_1.a2aEndpointFromBaseUrl)(options.baseUrl, options.path ?? config_1.A2A_DEFAULT_PATH);
+    const card = {
+        name: options.agentName,
+        description: options.description ?? `Ouroboros agent ${options.agentName}`,
+        protocolVersion: config_1.A2A_DEFAULT_PROTOCOL_VERSION,
+        ...(options.did ? { did: options.did } : {}),
+        url: endpoint,
+        preferredTransport: "JSONRPC",
+        supportedInterfaces: [{
+                url: endpoint,
+                protocolBinding: "JSONRPC",
+                protocolVersion: config_1.A2A_DEFAULT_PROTOCOL_VERSION,
+            }],
+        additionalInterfaces: [{
+                url: endpoint,
+                transport: "JSONRPC",
+            }],
+        version: "1.0.0",
+        capabilities: {
+            streaming: false,
+            pushNotifications: false,
+            extendedAgentCard: false,
+        },
+        defaultInputModes: ["text/plain"],
+        defaultOutputModes: ["text/plain", "application/json"],
+        skills: [
+            {
+                id: "ouro-message",
+                name: "Message Ouro Agent",
+                description: "Send a message or task request through the Ouro A2A sense.",
+                tags: ["ouro", "agent", "work"],
+                examples: ["Ask this Ouro agent to continue or complete a delegated task."],
+                inputModes: ["text/plain"],
+                outputModes: ["text/plain", "application/json"],
+            },
+        ],
+        metadata: {
+            ouro: {
+                sense: "a2a",
+                agentName: options.agentName,
+            },
+        },
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_card_built",
+        message: "built A2A agent card",
+        meta: { agentName: options.agentName, endpoint, ...(options.did ? { did: options.did } : {}) },
+    });
+    return card;
+}

package/dist/a2a/client.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.endpointForCard = endpointForCard;
+exports.fetchA2AAgentCard = fetchA2AAgentCard;
+exports.sendA2AMessage = sendA2AMessage;
+exports.postA2AMessageEnvelope = postA2AMessageEnvelope;
+exports.getA2ATask = getA2ATask;
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+function endpointForCard(card) {
+    const jsonRpc = card.supportedInterfaces?.find((entry) => (entry.protocolBinding ?? entry.transport)?.toUpperCase() === "JSONRPC");
+    if (jsonRpc?.url)
+        return jsonRpc.url;
+    if (card.preferredTransport?.toUpperCase() === "JSONRPC" && card.url)
+        return card.url;
+    const legacyJsonRpc = card.additionalInterfaces?.find((entry) => entry.transport.toUpperCase() === "JSONRPC");
+    return legacyJsonRpc?.url ?? card.url;
+}
+async function fetchA2AAgentCard(cardUrl, fetchImpl = fetch) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_card_fetch_start",
+        message: "fetching A2A agent card",
+        meta: { cardUrl },
+    });
+    const response = await fetchImpl(cardUrl);
+    if (!response.ok) {
+        throw new Error(`A2A card fetch failed (${response.status} ${response.statusText})`);
+    }
+    const parsed = await response.json();
+    const endpoint = endpointForCard(parsed);
+    if (!parsed || typeof parsed !== "object" || typeof endpoint !== "string" || typeof parsed.name !== "string") {
+        throw new Error("A2A card is missing required name or JSONRPC endpoint fields");
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_card_fetch_end",
+        message: "fetched A2A agent card",
+        meta: { cardUrl, endpoint, name: parsed.name },
+    });
+    return parsed;
+}
+async function postJsonRpc(endpointUrl, request, fetchImpl, protocolVersion = "1.0") {
+    const response = await fetchImpl(endpointUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json", "A2A-Version": protocolVersion },
+        body: JSON.stringify(request),
+    });
+    if (!response.ok) {
+        throw new Error(`A2A JSON-RPC request failed (${response.status} ${response.statusText})`);
+    }
+    return await response.json();
+}
+function methodNotFound(response) {
+    return "error" in response && response.error.code === -32601;
+}
+function senderMetadata(input) {
+    return {
+        ...(input.senderAgentId ? { senderAgentId: input.senderAgentId } : {}),
+        ...(input.senderName ? { senderName: input.senderName } : {}),
+        ...(input.senderCardUrl ? { senderCardUrl: input.senderCardUrl } : {}),
+    };
+}
+async function sendA2AMessage(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const messageId = (0, node_crypto_1.randomUUID)();
+    const request = {
+        jsonrpc: "2.0",
+        id: (0, node_crypto_1.randomUUID)(),
+        method: "message/send",
+        params: {
+            message: {
+                kind: "message",
+                role: "user",
+                messageId,
+                ...(input.taskId ? { taskId: input.taskId } : {}),
+                contextId: input.sessionKey ?? "default",
+                parts: [{ kind: "text", text: input.message }],
+                metadata: senderMetadata(input),
+            },
+            ...(input.accessToken ? { accessToken: input.accessToken } : {}),
+        },
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_message_send_start",
+        message: "sending A2A message",
+        meta: { endpointUrl: input.endpointUrl, messageId },
+    });
+    let rpc = await postJsonRpc(input.endpointUrl, request, fetchImpl, "0.3");
+    if (methodNotFound(rpc)) {
+        rpc = await postJsonRpc(input.endpointUrl, {
+            ...request,
+            method: "SendMessage",
+            params: {
+                ...request.params,
+                message: {
+                    ...(request.params.message),
+                    role: "ROLE_USER",
+                },
+            },
+        }, fetchImpl);
+    }
+    if ("error" in rpc) {
+        throw new Error(`A2A error ${rpc.error.code}: ${rpc.error.message}`);
+    }
+    const result = rpc.result;
+    const task = "task" in result && result.task ? result.task : result;
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_message_send_end",
+        message: "sent A2A message",
+        meta: { endpointUrl: input.endpointUrl, messageId, taskId: task.id },
+    });
+    return task;
+}
+/**
+ * POST a pre-built friends A2A message (a `wrapInDataPart` sealed-envelope message)
+ * to a peer endpoint as a JSON-RPC `message/send`. This is the `direct`-rung wire
+ * the harness `A2ATransport` uses: friends' `sendShare` builds the sealed message and
+ * hands it to the transport, which delivers it here. Unlike `sendA2AMessage` (which
+ * builds a text part), this carries the caller's exact `message` (the sealed DataPart)
+ * untouched. Throws on a non-2xx response (transport failure).
+ */
+async function postA2AMessageEnvelope(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const request = {
+        jsonrpc: "2.0",
+        id: (0, node_crypto_1.randomUUID)(),
+        method: "message/send",
+        params: { message: input.message },
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_envelope_post_start",
+        message: "posting sealed A2A message envelope (direct rung)",
+        meta: { endpointUrl: input.endpointUrl },
+    });
+    let rpc = await postJsonRpc(input.endpointUrl, request, fetchImpl, "0.3");
+    if (methodNotFound(rpc)) {
+        rpc = await postJsonRpc(input.endpointUrl, { ...request, method: "SendMessage" }, fetchImpl);
+    }
+    if ("error" in rpc) {
+        throw new Error(`A2A error ${rpc.error.code}: ${rpc.error.message}`);
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_envelope_post_end",
+        message: "posted sealed A2A message envelope",
+        meta: { endpointUrl: input.endpointUrl },
+    });
+}
+async function getA2ATask(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const metadata = senderMetadata(input);
+    const request = {
+        jsonrpc: "2.0",
+        id: (0, node_crypto_1.randomUUID)(),
+        method: "tasks/get",
+        params: {
+            id: input.taskId,
+            ...(input.accessToken ? { accessToken: input.accessToken } : {}),
+            ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+        },
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_task_get",
+        message: "fetching A2A task",
+        meta: { endpointUrl: input.endpointUrl, taskId: input.taskId },
+    });
+    let rpc = await postJsonRpc(input.endpointUrl, request, fetchImpl, "0.3");
+    if (methodNotFound(rpc)) {
+        rpc = await postJsonRpc(input.endpointUrl, { ...request, method: "GetTask" }, fetchImpl);
+    }
+    if ("error" in rpc) {
+        throw new Error(`A2A error ${rpc.error.code}: ${rpc.error.message}`);
+    }
+    return rpc.result;
+}

package/dist/a2a/config.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A2A_DEFAULT_PATH = exports.A2A_DEFAULT_HOST = exports.A2A_DEFAULT_PROTOCOL_VERSION = void 0;
+exports.defaultA2APort = defaultA2APort;
+exports.normalizeA2APath = normalizeA2APath;
+exports.a2aEndpointFromBaseUrl = a2aEndpointFromBaseUrl;
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+exports.A2A_DEFAULT_PROTOCOL_VERSION = "1.0";
+exports.A2A_DEFAULT_HOST = "127.0.0.1";
+exports.A2A_DEFAULT_PATH = "/a2a";
+function defaultA2APort(agentName) {
+    const digest = (0, node_crypto_1.createHash)("sha256").update(agentName).digest();
+    const port = 18920 + (digest[0] % 60);
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_default_port",
+        message: "computed default A2A port",
+        meta: { agentName, port },
+    });
+    return port;
+}
+function normalizeA2APath(value) {
+    const trimmed = value?.trim();
+    const normalized = !trimmed
+        ? exports.A2A_DEFAULT_PATH
+        : trimmed.startsWith("/")
+            ? trimmed
+            : `/${trimmed}`;
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_path_normalized",
+        message: "normalized A2A path",
+        meta: { normalized },
+    });
+    return normalized;
+}
+function a2aEndpointFromBaseUrl(baseUrl, a2aPath = exports.A2A_DEFAULT_PATH) {
+    const url = new URL(baseUrl);
+    url.pathname = normalizeA2APath(a2aPath);
+    url.search = "";
+    url.hash = "";
+    (0, runtime_1.emitNervesEvent)({
+        component: "channels",
+        event: "channel.a2a_endpoint_built",
+        message: "built A2A endpoint URL",
+        meta: { endpoint: url.toString() },
+    });
+    return url.toString();
+}

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,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeDidResolution = makeDidResolution;
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Build the friends `DidResolution` for did:key peers. `resolveAndPin` is the
+ * verify-and-pin core the inbound bridge consumes:
+ *   parse the did:key → derive the presented Ed25519 key →
+ *     first contact (no pin under `fromAgentId`) → TOFU `pinOnFirstContact`
+ *     already pinned → `evaluateRotation` against the pin:
+ *       unchanged  → pin-hit, return the pinned key
+ *       accepted   → (re-pinned by evaluateRotation) return the NEW key
+ *       rejected   → loud security event, return null
+ *
+ * The pin is keyed by the STABLE `fromAgentId` (NOT the did:key string), so a
+ * rotation is "same `fromAgentId`, new (did, key)". An unparseable or empty DID is
+ * refused (null) and never matchable. The crypto is the friends primitives' — this
+ * only sequences them.
+ */
+function makeDidResolution(input) {
+    const { sodium, rotationProofFor } = input;
+    return {
+        async resolveAndPin(args) {
+            const { fromAgentId, did, pinStore, trustOfSource } = args;
+            // Empty DID is never a matchable key.
+            if (!did) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "channels",
+                    event: "channel.a2a_did_resolve_refused",
+                    message: "A2A DID resolve refused (empty DID)",
+                    meta: { fromAgentId, reason: "empty_did" },
+                });
+                return null;
+            }
+            const parsed = (0, a2a_client_1.parseDidKey)(did);
+            if (!parsed) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "channels",
+                    event: "channel.a2a_did_resolve_refused",
+                    message: "A2A DID resolve refused (unparseable did:key)",
+                    meta: { fromAgentId, reason: "parse_failed" },
+                });
+                return null;
+            }
+            const pinned = pinStore.get(fromAgentId);
+            if (!pinned) {
+                // 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 };
+            }
+            // Already pinned: evaluate the presented key against the pin.
+            const rotationProof = rotationProofFor?.(fromAgentId, did, parsed.ed25519Pub);
+            const decision = (0, a2a_client_1.evaluateRotation)({
+                sodium,
+                pinStore,
+                fromAgentId,
+                trustOfSource,
+                newDid: did,
+                newEd25519Pub: parsed.ed25519Pub,
+                rotationProof,
+            });
+            if (decision.decision === "unchanged") {
+                // Same key — pin-hit. (FileA2APinStore.get already emitted a2a_pin_hit.)
+                return { ed25519Pub: parsed.ed25519Pub };
+            }
+            if (decision.decision === "accepted") {
+                // evaluateRotation already re-pinned to the new key under fromAgentId.
+                (0, runtime_1.emitNervesEvent)({
+                    component: "channels",
+                    event: "channel.a2a_rotation_accepted",
+                    message: "A2A signed key rotation accepted",
+                    meta: { fromAgentId, newDid: did, trustOfSource },
+                });
+                return { ed25519Pub: parsed.ed25519Pub };
+            }
+            // Rejected — loud security signal (carries the reason).
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_rotation_rejected",
+                message: "A2A key rotation rejected",
+                meta: { fromAgentId, newDid: did, trustOfSource, reason: decision.reason },
+            });
+            return null;
+        },
+    };
+}

package/dist/a2a/identity.js

@@ -0,0 +1,170 @@
+"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.readStoredA2ASeed = readStoredA2ASeed;
+exports.loadOrMintA2AIdentity = loadOrMintA2AIdentity;
+exports.loadSelfA2AIdentity = loadSelfA2AIdentity;
+const crypto = __importStar(require("node:crypto"));
+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 } } });
+        },
+    });
+}