@adapt-toolkit/a2adapt 0.11.4 → 0.11.5

package/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "a2adapt",
   "displayName": "a2adapt",
   "description": "Secure agent-to-agent communication channel over ADAPT: self-sovereign pubkey identity, end-to-end encryption, plan-first execution.",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "author": {
     "name": "Adapt Toolkit"
   },

package/dist/index.js

@@ -22429,7 +22429,7 @@ var StreamableHTTPServerTransport = class {
 // src/index.ts
 import { resolve as resolve2, join as join2, dirname as dirname2, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
-import { randomBytes, randomUUID } from "node:crypto";
+import { randomBytes, randomInt, randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import * as fs2 from "node:fs";
 import { brotliCompressSync, brotliDecompressSync, constants as zlibConstants } from "node:zlib";
@@ -22512,7 +22512,7 @@ function writeIdentityFile(target, opts, overwrite = false) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.11.4" : "0.0.0-dev";
+var VERSION = true ? "0.11.5" : "0.0.0-dev";
 var CONFIG = loadConfig();
 var STATE_DIR = CONFIG.stateDir;
 var BROKER_URL = CONFIG.brokerUrl;
@@ -22668,7 +22668,8 @@ function describeIdentity(id) {
     bio: v.Reduce("bio").Visualize(),
     roleId: v.Reduce("role_id").Visualize(),
     rootCid: v.Reduce("root_cid").Visualize(),
-    rootName: v.Reduce("root_name").Visualize()
+    rootName: v.Reduce("root_name").Visualize(),
+    monitoringEnabled: v.Reduce("monitoring_enabled").GetBoolean()
   };
 }
 async function delegateRole(root, role) {
@@ -22735,6 +22736,282 @@ async function sendViaLocalBook(id, contact, text) {
   });
   return `"${entry.name}" was not a contact yet \u2014 connected via the local contact book and sent the message with the introduction. If "${entry.name}" requires approval for local introductions, delivery completes once they approve.`;
 }
+function monitoringStatus(id) {
+  const v = readonlyTx(id, "::actor::get_monitoring_status");
+  return {
+    enabled: v.Reduce("monitoring_enabled").GetBoolean(),
+    proxyCid: v.Reduce("proxy_cid").Visualize(),
+    proxyPending: v.Reduce("proxy_pending").GetBoolean(),
+    copiesQueued: parseInt(v.Reduce("copies_queued").Visualize(), 10) || 0,
+    controlQueued: parseInt(v.Reduce("control_queued").Visualize(), 10) || 0
+  };
+}
+async function setAgentMonitoring(root, role, enabled) {
+  if (enabled) {
+    const rootAd = exportAdBlob(root);
+    await mutatingTx(role, "::actor::connect_sibling", {
+      name: root.name,
+      target_ad: role.pw.packet.NewBinaryFromBuffer(rootAd)
+    });
+  }
+  const roleAd = exportAdBlob(role);
+  const authData = await mutatingTx(root, "::actor::sign_monitoring_auth", {
+    role_ad: root.pw.packet.NewBinaryFromBuffer(roleAd),
+    enabled
+  });
+  const authBlob = Buffer.from(authData.Reduce("auth").GetBinary());
+  await mutatingTx(role, "::actor::set_monitoring", {
+    auth: role.pw.packet.NewBinaryFromBuffer(authBlob)
+  });
+  log(`[${role.name}] monitoring ${enabled ? "enabled" : "disabled"} (authorized by root "${root.name}")`);
+}
+async function sendControl(id, contactRef, payload) {
+  await mutatingTx(id, "::a2a_control::send_control", {
+    contact: contactRef,
+    payload: JSON.stringify(payload)
+  });
+}
+function renderCopies(v) {
+  const out = [];
+  if (v.IsNil()) return out;
+  for (let i = 0; ; i++) {
+    const m = v.Reduce(i);
+    if (m.IsNil()) break;
+    out.push({
+      source_cid: m.Reduce("source_cid").Visualize(),
+      source_name: m.Reduce("source_name").Visualize(),
+      direction: m.Reduce("direction").Visualize(),
+      peer_cid: m.Reduce("peer_cid").Visualize(),
+      peer_name: m.Reduce("peer_name").Visualize(),
+      date: m.Reduce("date").Visualize(),
+      body: m.Reduce("body").Visualize()
+    });
+  }
+  return out;
+}
+function renderControlRequests(v) {
+  const out = [];
+  if (v.IsNil()) return out;
+  for (let i = 0; ; i++) {
+    const m = v.Reduce(i);
+    if (m.IsNil()) break;
+    out.push({
+      senderCid: m.Reduce("sender_cid").Visualize(),
+      senderName: m.Reduce("sender_name").Visualize(),
+      payload: m.Reduce("payload").Visualize(),
+      date: m.Reduce("date").Visualize()
+    });
+  }
+  return out;
+}
+var forwardBusy = /* @__PURE__ */ new Set();
+async function forwardMonitoring(root) {
+  if (forwardBusy.has(root.name)) return;
+  forwardBusy.add(root.name);
+  try {
+    const st = monitoringStatus(root);
+    if (!st.proxyCid || st.copiesQueued === 0) return;
+    const data = await mutatingTx(root, "::actor::get_monitoring_copies", {});
+    const copies = renderCopies(data.Reduce("copies"));
+    if (copies.length === 0) return;
+    await sendControl(root, st.proxyCid, { v: 1, t: "monitoring", copies });
+  } catch (err) {
+    log(`[${root.name}] monitoring forward failed:`, String(err));
+  } finally {
+    forwardBusy.delete(root.name);
+  }
+}
+function listAgentsFor(root) {
+  const agents = [];
+  for (const id of identities.values()) {
+    if (id.name === root.name) continue;
+    const info = describeIdentity(id);
+    if (info.rootCid !== root.cid) continue;
+    agents.push({
+      name: id.name,
+      cid: id.cid,
+      role_id: info.roleId,
+      bio: info.bio,
+      monitoring: info.monitoringEnabled
+    });
+  }
+  return agents;
+}
+function findAgentOf(root, ref) {
+  const id = identities.get(ref) ?? [...identities.values()].find((i) => i.cid === ref);
+  if (!id || id.name === root.name) return null;
+  return describeIdentity(id).rootCid === root.cid ? id : null;
+}
+function deleteIdentityCompletely(id) {
+  try {
+    wrapper.remove_packet(id.cid);
+  } catch (err) {
+    log(`remove_packet(${id.cid}) failed:`, String(err));
+  }
+  identities.delete(id.name);
+  try {
+    unpublishFromBook(id.name);
+  } catch (err) {
+    log(`failed to unpublish "${id.name}" from the contact book:`, String(err));
+  }
+  const holder = bindingOwner.get(id.name);
+  if (holder) {
+    bindingOwner.delete(id.name);
+    sessionBinding.delete(holder);
+    persistBindings();
+  }
+  if (id.name === rootName) {
+    rootName = null;
+    clearRootMarker();
+  }
+  try {
+    fs2.rmSync(id.dir, { recursive: true, force: true });
+  } catch (err) {
+    return `deleting ${id.dir} failed: ${String(err)}`;
+  }
+  return null;
+}
+async function handleControlRequest(root, req) {
+  let msg;
+  try {
+    const parsed = JSON.parse(req.payload);
+    if (!parsed || typeof parsed !== "object") throw new Error("not an object");
+    msg = parsed;
+  } catch {
+    log(`[${root.name}] dropping unparseable control request from ${req.senderName}`);
+    return;
+  }
+  if (msg.v !== 1 || typeof msg.t !== "string") {
+    log(`[${root.name}] dropping control request with unknown envelope from ${req.senderName}`);
+    return;
+  }
+  const reply = async (data) => {
+    try {
+      await sendControl(root, req.senderCid, { v: 1, t: "res", id: msg.id ?? null, req: msg.t, ...data });
+    } catch (err) {
+      log(`[${root.name}] control reply to ${req.senderName} failed:`, String(err));
+    }
+  };
+  try {
+    if (msg.t === "bind") {
+      const data = await mutatingTx(root, "::actor::verify_proxy_code", {
+        code: String(msg.code ?? ""),
+        sender: req.senderCid
+      });
+      if (!data.Reduce("verified").GetBoolean()) {
+        const reason = data.Reduce("reason").Visualize();
+        log(`[${root.name}] proxy bind attempt from ${req.senderName} rejected (${reason})`);
+        await reply({ ok: false, error: reason });
+        return;
+      }
+      appendNotifyLog(root, { event: "monitoring_proxy_bound", from: req.senderName });
+      log(`[${root.name}] monitoring proxy bound: ${req.senderName} (${req.senderCid})`);
+      await reply({ ok: true, root: { name: root.name, cid: root.cid }, agents: listAgentsFor(root) });
+      await forwardMonitoring(root);
+      return;
+    }
+    const st = monitoringStatus(root);
+    if (!st.proxyCid || st.proxyCid !== req.senderCid) {
+      await reply({ ok: false, error: "not_authorized" });
+      return;
+    }
+    switch (msg.t) {
+      case "list_agents": {
+        await reply({ ok: true, root: { name: root.name, cid: root.cid }, agents: listAgentsFor(root) });
+        return;
+      }
+      case "create_agent": {
+        const name = String(msg.name ?? "").trim();
+        const bio = String(msg.bio ?? "");
+        const bad = validateName(name);
+        if (bad) {
+          await reply({ ok: false, error: bad });
+          return;
+        }
+        if (identities.has(name)) {
+          await reply({ ok: false, error: `an identity named "${name}" already exists` });
+          return;
+        }
+        const agent = await provisionIdentity(name);
+        if (bio) await mutatingTx(agent, "::a2a_messaging::set_my_bio", { bio });
+        await delegateRole(root, agent);
+        await reply({ ok: true, agents: listAgentsFor(root) });
+        return;
+      }
+      case "update_role": {
+        const agent = findAgentOf(root, String(msg.agent ?? ""));
+        if (!agent) {
+          await reply({ ok: false, error: "no such agent under this root" });
+          return;
+        }
+        await mutatingTx(agent, "::a2a_messaging::set_my_bio", { bio: String(msg.bio ?? "") });
+        await reply({ ok: true, agents: listAgentsFor(root) });
+        return;
+      }
+      case "set_monitoring": {
+        const agent = findAgentOf(root, String(msg.agent ?? ""));
+        if (!agent) {
+          await reply({ ok: false, error: "no such agent under this root" });
+          return;
+        }
+        await setAgentMonitoring(root, agent, Boolean(msg.enabled));
+        await reply({ ok: true, agents: listAgentsFor(root) });
+        return;
+      }
+      case "contact_agent": {
+        const agent = findAgentOf(root, String(msg.agent ?? ""));
+        if (!agent) {
+          await reply({ ok: false, error: "no such agent under this root" });
+          return;
+        }
+        const inv = await mutatingTx(agent, "::a2a_messaging::generate_invite", {});
+        const blob = packInvite(Buffer.from(inv.Reduce("invite").GetBinary()));
+        await reply({ ok: true, agent: agent.name, invite: blob });
+        return;
+      }
+      case "remove_agent": {
+        const agent = findAgentOf(root, String(msg.agent ?? ""));
+        if (!agent) {
+          await reply({ ok: false, error: "no such agent under this root" });
+          return;
+        }
+        const fail = deleteIdentityCompletely(agent);
+        if (fail) {
+          await reply({ ok: false, error: fail });
+          return;
+        }
+        await reply({ ok: true, agents: listAgentsFor(root) });
+        return;
+      }
+      default:
+        await reply({ ok: false, error: `unknown request type "${msg.t}"` });
+    }
+  } catch (err) {
+    await reply({ ok: false, error: String(err) });
+  }
+}
+var controlBusy = /* @__PURE__ */ new Set();
+async function processControlRequests(root) {
+  if (controlBusy.has(root.name)) return;
+  controlBusy.add(root.name);
+  try {
+    for (; ; ) {
+      const data = await mutatingTx(root, "::actor::get_control_requests", {});
+      const reqs = renderControlRequests(data.Reduce("requests"));
+      if (reqs.length === 0) return;
+      for (const req of reqs) {
+        await handleControlRequest(root, req);
+      }
+    }
+  } catch (err) {
+    log(`[${root.name}] control dispatch failed:`, String(err));
+  } finally {
+    controlBusy.delete(root.name);
+  }
+  if (identities.has(root.name) && monitoringStatus(root).controlQueued > 0) {
+    return processControlRequests(root);
+  }
+}
 async function ensureRegistrar() {
   fs2.mkdirSync(bookDir(), { recursive: true });
   let seed;
@@ -22897,6 +23174,12 @@ function wireHandlers(id) {
         process.nextTick(
           () => pushNotification(id.name, `[${id.name}] "${name}" queued a message awaiting introduction approval (${queued} queued).`)
         );
+      } else if (event === "control_request") {
+        const from = payload.Reduce("sender_name").Visualize();
+        log(`[${id.name}] control request queued by ${from}`);
+        process.nextTick(() => void processControlRequests(id));
+      } else if (event === "monitoring_copy") {
+        process.nextTick(() => void forwardMonitoring(id));
       }
       return;
     }
@@ -23034,6 +23317,16 @@ async function bootWrapper() {
     clearRootMarker();
   }
   if (rootName) log(`root identity: ${rootName}`);
+  const root = rootName ? identities.get(rootName) : void 0;
+  if (root) {
+    try {
+      const st = monitoringStatus(root);
+      if (st.controlQueued > 0) void processControlRequests(root);
+      else if (st.copiesQueued > 0) void forwardMonitoring(root);
+    } catch (err) {
+      log(`boot-time monitoring/control drain failed:`, String(err));
+    }
+  }
   persistBindings();
 }
 function resolveBound(sessionId) {
@@ -23391,31 +23684,9 @@ Bio: ${info.bio}` : "";
           );
         }
       }
-      try {
-        wrapper.remove_packet(id.cid);
-      } catch (err) {
-        log(`remove_packet(${id.cid}) failed:`, String(err));
-      }
-      identities.delete(name);
-      try {
-        unpublishFromBook(name);
-      } catch (err) {
-        log(`failed to unpublish "${name}" from the contact book:`, String(err));
-      }
-      const holder = bindingOwner.get(name);
-      if (holder) {
-        bindingOwner.delete(name);
-        sessionBinding.delete(holder);
-        persistBindings();
-      }
-      if (name === rootName) {
-        rootName = null;
-        clearRootMarker();
-      }
-      try {
-        fs2.rmSync(id.dir, { recursive: true, force: true });
-      } catch (err) {
-        return textResult(`Identity "${name}" removed from memory, but deleting ${id.dir} failed: ${String(err)}`, true);
+      const fail = deleteIdentityCompletely(id);
+      if (fail) {
+        return textResult(`Identity "${name}" removed from memory, but ${fail}`, true);
       }
       return textResult(`Removed identity "${name}" and its state.`);
     }
@@ -23731,6 +24002,97 @@ These are now marked processed (auto-GC'd later). To hand any back to another se
       }
     }
   );
+  const rootOr = () => {
+    const root = rootName ? identities.get(rootName) : void 0;
+    if (!root) {
+      return { err: textResult("No root identity exists on this host \u2014 create one with create_root_identity first.", true) };
+    }
+    return { root };
+  };
+  server.tool(
+    "enable_monitoring",
+    "Enable monitoring on one of this host's agents (a role under the root identity): from now on the agent reports a copy of every message it sends or receives to the root, which forwards them to the bound browser proxy (see bind_monitoring_proxy). Authorized by a root-signed blob the role verifies against its delegation chain. Forward-only: past messages are never reported.",
+    { agent: external_exports.string().min(1).describe("Agent (role) name or container id.") },
+    async ({ agent }) => {
+      const { root, err } = rootOr();
+      if (err) return err;
+      const role = findAgentOf(root, agent);
+      if (!role) return textResult(`enable_monitoring failed: "${agent}" is not a role under root "${root.name}".`, true);
+      try {
+        await setAgentMonitoring(root, role, true);
+        return textResult(`Monitoring enabled on "${role.name}" \u2014 its message traffic now reports to root "${root.name}".`);
+      } catch (e) {
+        return textResult(`enable_monitoring failed: ${String(e)}`, true);
+      }
+    }
+  );
+  server.tool(
+    "disable_monitoring",
+    "Disable monitoring on one of this host's agents (see enable_monitoring).",
+    { agent: external_exports.string().min(1).describe("Agent (role) name or container id.") },
+    async ({ agent }) => {
+      const { root, err } = rootOr();
+      if (err) return err;
+      const role = findAgentOf(root, agent);
+      if (!role) return textResult(`disable_monitoring failed: "${agent}" is not a role under root "${root.name}".`, true);
+      try {
+        await setAgentMonitoring(root, role, false);
+        return textResult(`Monitoring disabled on "${role.name}".`);
+      } catch (e) {
+        return textResult(`disable_monitoring failed: ${String(e)}`, true);
+      }
+    }
+  );
+  server.tool(
+    "bind_monitoring_proxy",
+    "Start binding a browser (messenger) account as this host's monitoring & control proxy. PREREQUISITE: the browser account must already be a contact of the ROOT identity (invite exchange). This generates a 6-digit code (5-minute expiry, 3 attempts) bound to that contact and shows it HERE \u2014 read it to the user, who enters it in the messenger's Control Panel. On a successful code verification the contact becomes the monitoring proxy: it receives the monitoring feed and may manage agents (create, edit bios, toggle monitoring, request invites) through the root.",
+    { contact: external_exports.string().min(1).describe("The root's contact (name or container id) to bind as the proxy.") },
+    async ({ contact }) => {
+      const { root, err } = rootOr();
+      if (err) return err;
+      try {
+        const code = String(randomInt(0, 1e6)).padStart(6, "0");
+        const data = await mutatingTx(root, "::actor::set_proxy_pending", { code, proxy: contact });
+        const cid = data.Reduce("proxy_cid").Visualize();
+        return textResult(
+          `Proxy binding started for contact "${contact}" (${cid}).
+
+Verification code: ${code}
+
+Tell the user to enter this code in the messenger's Control Panel within 5 minutes (3 attempts). Do NOT send the code over a2adapt \u2014 it must travel out-of-band (this terminal counts).`
+        );
+      } catch (e) {
+        return textResult(`bind_monitoring_proxy failed: ${String(e)}`, true);
+      }
+    }
+  );
+  server.tool(
+    "get_monitoring_status",
+    "Report the monitoring & control state of this host: the root's bound proxy (if any), a pending proxy verification, queued copies/requests, and which agents have monitoring enabled.",
+    {},
+    async () => {
+      const { root, err } = rootOr();
+      if (err) return err;
+      try {
+        const st = monitoringStatus(root);
+        const lines = [];
+        lines.push(`Root "${root.name}" (${root.cid}):`);
+        lines.push(st.proxyCid ? `\u2022 monitoring proxy bound: ${st.proxyCid}` : "\u2022 no monitoring proxy bound");
+        if (st.proxyPending) lines.push("\u2022 a proxy code verification is pending");
+        if (st.copiesQueued > 0) lines.push(`\u2022 ${st.copiesQueued} monitoring cop${st.copiesQueued === 1 ? "y" : "ies"} queued for forwarding`);
+        if (st.controlQueued > 0) lines.push(`\u2022 ${st.controlQueued} control request(s) queued`);
+        const agents = listAgentsFor(root);
+        lines.push("");
+        lines.push(
+          agents.length === 0 ? "No agents (roles) under this root." : `Agents (${agents.length}):
+${agents.map((a) => `\u2022 ${a.name} \u2014 monitoring ${a.monitoring ? "ON" : "off"}${a.bio ? ` \u2014 ${a.bio}` : ""}`).join("\n")}`
+        );
+        return textResult(lines.join("\n"));
+      } catch (e) {
+        return textResult(`get_monitoring_status failed: ${String(e)}`, true);
+      }
+    }
+  );
   return server;
 }
 function readBody(req) {

package/dist/mufl_code/actor.mu

@@ -62,9 +62,23 @@
 //   reject_introduction     — drop a pending local introduction
 //   list_pending_introductions — (readonly) pending introductions (names + queue sizes)
 //
+// Monitoring + control plane (host-fired unless noted; see
+// MONITORING-AND-SHARED-LIBRARY-DESIGN.md):
+//   get_monitoring_status   — (readonly) enabled flag / proxy binding / queue sizes
+//   sign_monitoring_auth    — root-only: sign an enable/disable auth for a role
+//   set_monitoring          — role: verify the root-signed auth, set the flag
+//   get_monitoring_copies   — root: drain queued copies for proxy forwarding
+//   get_control_requests    — root: drain queued proxy control requests
+//   set_proxy_pending       — root: store the host-generated 6-digit code
+//   verify_proxy_code       — root: check a bind attempt (atomic attempts/expiry)
+//   clear_monitoring_proxy  — root: drop the proxy binding
+//   ::a2a_control::send_control — send an opaque control payload to a contact
+//
 // External transactions (inbound, not exposed as tools):
 //   accept_contact          — inviter learns the joiner's identity + name (core shim)
 //   receive_message         — store a decrypted inbound message (core shim)
+//   receive_monitoring_copy — a monitored role of mine reports a message copy
+//   ::a2a_control::control_message — control payload from a contact (queued for the daemon)
 //   local_introduce         — same-host peer connects via the local contact book
 //   sibling_introduce       — intra-root peer connects, authorized by its delegation cert
 
@@ -82,6 +96,7 @@ application actor loads libraries
     current_transaction_info,
     a2a_protocol,
     a2a_messaging,
+    a2a_control,
     version
     uses transactions
 {
@@ -113,6 +128,35 @@ application actor loads libraries
         seen_nonce_cap is int = 1024.
         pending_queue_cap is int = 50.
 
+        // ---- monitoring shapes + limits (see MONITORING-AND-SHARED-LIBRARY-DESIGN.md) ----
+        // Root-signed authorization for flipping a role's monitoring flag. Like
+        // a delegation cert, verified against the role's pinned root keys, so
+        // only this hierarchy's root can change what its roles report.
+        metadef monitoring_auth_core_t: ($version -> int, $role_cid -> global_id, $enabled -> bool, $issued_at -> time).
+        metadef monitoring_auth_t: ($c -> monitoring_auth_core_t, $s -> crypto_signature).
+        // One monitored message, as the role reports it to its root.
+        metadef monitoring_copy_t: (
+            $version     -> int,
+            $source_cid  -> global_id,
+            $source_name -> str,
+            $direction   -> str,
+            $peer_cid    -> global_id,
+            $peer_name   -> str,
+            $date        -> time,
+            $body        -> str
+        ).
+        // Proxy binding (root only): a pending 6-digit-code verification and
+        // the verified binding that replaces it on success.
+        metadef proxy_pending_t: ($code -> str, $proxy_cid -> global_id, $created_at -> time, $attempts -> int).
+        metadef proxy_binding_t: ($proxy_cid -> global_id, $bound_at -> time).
+        // One queued control request from the bound browser proxy.
+        metadef control_req_t: ($sender_cid -> global_id, $sender_name -> str, $payload -> str, $date -> time).
+
+        proxy_code_max_age_seconds is int = 300.
+        proxy_max_attempts is int = 3.
+        monitoring_inbox_cap is int = 500.
+        control_inbox_cap is int = 200.
+
         // Wire the deserialization primitive into the libraries that need it.
         _read_or_abort = grab( _read_or_abort ).
         key_storage::init ($_read_or_abort -> _read_or_abort).
@@ -147,6 +191,23 @@ application actor loads libraries
         // each with a bounded queue of messages awaiting approval.
         pending_introductions is (global_id ->> pending_intro_t) = (,).
 
+        // ---- monitoring state -------------------------------------------------
+        // Whether THIS packet (a role) reports its message traffic to its root.
+        // Only flipped by a root-signed authorization (set_monitoring).
+        monitoring_enabled is bool = FALSE.
+        // Root only: copies received from monitored roles, awaiting the host's
+        // get_monitoring_copies pull (forwarded to the bound proxy). Capped;
+        // oldest copies are dropped first when no proxy drains the queue.
+        monitoring_inbox is monitoring_copy_t[] = [].
+        // Root only: the in-flight proxy binding (6-digit code verification)
+        // and the verified proxy that monitoring traffic is forwarded to.
+        proxy_pending is proxy_pending_t+ = NIL.
+        monitoring_proxy is proxy_binding_t+ = NIL.
+        // Root only: control requests from the bound proxy, awaiting the
+        // host's get_control_requests pull. Kept out of the message inbox so
+        // agent sessions never see them.
+        control_inbox is control_req_t[] = [].
+
         // Signal the host to persist the packet. Only emitted at the end of a
         // complete procedure — intermediate states (e.g. channel handshake) are
         // never saved, so a crash mid-handshake restores to the last stable point.
@@ -170,6 +231,39 @@ application actor loads libraries
             return mid.
         }
 
+        // Build the monitoring-copy action for one message IF this packet is a
+        // monitored role with a live encrypted channel to its root; [] otherwise.
+        // The is_container_registered guard makes a missing/lost root channel
+        // degrade to "no copy" instead of failing the user's message — the
+        // enable flow (host-side) establishes the channel via connect_sibling.
+        fn monitor_copy_actions (direction: str, peer_cid: global_id, text: str, msg_date: time) -> transaction::action::type[]
+        {
+            if monitoring_enabled == FALSE || a2a_messaging::delegation_cert == NIL { return []. }
+            root_cid = a2a_messaging::delegation_cert? $c $root_cid.
+            if key_storage::is_container_registered(root_cid) != TRUE { return []. }
+
+            peer_name is str = "".
+            p = a2a_messaging::contacts peer_cid.
+            if p != NIL { peer_name -> p? $name. }
+
+            copy is monitoring_copy_t = (
+                $version     -> 1,
+                $source_cid  -> _get_container_id(),
+                $source_name -> a2a_messaging::my_name,
+                $direction   -> direction,
+                $peer_cid    -> peer_cid,
+                $peer_name   -> peer_name,
+                $date        -> msg_date,
+                $body        -> text
+            ).
+            return [
+                encrypted_channel::send_encrypted_tx root_cid (
+                    $name -> "::actor::receive_monitoring_copy",
+                    $targ -> ($copy -> copy)
+                )
+            ].
+        }
+
         // Resolve a pending introduction by joiner name or stringified container
         // id; aborts when nothing matches.
         fn resolve_pending (ref: str) -> global_id
@@ -217,13 +311,44 @@ application actor loads libraries
 
                 sender_name = (arg $sender_name) safe str.
                 mid = deposit_message sender_id sender_name text msg_date.
+                actions is transaction::action::type[] = [].
+                sc monitor_copy_actions "in" sender_id text msg_date -- ( -> a)
+                {
+                    actions (_count actions|) -> a.
+                }
+                actions (_count actions|) -> _notify_agent ($event -> $message_received, $sender_name -> sender_name, $msg_id -> mid, $date -> msg_date).
+                actions (_count actions|) -> _save_state NIL.
+                return actions.
+            },
+            $on_message_sent -> fn (arg: any) -> transaction::action::type[]
+            {
+                return monitor_copy_actions "out" ((arg $target_id) safe global_id) ((arg $text) safe str) ((arg $date) safe time).
+            },
+            $on_contact_removed -> fn (_: any) -> transaction::action::type[] { return []. }
+        ).
+
+        // Wire the control plane (see MONITORING-AND-SHARED-LIBRARY-DESIGN.md
+        // Part 4): control requests from the bound browser proxy queue in
+        // control_inbox — NEVER the message inbox, so agent sessions don't see
+        // them — and the notify event wakes the daemon's dispatcher. The
+        // payload stays opaque here; sender authorization happens in the
+        // daemon against the packet's monitoring_proxy / proxy_pending state.
+        a2a_control::init (
+            $on_control_received -> fn (arg: any) -> transaction::action::type[]
+            {
+                abort "Control queue is full." when (_count control_inbox|) >= control_inbox_cap.
+                sender_name = (arg $sender_name) safe str.
+                control_inbox (_count control_inbox|) -> (
+                    $sender_cid  -> (arg $sender_id) safe global_id,
+                    $sender_name -> sender_name,
+                    $payload     -> (arg $payload) safe str,
+                    $date        -> (arg $date) safe time
+                ).
                 return [
-                    _notify_agent ($event -> $message_received, $sender_name -> sender_name, $msg_id -> mid, $date -> msg_date),
+                    _notify_agent ($event -> $control_request, $sender_name -> sender_name, $queued -> _count control_inbox|),
                     _save_state NIL
                 ].
-            },
-            $on_message_sent -> fn (_: any) -> transaction::action::type[] { return []. },
-            $on_contact_removed -> fn (_: any) -> transaction::action::type[] { return []. }
+            }
         ).
     }
 
