@ouro.bot/cli 0.1.0-alpha.833 → 0.1.0-alpha.835

package/changelog.json

@@ -1,6 +1,23 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.835",
+      "changes": [
+        "Sanctuary: in-place upgrade of an installed root authority (D-043). The authority keeps its epoch, token, issuer and Telegram cursor; only the reviewed package, its pins and the resident image change. The new package's lifecycle runs stop, switch, resident, migrate and start from a journal, backs up every root record it rewrites, and rolls back exactly on any failure. An interrupted upgrade rolls back on the next authority boot. No token rotation.",
+        "Upgrade orchestrator: new upgrade phase stages the package beside the live one, pauses host supervision behind a self-expiring maintenance flag, runs the lifecycle upgrade with automatic rollback, pins the DockerMan template, and resumes supervision. --rehearse <step> stops after a step and rolls back, proving the rollback on the real host. The host keeper now also restarts a resident left stopped.",
+        "Sanctuary root lifecycle failures are recorded with their real cause in a root-only log (the authority directory), and stderr names that file (D-034). A stale copy of the live token left in incoming-token is removed after an upgrade (D-044)."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.834",
+      "changes": [
+        "A2A: authenticated agent chat. A verified friend's message (friends message kind, signed and sealed) becomes the agent's turn under the sender's relationship profile, and the reply is sealed back to the sender and stored sealed, so neither direction travels or persists in plaintext over any transport.",
+        "Sanctuary: remote turns are relationship-scoped. Any Sanctuary turn from outside the host (Telegram, A2A, future senses) without a known capability profile gets no tools; only the Butler's own inner, CLI, and MCP channels keep the unscoped tool set. Adds a sanctuary-agent-peer profile: the owner's chat tools minus host execution and approval-gated restarts.",
+        "CLI: ouro a2a identity mints a file-backed client key (0600, refused if group- or other-readable); ouro a2a message sends a sealed chat to an agent card and prints the verified reply.",
+        "A2A: sealed chat is observable (sealed, opened, and refused events), and a reply sealed as any other friends kind is refused before it can reach a store."
+      ]
+    },
     {
       "version": "0.1.0-alpha.833",
       "changes": [

package/deploy/unraid/sanctuary-butler-upgrade.mjs

@@ -19,11 +19,17 @@
 //              automatic rollback on ANY failure so the Butler is never left
 //              down. Requires a freshly rotated token at incoming-token.
 //   verify     health + preservation (Jellyfin, steward policy) + readback.
+//   upgrade    in-place upgrade of an INSTALLED authority (D-043): same epoch,
+//              token and cursor; new package, pins and resident image. The new
+//              package's own lifecycle does the work and rolls back exactly on
+//              any failure. `--rehearse <step>` stops after that step and rolls
+//              back, proving the rollback on real hardware. No token rotation.
 //
-// Run `preflight` and `prepare` freely. `install` is the only destructive phase
-// and refuses without a rotated incoming-token.
+// Run `preflight` and `prepare` freely. `install` is the first-install phase and
+// refuses without a rotated incoming-token. Run `upgrade` detached so an SSH drop
+// cannot interrupt it:  setsid nohup node <this> upgrade <version> > /var/log/ouro-upgrade.log 2>&1 &
 //
-// Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify> <version>
+// Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>]
 
 import { execFileSync } from "node:child_process"
 import { createHash } from "node:crypto"
@@ -47,6 +53,13 @@ const REQUIRED_PROGRAMS = [
   "deploy/unraid/sanctuary-authority-service.sh",
 ]
 const MIN_FREE_GB = 2
+const INCOMING_MANIFEST = `${ROOT}/incoming-package-manifest.json`
+const INCOMING_REQUEST = `${ROOT}/incoming-request.json`
+const UPGRADE_JOURNAL = `${ROOT}/upgrade.json`
+// Host supervision skips its work while this flag is fresh (< 30 min), so a crashed
+// upgrade can never leave self-heal off for longer than that.
+const MAINTENANCE = "/run/ouro-authority-maintenance"
+const UPGRADE_STEPS = ["stop", "switch", "resident", "migrate", "start"]
 
 const sh = (file, args, opts = {}) => execFileSync(file, args, { encoding: "utf8", maxBuffer: 64 << 20, ...opts })
 const docker = (args, opts = {}) => sh("/usr/bin/docker", args, opts)
@@ -109,8 +122,11 @@ function preflight(version) {
   } catch { bad(`the ${CONTAINER} container is absent`) }
   if (id && runningImage && id === runningImage) bad("target and running image are identical — nothing to upgrade")
 
+  const installed = existsSync(`${ROOT}/active.json`)
+  if (installed) console.log("  note: an authority is installed, so this is an in-place upgrade (run `upgrade`, no token rotation)")
+
   say("no stale authority runtime state")
-  {
+  if (!installed) {
     const stale = ["/sys/fs/cgroup/ouro-authority", "/var/lib/ouro-authority", "/run/ouro-authority", `${ROOT}/epochs`].filter((d) => existsSync(d))
     if (stale.length && !existsSync(`${ROOT}/active.json`)) console.log(`  note: stale dirs present, install will clear them: ${stale.join(", ")}`)
     else if (!stale.length) ok("no stale authority runtime dirs")
@@ -119,7 +135,8 @@ function preflight(version) {
 
   say("no upgrade already in flight")
   existsSync(JOURNAL) ? bad(`a template transaction journal is pending at ${JOURNAL}; resolve it first`) : ok("no pending template transaction")
-  existsSync(`${ROOT}/active.json`) ? bad("an authority is already installed (active.json present)") : ok("no prior authority installed")
+  if (installed) existsSync(UPGRADE_JOURNAL) ? console.log("  note: an in-place upgrade is pending; `upgrade` resumes it") : ok("no pending in-place upgrade")
+  if (installed && existsSync(`${ROOT}/incoming-token`)) console.log("  note: a stale incoming-token copy is present; the upgrade removes it (D-044)")
 
   say("host primitives (root-owned, not group/world-writable)")
   for (const f of PRIMITIVES) {
@@ -140,7 +157,8 @@ function preflight(version) {
   } catch { bad("could not inspect the image contents") }
 
   say("D-018: the fenced vault read the install depends on")
-  if (id) {
+  if (installed) ok("not needed: the installed gateway already holds the token in root custody")
+  else if (id) {
     // Run the read fenced exactly as THIS version's install will fence it, so
     // the rehearsal is faithful: an unfixed image is tested without the fix and
     // correctly fails here rather than during a real install.
@@ -169,7 +187,7 @@ function preflight(version) {
   catch { bad("jellyfin container not inspectable") }
 
   console.log("")
-  if (RED === 0) console.log("PREFLIGHT GREEN — the upgrade can proceed. Next: prepare, rotate the token, install.")
+  if (RED === 0) console.log(installed ? "PREFLIGHT GREEN — run `upgrade` (detached)." : "PREFLIGHT GREEN — the upgrade can proceed. Next: prepare, rotate the token, install.")
   else console.log(`PREFLIGHT RED — ${RED} blocker(s) above. Nothing was changed; fix these before rotating the token.`)
   process.exit(RED === 0 ? 0 : 1)
 }
@@ -215,7 +233,41 @@ function prepare(version) {
   say(`prepare inputs for ${version}`)
   const id = imageId(version)
   if (!id) fail(`image ${image(version)} is not present; pull it first`)
+  if (existsSync(`${ROOT}/active.json`)) fail("an authority is installed; use `upgrade` (in place, no token rotation) instead of prepare/install")
   const epochId = `${version.replace(/[^A-Za-z0-9_-]/g, "-")}-${new Date().toISOString().slice(0, 10).replace(/-/g, "")}`
+  const manifestBytes = stageIncomingPackage(version)
+  writePrivate(`${ROOT}/package-manifest.json`, manifestBytes)
+  const creds = JSON.parse(readFileSync(`/mnt/user/appdata/ouro-butler/runtime/container-credentials.json`, "utf8")).credentials[0].runtimeConfig
+  const request = {
+    schemaVersion: 1, epochId,
+    botId: String(creds.telegramBotToken).split(":")[0],
+    ownerUserId: String(creds.telegramAuthorizedUserId), ownerChatId: String(creds.telegramAuthorizedChatId),
+    ...packagePins(manifestBytes),
+  }
+  if (request.ownerUserId !== request.ownerChatId) fail("owner user and chat must match")
+  writePrivate(`${ROOT}/request.json`, Buffer.from(JSON.stringify(request)))
+  ok(`epoch ${epochId}, package ${request.packageDigest.slice(7, 19)}…`)
+
+  say("verify the prepared package against the installer's own rules")
+  verifyPackage(`${ROOT}/incoming-package`, `${ROOT}/package-manifest.json`, `${ROOT}/request.json`)
+  ok("package verifies")
+
+  console.log("\nPREPARE done. Next: rotate the bot token into ${ROOT}/incoming-token, then install.".replace("${ROOT}", ROOT))
+}
+
+// The package digest plus the host primitive pins every request carries.
+function packagePins(manifestBytes) {
+  const d = (f) => digest(readFileSync(f))
+  return {
+    packageDigest: digest(manifestBytes),
+    nodeDigest: d("/usr/local/bin/node"), prlimitDigest: d("/usr/bin/prlimit"),
+    setsidDigest: d("/usr/bin/setsid"), shellDigest: d(sh("/bin/readlink", ["-f", "/bin/sh"]).trim()),
+  }
+}
+
+// Extract the exact package from the image into incoming-package, normalised to the
+// installer's rules, and return its manifest bytes. The running Butler is untouched.
+function stageIncomingPackage(version) {
   const incoming = `${ROOT}/incoming-package`
 
   say("extract the exact package from the image")
@@ -252,27 +304,8 @@ function prepare(version) {
     }
   }
   walk("")
-  const manifestBytes = Buffer.from(JSON.stringify({ schemaVersion: 1, files }))
-  writePrivate(`${ROOT}/package-manifest.json`, manifestBytes)
-  const creds = JSON.parse(readFileSync(`/mnt/user/appdata/ouro-butler/runtime/container-credentials.json`, "utf8")).credentials[0].runtimeConfig
-  const d = (f) => digest(readFileSync(f))
-  const request = {
-    schemaVersion: 1, epochId,
-    botId: String(creds.telegramBotToken).split(":")[0],
-    ownerUserId: String(creds.telegramAuthorizedUserId), ownerChatId: String(creds.telegramAuthorizedChatId),
-    packageDigest: digest(manifestBytes),
-    nodeDigest: d("/usr/local/bin/node"), prlimitDigest: d("/usr/bin/prlimit"),
-    setsidDigest: d("/usr/bin/setsid"), shellDigest: d(sh("/bin/readlink", ["-f", "/bin/sh"]).trim()),
-  }
-  if (request.ownerUserId !== request.ownerChatId) fail("owner user and chat must match")
-  writePrivate(`${ROOT}/request.json`, Buffer.from(JSON.stringify(request)))
-  ok(`epoch ${epochId}, ${Object.keys(files).length} files pinned, package ${request.packageDigest.slice(7, 19)}…`)
-
-  say("verify the prepared package against the installer's own rules")
-  verifyPackage(incoming, `${ROOT}/package-manifest.json`, `${ROOT}/request.json`)
-  ok("package verifies")
-
-  console.log("\nPREPARE done. Next: rotate the bot token into ${ROOT}/incoming-token, then install.".replace("${ROOT}", ROOT))
+  ok(`${Object.keys(files).length} files pinned`)
+  return Buffer.from(JSON.stringify({ schemaVersion: 1, files }))
 }
 
 function writePrivate(path, bytes) { writeFileSync(path, bytes, { mode: 0o600 }); sh("/bin/chown", ["0:0", path]); chmodSync(path, 0o600) }
@@ -440,18 +473,23 @@ start_gw() {
   /bin/sh /boot/config/custom/ouro-authority/start.sh --boot >> "$LOG" 2>&1 \
     || echo "$(date) keeper: authority boot failed; will retry" >> "$LOG"
 }
+# An in-place upgrade pauses us with a flag; a stale flag (> 30 min) is ignored.
+maintenance() { [ -n "$(find /run/ouro-authority-maintenance -mmin -30 2>/dev/null)" ]; }
 pause_reaper; ensure_cg; ensure_sock
 last_res=0
 while true; do
+  if maintenance; then sleep 15; continue; fi
   pause_reaper
   ensure_cg
   ensure_sock
   [ -n "$(gw_pid)" ] || { start_gw; sleep 8; }
   rd=$(jq -rc .status "$R"/epochs/*/readiness.json 2>/dev/null)
   st=$(docker inspect ouro-butler --format '{{.State.Health.Status}}' 2>/dev/null)
+  ss=$(docker inspect ouro-butler --format '{{.State.Status}}' 2>/dev/null)
   now=$(date +%s)
-  if [ "$rd" = ready ] && [ "$st" = unhealthy ] && [ $((now - last_res)) -gt 90 ]; then
-    echo "$(date) keeper: reconnecting unhealthy resident" >> "$LOG"
+  # Unhealthy, or left stopped (an interrupted upgrade or restart): the gateway is ready, so bring it back.
+  if [ "$rd" = ready ] && { [ "$st" = unhealthy ] || [ "$ss" = exited ] || [ "$ss" = created ]; } && [ $((now - last_res)) -gt 90 ]; then
+    echo "$(date) keeper: reconnecting resident ($ss/$st)" >> "$LOG"
     docker restart ouro-butler >/dev/null 2>&1
     last_res=$now
   fi
@@ -468,6 +506,8 @@ const GATEWAY_WATCHDOG_SH = String.raw`#!/bin/sh
 set -u
 # The stop hook sets this during shutdown; never resurrect the supervisor then.
 [ -e /run/ouro-authority-shutdown ] && exit 0
+# An in-place upgrade pauses supervision; a stale flag (> 30 min) is ignored.
+[ -n "$(find /run/ouro-authority-maintenance -mmin -30 2>/dev/null)" ] && exit 0
 SUP=/boot/config/custom/ouro-authority/gateway-supervisor.sh
 LOG=/var/log/ouro-gateway.log
 if [ ! -f "$SUP" ]; then
@@ -737,6 +777,83 @@ function buildFinalProof(version, out) {
   writeFileSync(out, JSON.stringify(proof), { mode: 0o600 })
 }
 
+// ---- upgrade (in place, installed authority) --------------------------------
+
+function pauseSupervision() {
+  writeFileSync(MAINTENANCE, `${new Date().toISOString()} ${process.pid}\n`)
+  sh("/bin/sh", ["-c", "for p in $(pgrep -f '^/bin/sh /boot/config/custom/ouro-authority/[g]ateway-supervisor' || true); do kill $p; done"])
+  ok("host supervision paused (its flag expires on its own after 30 min)")
+}
+function resumeSupervision() {
+  rmSync(MAINTENANCE, { force: true })
+  installGatewaySupervisor()
+}
+
+// Keep Unraid's DockerMan template (what the UI's Apply/Update uses) on the live image.
+function pinTemplate(version) {
+  if (!existsSync(TEMPLATE)) { console.log("  note: no DockerMan template to update"); return }
+  const text = readFileSync(TEMPLATE, "utf8")
+  const next = text.replace(/<Repository>ghcr\.io\/ourostack\/ouroboros-butler:[^<]+<\/Repository>/u, `<Repository>${image(version)}</Repository>`)
+  if (!next.includes(`<Repository>${image(version)}</Repository>`)) { console.log("  WARN: DockerMan template Repository not recognised; left unchanged"); return }
+  if (next !== text) { writeFileSync(`${TEMPLATE}.prev`, text); writeFileSync(TEMPLATE, next) }
+  ok(`DockerMan template pins ${image(version)}`)
+}
+
+function lifecycleFailure(e) {
+  const detail = [e.stderr, e.stdout].map((x) => (x ? String(x).trim() : "")).filter(Boolean).join(" | ")
+  let last = ""
+  try { last = readFileSync(`${ROOT}/lifecycle-failure.log`, "utf8").trim().split("\n").filter((l) => /^\d{4}-/.test(l)).at(-1) ?? "" } catch { /* none */ }
+  return `${detail || e.message}${last ? `\n   last root failure: ${last}` : ""}`
+}
+
+function upgrade(version, rehearse) {
+  say(`in-place upgrade to ${version}${rehearse ? ` — REHEARSAL: stop after "${rehearse}", then roll back` : ""}`)
+  if (rehearse && !UPGRADE_STEPS.includes(rehearse)) fail(`--rehearse takes one of: ${UPGRADE_STEPS.join(", ")}`)
+  if (!existsSync(`${ROOT}/active.json`) || !existsSync(`${ROOT}/activation.json`)) fail("no installed authority; use prepare + install")
+  if (existsSync(JOURNAL)) fail("a template transaction is pending; resolve it first")
+  let id = imageId(version)
+  if (!id) { docker(["pull", image(version)]); id = imageId(version) }
+  if (!id) fail(`image ${image(version)} could not be pulled`)
+  ok(`image ${id.slice(0, 19)}…`)
+  if (existsSync(UPGRADE_JOURNAL)) console.log("  note: resuming the pending in-place upgrade with its staged package")
+  else {
+    const current = JSON.parse(readFileSync(`${ROOT}/request.json`, "utf8"))
+    const manifestBytes = stageIncomingPackage(version)
+    const pkgVersion = JSON.parse(readFileSync(`${ROOT}/incoming-package/deploy/unraid/sanctuary.ouro/bundle-meta.json`, "utf8")).runtimeVersion
+    if (pkgVersion !== version) fail(`staged package is ${pkgVersion}, not ${version}`)
+    writePrivate(INCOMING_MANIFEST, manifestBytes)
+    const request = { schemaVersion: 1, epochId: current.epochId, botId: current.botId, ownerUserId: current.ownerUserId, ownerChatId: current.ownerChatId, ...packagePins(manifestBytes) }
+    writePrivate(INCOMING_REQUEST, Buffer.from(JSON.stringify(request)))
+    verifyPackage(`${ROOT}/incoming-package`, INCOMING_MANIFEST, INCOMING_REQUEST)
+    ok("new package staged beside the live one and verified")
+  }
+  const lifecycle = `${ROOT}/incoming-package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js`
+  const jellyfinBefore = docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim()
+  const policyBefore = existsSync(POLICY) ? sha12(POLICY) : fail("steward policy missing")
+  pauseSupervision()
+  let failure = null
+  try {
+    say("lifecycle upgrade (stop → switch → resident → migrate → start)")
+    ok(sh("/usr/local/bin/node", [lifecycle, "upgrade", id, image(version), ...(rehearse ? ["--fail-after", rehearse] : [])], { stdio: ["ignore", "pipe", "pipe"] }).trim())
+  } catch (e) { failure = e }
+  if (failure) {
+    console.log(`\n!! ${rehearse ? "rehearsal stopped as planned" : "upgrade failed"}: ${lifecycleFailure(failure)}\n!! rolling back to the predecessor`)
+    try { ok(`rollback: ${sh("/usr/local/bin/node", [lifecycle, "upgrade-rollback"], { stdio: ["ignore", "pipe", "pipe"] }).trim()}`) }
+    catch (e) {
+      resumeSupervision()
+      fail(`ROLLBACK FAILED: ${lifecycleFailure(e)}\nThe journal is kept; the next authority boot (or \`upgrade-rollback\`) retries it.`)
+    }
+  } else pinTemplate(version)
+  resumeSupervision()
+  say("preservation")
+  docker(["inspect", "jellyfin", "--format", "{{.Id}}|{{.Image}}|{{.RestartCount}}|{{.State.StartedAt}}"]).trim() === jellyfinBefore ? ok("jellyfin unchanged") : fail("JELLYFIN CHANGED")
+  sha12(POLICY) === policyBefore ? ok("steward policy unchanged") : fail("STEWARD POLICY CHANGED")
+  const live = docker(["inspect", CONTAINER, "--format", "{{.Config.Image}} {{.State.Status}}/{{.State.Health.Status}}"]).trim()
+  ok(`butler: ${live}`)
+  if (failure && !rehearse) fail("upgrade rolled back; the Butler is on its prior version (see above)")
+  console.log(rehearse ? "\nREHEARSAL done — the rollback restored the predecessor." : `\nUPGRADE done — ${version} live. Run verify.`)
+}
+
 // ---- verify ---------------------------------------------------------------
 
 function verify() {
@@ -755,9 +872,9 @@ function fail(m) { console.error(`\nREFUSING: ${m}`); process.exit(1) }
 
 // ---- entry ----------------------------------------------------------------
 
-const [phase, version] = process.argv.slice(2)
-if (!phase || !["preflight", "prepare", "install", "verify"].includes(phase)) {
-  console.error("Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify> <version>")
+const [phase, version, flag, rehearse] = process.argv.slice(2)
+if (!phase || !["preflight", "prepare", "install", "verify", "upgrade"].includes(phase) || (flag !== undefined && !(phase === "upgrade" && flag === "--rehearse" && rehearse))) {
+  console.error("Usage: sanctuary-butler-upgrade.mjs <preflight|prepare|install|verify|upgrade> <version> [--rehearse <step>]")
   process.exit(2)
 }
 if (phase !== "verify" && !/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(version || "")) {
@@ -770,3 +887,4 @@ if (phase === "preflight") preflight(version)
 else if (phase === "prepare") prepare(version)
 else if (phase === "install") install(version)
 else if (phase === "verify") verify()
+else if (phase === "upgrade") upgrade(version, rehearse)

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.833",
+  "runtimeVersion": "0.1.0-alpha.835",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

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

@@ -130,6 +130,75 @@
       "effectScopes": [
         "telegram.owner_event"
       ]
+    },
+    "sanctuary-agent-peer": {
+      "version": 1,
+      "toolNames": [
+        "external_event_disposition",
+        "query_active_work",
+        "save_friend_note",
+        "telegram_contact_manage",
+        "query_cares",
+        "care_manage",
+        "await_condition",
+        "resolve_await",
+        "cancel_await",
+        "list_recent_attachments",
+        "materialize_attachment",
+        "describe_image",
+        "unraid_list_containers",
+        "unraid_get_container_logs",
+        "unraid_get_storage",
+        "sanctuary_get_media_optimization",
+        "sanctuary_search_media_catalog",
+        "unraid_get_disks",
+        "unraid_get_notifications",
+        "unraid_get_system",
+        "sanctuary_get_install_state",
+        "unraid_check_services",
+        "sanctuary_get_download_queue",
+        "sanctuary_resume_download_queue",
+        "steward_policy_manage",
+        "send_message",
+        "ponder",
+        "rest",
+        "settle",
+        "speak",
+        "shell",
+        "shell_status",
+        "shell_tail",
+        "read_file",
+        "write_file",
+        "edit_file",
+        "glob",
+        "grep",
+        "web_search",
+        "search_facts",
+        "consult_diary",
+        "consult_notes",
+        "get_friend_note",
+        "session_summary",
+        "query_session",
+        "set_reasoning_effort",
+        "restart_runtime",
+        "revive_sense",
+        "media_search",
+        "media_request",
+        "media_request_status",
+        "media_diagnose_and_fix",
+        "media_chain_health",
+        "media_play_or_resolve"
+      ],
+      "contextScopes": [
+        "household.status",
+        "household.policy",
+        "household.private"
+      ],
+      "effectScopes": [
+        "telegram.proactive",
+        "telegram.request_return",
+        "telegram.owner_event"
+      ]
     }
   }
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.833</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.835</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/a2a/client.js

@@ -1,12 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.cardDid = cardDid;
 exports.endpointForCard = endpointForCard;
 exports.fetchA2AAgentCard = fetchA2AAgentCard;
 exports.sendA2AMessage = sendA2AMessage;
 exports.postA2AMessageEnvelope = postA2AMessageEnvelope;
 exports.getA2ATask = getA2ATask;
+exports.sendSealedA2AChat = sendSealedA2AChat;
 const node_crypto_1 = require("node:crypto");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
 const runtime_1 = require("../nerves/runtime");
+const sealed_chat_1 = require("./sealed-chat");
+/** The trimmed `did:key` a card serves, or undefined when the card is did-less. */
+function cardDid(card) {
+    const did = card.did;
+    return typeof did === "string" && did.trim() ? did.trim() : undefined;
+}
 function endpointForCard(card) {
     const jsonRpc = card.supportedInterfaces?.find((entry) => (entry.protocolBinding ?? entry.transport)?.toUpperCase() === "JSONRPC");
     if (jsonRpc?.url)
@@ -178,3 +187,50 @@ async function getA2ATask(input) {
     }
     return rpc.result;
 }
+/**
+ * Talk to an A2A agent as a verified friend: seal `text` to the agent's card DID,
+ * signed by `identity`, send it, and open the sealed reply. The card must serve a
+ * did:key bound to it (the same check onboarding applies), so the reply can only be
+ * accepted from that key. Neither direction ever travels in plaintext.
+ */
+async function sendSealedA2AChat(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const sodium = input.sodium ?? await (0, a2a_client_1.ready)();
+    const card = await fetchA2AAgentCard(input.cardUrl, fetchImpl);
+    const peerDid = cardDid(card);
+    if (!peerDid)
+        throw new Error(`A2A card ${input.cardUrl} serves no DID; sealed chat needs one`);
+    const parsed = (0, a2a_client_1.parseDidKey)(peerDid);
+    if (!parsed || !(0, a2a_client_1.verifyCardDidBinding)({ card: { did: peerDid, url: input.cardUrl }, did: peerDid, didDoc: null })) {
+        throw new Error(`A2A card↔DID binding failed for ${peerDid}`);
+    }
+    const endpointUrl = endpointForCard(card);
+    const conversationId = input.conversationId ?? (0, node_crypto_1.randomUUID)();
+    const sealed = (0, sealed_chat_1.sealChatMessage)({
+        sodium,
+        from: input.identity,
+        recipientDid: peerDid,
+        recipientEd25519Pub: parsed.ed25519Pub,
+        text: input.text,
+        conversationId,
+    });
+    const request = {
+        jsonrpc: "2.0",
+        id: (0, node_crypto_1.randomUUID)(),
+        method: "SendMessage",
+        params: { message: { kind: "message", role: "ROLE_USER", messageId: (0, node_crypto_1.randomUUID)(), contextId: conversationId, parts: sealed.parts } },
+    };
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_chat_send_start", message: "sending sealed A2A chat message", meta: { endpointUrl, peerDid } });
+    const rpc = await postJsonRpc(endpointUrl, request, fetchImpl);
+    if ("error" in rpc)
+        throw new Error(`A2A error ${rpc.error.code}: ${rpc.error.message}`);
+    const task = rpc.result;
+    const replyMessage = task?.status?.message;
+    if (!replyMessage)
+        throw new Error("A2A chat returned no reply message");
+    const opened = await (0, sealed_chat_1.openChatMessage)({ sodium, self: input.identity, message: replyMessage, senderDid: peerDid, senderEd25519Pub: parsed.ed25519Pub });
+    if (!opened.ok)
+        throw new Error(`A2A chat reply rejected: ${opened.reason}`);
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_chat_send_end", message: "received sealed A2A chat reply", meta: { endpointUrl, peerDid, taskId: task.id } });
+    return { text: opened.text, conversationId, taskId: task.id, peerDid, peerName: card.name };
+}

package/dist/a2a/identity.js

@@ -36,7 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readStoredA2ASeed = readStoredA2ASeed;
 exports.loadOrMintA2AIdentity = loadOrMintA2AIdentity;
 exports.loadSelfA2AIdentity = loadSelfA2AIdentity;
+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");
@@ -168,3 +171,34 @@ async function loadSelfA2AIdentity(input) {
         },
     });
 }
+/**
+ * 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;
+}

package/dist/a2a/inbound-share.js

@@ -95,6 +95,9 @@ async function receiveInboundShare(message, deps) {
             trust,
             friendsKind: result.friendsKind,
             status: result.status,
+            ...(result.message ? { message: result.message } : {}),
+            /* v8 ignore next -- a completed receipt implies a trusted friend record: an unknown DID reads as stranger and is refused @preserve */
+            ...(record ? { friend: record } : {}),
         };
     }
     (0, runtime_1.emitNervesEvent)({

package/dist/a2a/onboarding.js

@@ -52,11 +52,6 @@ function urlAgentId(cardUrl) {
     parsed.hash = "";
     return parsed.toString();
 }
-/** The trimmed `did:key` a card serves, or undefined when the card is did-less. */
-function cardDid(card) {
-    const did = card.did;
-    return typeof did === "string" && did.trim() ? did.trim() : undefined;
-}
 async function onboardA2APeer(options) {
     // HTTP/URL glue stays harness-side: fetch the agent card, resolve its JSON-RPC
     // endpoint, and derive the stable agentId. The record-shaping (mint/update the
@@ -77,7 +72,7 @@ async function onboardA2APeer(options) {
     // an inbound envelope, so onboarding it would silently break the resolve later). A
     // card whose DID is unparseable or fails the binding is REFUSED (no record
     // written) — never TOFU-trust a mis-bound or malformed card.
-    const did = cardDid(card);
+    const did = (0, client_1.cardDid)(card);
     if (did) {
         const parsed = (0, a2a_client_1.parseDidKey)(did);
         const bound = parsed !== null && (0, a2a_client_1.verifyCardDidBinding)({ card: { did, url: options.cardUrl }, did, didDoc: null });