@@ -633,7 +758,7 @@ application actor loads libraries
     {
         if a2a_messaging::delegation_cert == NIL
         {
-            return ($name -> a2a_messaging::my_name, $bio -> a2a_messaging::my_bio, $has_cert -> FALSE, $role_id -> "", $root_cid -> "", $root_name -> "").
+            return ($name -> a2a_messaging::my_name, $bio -> a2a_messaging::my_bio, $has_cert -> FALSE, $role_id -> "", $root_cid -> "", $root_name -> "", $monitoring_enabled -> monitoring_enabled).
         }
         cert = a2a_messaging::delegation_cert?.
         rname is str = "".
@@ -644,7 +769,8 @@ application actor loads libraries
             $has_cert  -> TRUE,
             $role_id   -> cert $c $role_id,
             $root_cid  -> (_str (cert $c $root_cid)),
-            $root_name -> rname
+            $root_name -> rname,
+            $monitoring_enabled -> monitoring_enabled
         ).
     }
 
@@ -692,6 +818,232 @@ application actor loads libraries
         }).
     }
 
+    // ---- monitoring + control plane -------------------------------------------
+    // (see MONITORING-AND-SHARED-LIBRARY-DESIGN.md). A monitored ROLE reports
+    // every message it sends/receives to its ROOT (the monitor_copy_actions
+    // branches in the storage hooks above); the root queues the copies and the
+    // host forwards them to a human proxy bound via 6-digit-code verification.
+    // The proxy's control requests (create agent, update role, …) queue in
+    // control_inbox and are executed by the host daemon.
+
+    trn readonly get_monitoring_status _
+    {
+        pending is bool = FALSE.
+        if proxy_pending != NIL { pending -> TRUE. }
+        proxy_out is str = "".
+        if monitoring_proxy != NIL { proxy_out -> _str (monitoring_proxy? $proxy_cid). }
+        return (
+            $monitoring_enabled -> monitoring_enabled,
+            $proxy_cid          -> proxy_out,
+            $proxy_pending      -> pending,
+            $copies_queued      -> _count monitoring_inbox|,
+            $control_queued     -> _count control_inbox|
+        ).
+    }
+
+    // Sign a monitoring authorization for a role (ROOT packet only — the role
+    // verifies the signature against its pinned root keys, so an auth minted
+    // by any other packet fails). Stateless, mirrors sign_delegation.
+    trn sign_monitoring_auth _:($role_ad -> role_ad_blob: bin, $enabled -> enabled: bool)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+        abort "Only a root identity can sign monitoring authorizations." when a2a_messaging::delegation_cert != NIL.
+
+        role_ad = (_read_or_abort role_ad_blob) safe address_document_types::t_address_document.
+        core is monitoring_auth_core_t = (
+            $version   -> 1,
+            $role_cid  -> role_ad $identity $container_id,
+            $enabled   -> enabled,
+            $issued_at -> (current_transaction_info::get_transaction_time())?
+        ).
+        auth is monitoring_auth_t = ($c -> core, $s -> key_storage::default_sign (_value_id core)).
+        return transaction::success [
+            _return_data ($auth -> (_write auth))
+        ].
+    }
+
+    // Store a verified monitoring flag (ROLE packet, host-fired after the root
+    // signed the auth). An auth that does not name me or was not signed by my
+    // root is rejected — so even a compromised host process cannot silently
+    // flip monitoring without the root packet's keys.
+    trn set_monitoring _:($auth -> auth_blob: bin)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+        abort "Only a delegated role can be monitored." when a2a_messaging::delegation_cert == NIL || a2a_messaging::root_ad == NIL.
+
+        auth = (_read_or_abort auth_blob) safe monitoring_auth_t.
+        abort "Unsupported monitoring authorization version." when (auth $c $version) != 1.
+        abort "This monitoring authorization was issued to a different identity." when (auth $c $role_cid) != _get_container_id().
+        abort "The monitoring authorization was not signed by my root." when key_storage::check_signature_new_container (_value_id (auth $c)) (auth $s) (a2a_messaging::root_ad? $identity $key_list) != TRUE.
+
+        monitoring_enabled -> auth $c $enabled.
+        return transaction::success [
+            _return_data ($monitoring_enabled -> monitoring_enabled),
+            _save_state NIL
+        ].
+    }
+
+    // A monitored role reports one message copy (ROOT packet, inbound). Only
+    // accepted from a verified role of THIS root (the contact_roots linkage
+    // recorded by sibling_introduce), and the copy must name its actual sender
+    // — a role cannot forge copies on another role's behalf.
+    trn receive_monitoring_copy _:($copy -> copy: monitoring_copy_t)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::external,).
+        encrypted_channel::check_encrypted_or_abort().
+
+        sender_id = current_transaction_info::get_external_envelope_or_abort() $from.
+        link = a2a_messaging::contact_roots sender_id.
+        abort "Monitoring copies are only accepted from my own roles." when link == NIL || (link? $root_cid) != _get_container_id().
+        abort "Monitoring copy does not name its sender as the source." when (copy $source_cid) != sender_id.
+        abort "Unsupported monitoring copy version." when (copy $version) != 1.
+
+        // Capped queue, oldest first out: if no proxy drains the root, recent
+        // traffic wins over old.
+        if (_count monitoring_inbox|) >= monitoring_inbox_cap
+        {
+            trimmed is monitoring_copy_t[] = [].
+            i is int = 0.
+            sc monitoring_inbox -- ( -> m)
+            {
+                if i > 0 { trimmed (_count trimmed|) -> m. }
+                i -> i + 1.
+            }
+            monitoring_inbox -> trimmed.
+        }
+        monitoring_inbox (_count monitoring_inbox|) -> copy.
+
+        return transaction::success [
+            _notify_agent ($event -> $monitoring_copy, $source_name -> copy $source_name, $queued -> _count monitoring_inbox|),
+            _save_state NIL
+        ].
+    }
+
+    // Drain the queued monitoring copies (ROOT packet, host-fired before
+    // forwarding to the bound proxy). Cleared on read, like get_messages.
+    trn get_monitoring_copies _
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        copies = monitoring_inbox.
+        monitoring_inbox -> [].
+        return transaction::success [
+            _return_data ($copies -> copies),
+            _save_state NIL
+        ].
+    }
+
+    // Drain the queued control requests (ROOT packet, host-fired by the
+    // control dispatcher). Cleared on read.
+    trn get_control_requests _
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        reqs = control_inbox.
+        control_inbox -> [].
+        return transaction::success [
+            _return_data ($requests -> reqs),
+            _save_state NIL
+        ].
+    }
+
+    // Start a proxy binding (ROOT packet, host-fired): remember the code the
+    // host generated (MUFL has no random source) for one specific contact.
+    // Restarting overwrites any previous pending binding.
+    trn set_proxy_pending _:($code -> code: str, $proxy -> proxy_ref: str)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+        abort "Only a root identity can bind a monitoring proxy." when a2a_messaging::delegation_cert != NIL.
+
+        pid = a2a_messaging::resolve_contact proxy_ref.
+        proxy_pending -> (
+            $code       -> code,
+            $proxy_cid  -> pid,
+            $created_at -> (current_transaction_info::get_transaction_time())?,
+            $attempts   -> 0
+        ).
+        return transaction::success [
+            _return_data ($pending -> TRUE, $proxy_cid -> (_str pid)),
+            _save_state NIL
+        ].
+    }
+
+    // Verify a proxy's code attempt (ROOT packet, host-fired when a `bind`
+    // control request arrives). Failures are returned as DATA — not aborts —
+    // so the attempt counter and expiry clearing persist atomically; an abort
+    // would roll them back and reopen the brute-force window.
+    trn verify_proxy_code _:($code -> code: str, $sender -> sender_ref: str)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        if proxy_pending == NIL
+        {
+            return transaction::success [ _return_data ($verified -> FALSE, $reason -> "no_pending") ].
+        }
+        p = proxy_pending?.
+        now = (current_transaction_info::get_transaction_time())?.
+
+        if (_substract_seconds now (p $created_at)) > proxy_code_max_age_seconds
+        {
+            proxy_pending -> NIL.
+            return transaction::success [
+                _return_data ($verified -> FALSE, $reason -> "expired"),
+                _save_state NIL
+            ].
+        }
+
+        sid = a2a_messaging::resolve_contact sender_ref.
+        if sid != (p $proxy_cid)
+        {
+            // Not the contact this binding was started for: reject without
+            // burning an attempt (the code was never compared).
+            return transaction::success [ _return_data ($verified -> FALSE, $reason -> "wrong_sender") ].
+        }
+
+        if code != (p $code)
+        {
+            attempts = (p $attempts) + 1.
+            if attempts >= proxy_max_attempts
+            {
+                proxy_pending -> NIL.
+                return transaction::success [
+                    _return_data ($verified -> FALSE, $reason -> "too_many_attempts"),
+                    _save_state NIL
+                ].
+            }
+            proxy_pending -> (
+                $code       -> p $code,
+                $proxy_cid  -> p $proxy_cid,
+                $created_at -> p $created_at,
+                $attempts   -> attempts
+            ).
+            return transaction::success [
+                _return_data ($verified -> FALSE, $reason -> "wrong_code", $attempts_left -> proxy_max_attempts - attempts),
+                _save_state NIL
+            ].
+        }
+
+        monitoring_proxy -> ($proxy_cid -> sid, $bound_at -> now).
+        proxy_pending -> NIL.
+        return transaction::success [
+            _return_data ($verified -> TRUE, $proxy_cid -> (_str sid)),
+            _save_state NIL
+        ].
+    }
+
+    // Drop the proxy binding (and any in-flight code verification).
+    trn clear_monitoring_proxy _
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        monitoring_proxy -> NIL.
+        proxy_pending -> NIL.
+        return transaction::success [
+            _return_data ($cleared -> TRUE),
+            _save_state NIL
+        ].
+    }
+
     // ---- upgrade: state export / import -------------------------------------
     // The host persists state by calling export_state (readonly) and serializing
     // the returned value to a code-independent blob. On a code upgrade it recreates
@@ -725,7 +1077,12 @@ application actor loads libraries
             $delegation_cert   -> core_state $delegation_cert,
             $root_ad           -> core_state $root_ad,
             $root_profile      -> core_state $root_profile,
-            $contact_roots     -> core_state $contact_roots
+            $contact_roots     -> core_state $contact_roots,
+            $monitoring_enabled -> monitoring_enabled,
+            $monitoring_inbox  -> monitoring_inbox,
+            $proxy_pending     -> proxy_pending,
+            $monitoring_proxy  -> monitoring_proxy,
+            $control_inbox     -> control_inbox
         ).
     }
 
@@ -808,6 +1165,29 @@ application actor loads libraries
             pending_introductions -> (data $pending_introductions) safe (global_id ->> pending_intro_t).
         }
 
+        // Monitoring + control state arrived after the local-book schema —
+        // optional in old blobs the same way.
+        if (data $monitoring_enabled) != NIL
+        {
+            monitoring_enabled -> (data $monitoring_enabled) safe bool.
+        }
+        if (data $monitoring_inbox) != NIL
+        {
+            monitoring_inbox -> (data $monitoring_inbox) safe (monitoring_copy_t[]).
+        }
+        if (data $proxy_pending) != NIL
+        {
+            proxy_pending -> (data $proxy_pending) safe proxy_pending_t.
+        }
+        if (data $monitoring_proxy) != NIL
+        {
+            monitoring_proxy -> (data $monitoring_proxy) safe proxy_binding_t.
+        }
+        if (data $control_inbox) != NIL
+        {
+            control_inbox -> (data $control_inbox) safe (control_req_t[]).
+        }
+
         // Pending introducers' keys too: their channel to me predates approval,
         // so it must survive an upgrade exactly like an approved contact's.
         sc pending_introductions -- ( -> p)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adapt-toolkit/a2adapt",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "description": "MCP server daemon for a2adapt — one native ADAPT wrapper hosting N self-sovereign identities, exposing secure agent-to-agent messaging tools over HTTP (Streamable HTTP). Run `a2adapt-mcp start`.",
   "type": "module",
   "license": "MIT",