@adapt-toolkit/a2adapt 0.4.1 → 0.5.0

package/README.md

@@ -6,14 +6,15 @@ agent-to-agent messaging tools over stdio. Distributed as part of the
 
 The server **is** the node: on startup it boots a single ADAPT packet (a MUFL
 messenger), restores prior state from the state dir, connects to the broker, and
-exposes six tools — each a thin wrapper over one MUFL user transaction:
+exposes the messaging tools — each a thin wrapper over one MUFL user transaction:
 
 - `generate_invite` — named invite to share out-of-band
 - `add_contact` — add a contact from an invite blob (TOFU)
 - `list_contacts`
 - `send_message` — end-to-end encrypted
-- `process_incoming_message` — drain + decrypt inbound from the broker
-- `list_incoming_messages`
+- `get_messages` — return unread messages (bodies) + mark read; delivered exactly once
+- `mark_processed` / `defer_messages` — remove handled messages, or re-queue read ones for another session
+- `list_incoming_messages` — full inbox with ids + status (read-only)
 
 ## Configuration
 

package/dist/cli.js

@@ -161,7 +161,7 @@ function cmdWatch(which) {
     }
     for (const name of names) {
       if (which && name !== which) continue;
-      const logPath = join(STATE_DIR, name, "inbox.log");
+      const logPath = join(STATE_DIR, name, "notifications.log");
       let size;
       try {
         size = fs.statSync(logPath).size;
@@ -198,7 +198,7 @@ function cmdWatch(which) {
           continue;
         }
         out(
-          `[${name}] new message from ${msg.sender ?? "?"}: ${msg.text ?? ""}` + (msg.date ? `  (${msg.date})` : "")
+          `[${name}] new message from ${msg.from ?? "?"}` + (msg.msg_id !== void 0 ? ` (#${msg.msg_id})` : "") + (msg.date ? `  (${msg.date})` : "")
         );
       }
     }

package/dist/hooks/runner.js

@@ -21,34 +21,26 @@ function emit(payload) {
 function noop() {
   emit({ continue: true });
 }
-function readCursor(dir) {
+function readUnreadSnapshot(dir) {
+  let raw;
   try {
-    return parseInt(fs.readFileSync(join(dir, "inbox_cursor"), "utf8").trim(), 10) || 0;
+    raw = fs.readFileSync(join(dir, "unread.json"), "utf8");
   } catch {
-    return 0;
+    return null;
   }
-}
-function readInboxLog(dir) {
-  let raw;
   try {
-    raw = fs.readFileSync(join(dir, "inbox.log"), "utf8");
+    const snap = JSON.parse(raw);
+    const count = Number(snap.count ?? 0);
+    if (!count) return null;
+    const recent = Array.isArray(snap.recent) ? snap.recent.map((m) => ({
+      from: String(m.from ?? "?"),
+      msg_id: m.msg_id ?? "?",
+      date: String(m.date ?? "")
+    })) : [];
+    return { name: "", count, recent };
   } catch {
-    return [];
-  }
-  const msgs = [];
-  for (const line of raw.split("\n")) {
-    if (!line.trim()) continue;
-    try {
-      const m = JSON.parse(line);
-      msgs.push({
-        sender: String(m.sender ?? "?"),
-        text: String(m.text ?? ""),
-        date: String(m.date ?? "")
-      });
-    } catch {
-    }
+    return null;
   }
-  return msgs;
 }
 function collectUnread() {
   let names;
@@ -59,12 +51,9 @@ function collectUnread() {
   }
   const out = [];
   for (const name of names) {
-    const dir = join(STATE_DIR, name);
-    const all = readInboxLog(dir);
-    if (all.length === 0) continue;
-    const unread = all.slice(readCursor(dir));
-    if (unread.length === 0) continue;
-    out.push({ name, count: unread.length, messages: unread });
+    const snap = readUnreadSnapshot(join(STATE_DIR, name));
+    if (!snap) continue;
+    out.push({ ...snap, name });
   }
   return out;
 }
@@ -73,15 +62,15 @@ function renderContext(unread) {
   const lines = [];
   for (const u of unread) {
     lines.push(`\u2022 ${u.name} \u2014 ${u.count} unread:`);
-    for (const m of u.messages.slice(-5)) {
-      lines.push(`    [${m.sender}] ${m.text}${m.date ? `  (${m.date})` : ""}`);
+    for (const m of u.recent.slice(-5)) {
+      lines.push(`    from ${m.from} (#${m.msg_id})${m.date ? `  (${m.date})` : ""}`);
     }
-    if (u.count > 5) lines.push(`    \u2026and ${u.count - 5} earlier`);
+    if (u.count > u.recent.length) lines.push(`    \u2026and ${u.count - u.recent.length} earlier`);
   }
-  return `a2adapt \u2014 ${total} unread message(s) across ${unread.length} identit${unread.length === 1 ? "y" : "ies"} (arrived while you were away):
+  return `a2adapt \u2014 ${total} unread message(s) across ${unread.length} identit${unread.length === 1 ? "y" : "ies"} (arrived while you were away; senders shown, bodies stay in the packet):
 ${lines.join("\n")}
 
-To read & clear: choose_identity({ name }) then process_incoming_message(). To wait for live replies, arm a Monitor on the wake source \`a2adapt-mcp watch\` (each new-mail line wakes you).`;
+To read: choose_identity({ name }) then get_messages() (returns the bodies and marks them read). To wait for live replies, arm a Monitor on the per-identity wake source \`a2adapt-mcp watch <name>\` (each new-mail line wakes you).`;
 }
 function sessionStart() {
   const raw = readStdin();

package/dist/index.js

@@ -22433,10 +22433,11 @@ import { fileURLToPath } from "node:url";
 import { randomBytes, randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import * as fs from "node:fs";
+import { brotliCompressSync, brotliDecompressSync, constants as zlibConstants } from "node:zlib";
 import { adapt_wrapper } from "@adapt-toolkit/sdk/executables";
 import { PacketWrapperConfigurator } from "@adapt-toolkit/sdk/wrappers";
 import { object_to_adapt_value } from "@adapt-toolkit/sdk/wrapper";
-var VERSION = true ? "0.4.1" : "0.0.0-dev";
+var VERSION = true ? "0.5.0" : "0.0.0-dev";
 var STATE_DIR = resolve(
   process.env.A2ADAPT_STATE_DIR ?? resolve(homedir(), ".a2adapt")
 );
@@ -22481,8 +22482,8 @@ var evictedSessions = /* @__PURE__ */ new Set();
 var identityDir = (name) => join(STATE_DIR, name);
 var seedPath = (dir) => join(dir, "identity.seed");
 var dataPath = (dir) => join(dir, "state_data.bin");
-var cursorPath = (dir) => join(dir, "inbox_cursor");
-var inboxLogPath = (dir) => join(dir, "inbox.log");
+var notifyLogPath = (dir) => join(dir, "notifications.log");
+var unreadPath = (dir) => join(dir, "unread.json");
 function listPersistedNames() {
   if (!fs.existsSync(STATE_DIR)) return [];
   return fs.readdirSync(STATE_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && fs.existsSync(seedPath(join(STATE_DIR, d.name)))).map((d) => d.name);
@@ -22508,43 +22509,47 @@ function saveState(id) {
     log(`[${id.name}] failed to save state:`, String(err));
   }
 }
-function readCursor(dir) {
+function appendNotifyLog(id, from, msgId, date3) {
   try {
-    return parseInt(fs.readFileSync(cursorPath(dir), "utf8").trim(), 10) || 0;
-  } catch {
-    return 0;
-  }
-}
-function writeCursor(dir, n) {
-  try {
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(cursorPath(dir), String(n));
-  } catch {
+    fs.mkdirSync(id.dir, { recursive: true });
+    const line = JSON.stringify({ event: "message_received", from, msg_id: msgId, date: date3 }) + "\n";
+    fs.appendFileSync(notifyLogPath(id.dir), line);
+  } catch (err) {
+    log(`[${id.name}] failed to append notifications.log:`, String(err));
   }
 }
-function appendInboxLog(id, sender, text, date3) {
+function refreshUnread(id) {
   try {
+    const inbox = renderInbox(readonlyTx(id, "::actor::list_incoming_messages"));
+    const unread = inbox.filter((m) => m.status === "unread");
+    const snapshot = {
+      count: unread.length,
+      recent: unread.slice(-10).map((m) => ({ from: m.sender_name, msg_id: m.msg_id, date: m.date }))
+    };
     fs.mkdirSync(id.dir, { recursive: true });
-    const line = JSON.stringify({ sender, text, date: date3 }) + "\n";
-    fs.appendFileSync(inboxLogPath(id.dir), line);
+    const tmp = `${unreadPath(id.dir)}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(snapshot));
+    fs.renameSync(tmp, unreadPath(id.dir));
   } catch (err) {
-    log(`[${id.name}] failed to append inbox.log:`, String(err));
+    log(`[${id.name}] failed to refresh unread snapshot:`, String(err));
   }
 }
-var activeMcpServers = /* @__PURE__ */ new Set();
+var serversBySession = /* @__PURE__ */ new Map();
 var inboxResourceUri = (name) => `a2adapt://inbox/${encodeURIComponent(name)}`;
 function pushNotification(identityName, summary) {
   log(`[${identityName}] notify:`, summary);
-  for (const server of activeMcpServers) {
-    try {
-      server.sendLoggingMessage({ level: "info", logger: "a2adapt", data: summary });
-    } catch (e) {
-      log("sendLoggingMessage failed:", String(e));
-    }
-    try {
-      server.server.sendResourceUpdated({ uri: inboxResourceUri(identityName) });
-    } catch {
-    }
+  const sid = bindingOwner.get(identityName);
+  if (!sid) return;
+  const server = serversBySession.get(sid);
+  if (!server) return;
+  try {
+    server.sendLoggingMessage({ level: "info", logger: "a2adapt", data: summary });
+  } catch (e) {
+    log("sendLoggingMessage failed:", String(e));
+  }
+  try {
+    server.server.sendResourceUpdated({ uri: inboxResourceUri(identityName) });
+  } catch {
   }
 }
 function readonlyTx(id, name) {
@@ -22590,11 +22595,12 @@ function wireHandlers(id) {
       const event = payload.Reduce("event").Visualize();
       if (event === "message_received") {
         const sender = payload.Reduce("sender_name").Visualize();
-        const text = payload.Reduce("text").Visualize();
+        const msgId = payload.Reduce("msg_id").Visualize();
         const date3 = payload.Reduce("date").Visualize();
-        appendInboxLog(id, sender, text, date3);
+        appendNotifyLog(id, sender, msgId, date3);
+        refreshUnread(id);
         process.nextTick(
-          () => pushNotification(id.name, `[${id.name}] new message from ${sender}: ${text}  (${date3})`)
+          () => pushNotification(id.name, `[${id.name}] new message from ${sender} (#${msgId})`)
         );
       } else if (event === "contact_accepted") {
         const name = payload.Reduce("name").Visualize();
@@ -22680,6 +22686,7 @@ async function restoreIdentity(name) {
       log(`[${name}] failed to import saved state (continuing fresh):`, String(err));
     }
   }
+  refreshUnread(id);
   return id;
 }
 async function bootWrapper() {
@@ -22758,10 +22765,12 @@ function renderInbox(v) {
     const m = v.Reduce(i);
     if (m.IsNil()) break;
     out.push({
+      msg_id: parseInt(m.Reduce("msg_id").Visualize(), 10),
       sender_id: m.Reduce("sender_id").Visualize(),
       sender_name: m.Reduce("sender_name").Visualize(),
       text: m.Reduce("text").Visualize(),
-      date: m.Reduce("date").Visualize()
+      date: m.Reduce("date").Visualize(),
+      status: m.Reduce("status").Visualize()
     });
   }
   return out;
@@ -22769,12 +22778,32 @@ function renderInbox(v) {
 function textResult(text, isError = false) {
   return { content: [{ type: "text", text }], isError };
 }
+var INVITE_BROTLI_V1 = 1;
+function packInvite(raw) {
+  const compressed = brotliCompressSync(raw, {
+    params: {
+      [zlibConstants.BROTLI_PARAM_QUALITY]: 11,
+      [zlibConstants.BROTLI_PARAM_SIZE_HINT]: raw.length
+    }
+  });
+  return Buffer.concat([Buffer.from([INVITE_BROTLI_V1]), compressed]).toString("base64");
+}
+function unpackInvite(b64) {
+  const outer = Buffer.from(b64.trim(), "base64");
+  if (outer.length < 2) throw new Error("the invite blob is too short or not valid base64");
+  const version2 = outer[0];
+  if (version2 === INVITE_BROTLI_V1) return Buffer.from(brotliDecompressSync(outer.subarray(1)));
+  throw new Error(`unsupported invite format (version ${version2}) \u2014 the sender may be on a different a2adapt version`);
+}
+function fmtMsg(m, withStatus = true) {
+  const status = withStatus && m.status && m.status !== "unread" ? ` [${m.status}]` : "";
+  return `#${m.msg_id} [${m.sender_name}]${status} ${m.text}  (${m.date})`;
+}
 function createMcpServer(getSessionId) {
   const server = new McpServer(
     { name: "a2adapt", version: VERSION },
     { capabilities: { logging: {}, resources: {} } }
   );
-  activeMcpServers.add(server);
   const boundOr = () => {
     const b = resolveBound(getSessionId());
     return "error" in b ? { err: textResult(b.error, true) } : { id: b.id };
@@ -22885,7 +22914,7 @@ ${lines.join("\n")}`);
       if (err || !id) return { contents: [{ uri, mimeType: "text/plain", text: "No identity bound to this session." }] };
       const inbox = renderInbox(readonlyTx(id, "::actor::list_incoming_messages"));
       const text = inbox.length === 0 ? "Inbox is empty." : `Inbox (${inbox.length}):
-${inbox.map((m, i) => `${i + 1}. [${m.sender_name}] ${m.text}  (${m.date})`).join("\n")}`;
+${inbox.map((m) => fmtMsg(m)).join("\n")}`;
       return { contents: [{ uri, mimeType: "text/plain", text }] };
     }
   );
@@ -22898,7 +22927,7 @@ ${inbox.map((m, i) => `${i + 1}. [${m.sender_name}] ${m.text}  (${m.date})`).joi
       if (err) return err;
       try {
         const data = await mutatingTx(id, "::actor::generate_invite", { name });
-        const blob = Buffer.from(data.Reduce("invite").GetBinary()).toString("base64");
+        const blob = packInvite(Buffer.from(data.Reduce("invite").GetBinary()));
         return textResult(
           `Invite for "${name}" created. Share this blob out-of-band (they paste it into add_contact):
 
@@ -22921,10 +22950,10 @@ ${blob}`
       if (err) return err;
       let buf;
       try {
-        buf = Buffer.from(invite.trim(), "base64");
-        if (buf.length === 0) throw new Error("empty");
-      } catch {
-        return textResult("add_contact failed: the invite blob is not valid base64.", true);
+        buf = unpackInvite(invite);
+        if (buf.length === 0) throw new Error("the invite blob is empty");
+      } catch (e) {
+        return textResult(`add_contact failed: ${e instanceof Error ? e.message : "the invite blob is not valid."}`, true);
       }
       try {
         const blobValue = id.pw.packet.NewBinaryFromBuffer(buf);
@@ -22976,7 +23005,7 @@ ${contacts.map((c) => `\u2022 ${c.name} \u2014 ${c.container_id}`).join("\n")}`)
   );
   server.tool(
     "list_incoming_messages",
-    "List all received messages in the bound identity's inbox (decrypted, with sender).",
+    "List ALL messages in the bound identity's inbox (decrypted), each with its id and status (unread/read). A read-only history view \u2014 it does not change any status. To consume new mail use get_messages instead.",
     {},
     async () => {
       const { id, err } = boundOr();
@@ -22984,30 +23013,70 @@ ${contacts.map((c) => `\u2022 ${c.name} \u2014 ${c.container_id}`).join("\n")}`)
       try {
         const inbox = renderInbox(readonlyTx(id, "::actor::list_incoming_messages"));
         if (inbox.length === 0) return textResult("Inbox is empty.");
-        return textResult(`Inbox (${inbox.length}):
-${inbox.map((m, i) => `${i + 1}. [${m.sender_name}] ${m.text}  (${m.date})`).join("\n")}`);
+        const unread = inbox.filter((m) => m.status === "unread").length;
+        return textResult(
+          `Inbox (${inbox.length}, ${unread} unread):
+${inbox.map((m) => fmtMsg(m)).join("\n")}`
+        );
       } catch (e) {
         return textResult(`list_incoming_messages failed: ${String(e)}`, true);
       }
     }
   );
   server.tool(
-    "process_incoming_message",
-    "Surface messages that have arrived for the bound identity since the last check, and mark them processed (non-blocking \u2014 use to poll for new mail).",
+    "get_messages",
+    'Fetch the messages the bound identity has not seen yet (status "unread") and mark them "read". This is the ONLY call that returns message bodies. A message is delivered here exactly once, so reading and acting on it immediately will not double-process. Note each message id: pass them to mark_processed when done, or to defer_messages to leave a message for another session.',
     {},
     async () => {
       const { id, err } = boundOr();
       if (err) return err;
       try {
-        const inbox = renderInbox(readonlyTx(id, "::actor::list_incoming_messages"));
-        const cursor = readCursor(id.dir);
-        const fresh = inbox.slice(cursor);
-        writeCursor(id.dir, inbox.length);
+        const data = await mutatingTx(id, "::actor::get_messages", {});
+        const fresh = renderInbox(data.Reduce("messages"));
+        refreshUnread(id);
         if (fresh.length === 0) return textResult("No new messages.");
-        return textResult(`${fresh.length} new message(s):
-${fresh.map((m) => `\u2022 [${m.sender_name}] ${m.text}  (${m.date})`).join("\n")}`);
+        return textResult(
+          `${fresh.length} new message(s):
+${fresh.map((m) => fmtMsg(m, false)).join("\n")}
+
+When handled: mark_processed({ msg_ids: [${fresh.map((m) => m.msg_id).join(", ")}] }). To leave any for another session: defer_messages({ msg_ids: [...] }).`
+        );
+      } catch (e) {
+        return textResult(`get_messages failed: ${String(e)}`, true);
+      }
+    }
+  );
+  server.tool(
+    "mark_processed",
+    "Mark the given messages handled \u2014 they are removed from the inbox permanently. Idempotent: ids already gone are ignored. Optional for correctness (get_messages already prevents re-delivery); use it to keep the inbox tidy.",
+    { msg_ids: external_exports.array(external_exports.number().int()).min(1).describe("Message ids (from get_messages) to mark processed.") },
+    async ({ msg_ids }) => {
+      const { id, err } = boundOr();
+      if (err) return err;
+      try {
+        const data = await mutatingTx(id, "::actor::mark_processed", { msg_ids });
+        const n = data.Reduce("processed").Visualize();
+        refreshUnread(id);
+        return textResult(`Marked ${n} message(s) processed.`);
+      } catch (e) {
+        return textResult(`mark_processed failed: ${String(e)}`, true);
+      }
+    }
+  );
+  server.tool(
+    "defer_messages",
+    `Put already-read messages back into the queue (status "unread") so another session's get_messages will pick them up. Use when you read a message but want to leave it for someone else to process.`,
+    { msg_ids: external_exports.array(external_exports.number().int()).min(1).describe("Message ids (from get_messages) to defer back to unread.") },
+    async ({ msg_ids }) => {
+      const { id, err } = boundOr();
+      if (err) return err;
+      try {
+        const data = await mutatingTx(id, "::actor::defer_messages", { msg_ids });
+        const n = data.Reduce("deferred").Visualize();
+        refreshUnread(id);
+        return textResult(`Deferred ${n} message(s) back to unread.`);
       } catch (e) {
-        return textResult(`process_incoming_message failed: ${String(e)}`, true);
+        return textResult(`defer_messages failed: ${String(e)}`, true);
       }
     }
   );
@@ -23030,6 +23099,7 @@ function readBody(req) {
 async function main() {
   if (TRANSPORT === "stdio") {
     const server = createMcpServer(() => "stdio");
+    serversBySession.set("stdio", server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     log("MCP stdio transport connected, booting wrapper\u2026");
@@ -23065,6 +23135,7 @@ async function main() {
             sessionIdGenerator: () => randomUUID(),
             onsessioninitialized: (sid) => {
               transports[sid] = transport;
+              serversBySession.set(sid, server);
               log(`session ${sid.slice(0, 8)}\u2026 initialized`);
             }
           });
@@ -23073,13 +23144,13 @@ async function main() {
             const sid = transport.sessionId;
             if (sid) {
               delete transports[sid];
+              serversBySession.delete(sid);
               const name = sessionBinding.get(sid);
               if (name && bindingOwner.get(name) === sid) bindingOwner.delete(name);
               sessionBinding.delete(sid);
               evictedSessions.delete(sid);
               log(`session ${sid.slice(0, 8)}\u2026 closed`);
             }
-            activeMcpServers.delete(server);
           };
           await server.connect(transport);
           await transport.handleRequest(req, res, body);

package/dist/mufl_code/actor.mu

@@ -7,11 +7,14 @@
 //
 // User transactions (each backs one MCP tool):
 //   set_my_name             — set the display name peers see for me
-//   generate_invite         — make a personal invite blob for a named peer
+//   generate_invite         — make a slim personal invite blob for a named peer
 //   add_contact             — join via an invite blob, reply to the inviter
 //   send_message            — send an e2e-encrypted message to a contact
 //   list_contacts           — (readonly) my contacts
-//   list_incoming_messages  — (readonly) my inbox
+//   list_incoming_messages  — (readonly) my inbox, with per-message id + status
+//   get_messages            — return unread messages + mark them read (sole body egress)
+//   mark_processed          — delete handled messages from the inbox
+//   defer_messages          — flip read messages back to unread for another session
 //
 // External transactions (inbound, not exposed as tools):
 //   accept_contact          — inviter learns the joiner's identity + name
@@ -39,8 +42,27 @@ application actor loads libraries
     hidden
     {
         metadef contact_t: ($name -> str, $container_id -> global_id).
-        metadef invite_t: ($invite_id -> global_id, $inviter_id -> global_id, $inviter_name -> str, $inviter_ad -> address_document_types::t_address_document).
-        metadef message_t: ($sender_id -> global_id, $sender_name -> str, $text -> str, $date -> time).
+        // Slim invite. Short keys (no field-name bloat), no outer wrapper, and
+        // only the cryptographically load-bearing parts travel: the inviter's
+        // signed identity (public keys) + its self-signatures. inviter_id is NOT
+        // carried separately — it is the identity's own container_id. version is
+        // a constant reconstructed on the receiver. (See generate_invite /
+        // add_contact: the embedded identity is kept byte-for-byte so its
+        // _value_id — what the signatures are over — stays valid.)
+        //   $d invite_id   $n inviter_name   $c container_id
+        //   $k public keys  $a authorizations
+        // default_keys is NOT carried — the receiver rebuilds it from the keys
+        // (each key knows its own function + id), so the reconstructed identity is
+        // byte-identical to the signed one and the self-signatures still verify.
+        metadef invite_t: ($d -> global_id, $n -> str, $c -> global_id, $k -> key_utils::t_publickey(,), $a -> crypto_signature(,)).
+        // A received message carries a stable per-packet id and a lifecycle
+        // status: "unread" (just arrived) -> "read" (handed to the agent via
+        // get_messages). mark_processed deletes it; defer_messages flips it back
+        // to "unread" so another session can pick it up.
+        metadef message_t: ($msg_id -> int, $sender_id -> global_id, $sender_name -> str, $text -> str, $date -> time, $status -> str).
+        // The pre-lifecycle inbox shape (no per-message id/status). import_state
+        // migrates blobs in this shape forward — see below.
+        metadef legacy_message_t: ($sender_id -> global_id, $sender_name -> str, $text -> str, $date -> time).
 
         // Wire the deserialization primitive into the libraries that need it.
         _read_or_abort = grab( _read_or_abort ).
@@ -54,8 +76,14 @@ application actor loads libraries
         contacts is (global_id ->> contact_t) = (,).
         // Invites I generated, keyed by invite id -> the name I assigned the peer.
         pending_invites is (global_id ->> str) = (,).
-        // Received messages, append-only (the host tracks how many it surfaced).
+        // Received messages. Each carries its own lifecycle status (see
+        // message_t / get_messages / mark_processed / defer_messages), so the
+        // packet is the single authority on what has been read or processed —
+        // no host-side cursor, safe across concurrent sessions.
         inbox is message_t[] = [].
+        // Monotonic source of per-message ids (the stable handle the agent uses
+        // to mark a message processed or defer it).
+        next_msg_seq is int = 1.
         // Peer address documents, captured when a contact is established. These are
         // self-signed, code-independent, and seed-stable, so on a code upgrade the
         // host re-creates this packet from the same seed and import_state replays
@@ -105,13 +133,20 @@ application actor loads libraries
         // Remember the name I'm assigning to whoever redeems this invite.
         pending_invites invite_id -> name.
 
+        // Carry only my signed identity (public keys) + its self-signatures. The
+        // joiner rebuilds my address document from these (version is constant, my
+        // container_id is the identity's own field) and stores it so it can
+        // re-register me after a code upgrade (see peer_ads / import_state). The
+        // identity sub-record is passed through untouched so its _value_id — what
+        // the authorizations sign over — survives the round trip unchanged.
+        my_ad = address_document::get_my_address_document().
+        my_identity = my_ad $identity.
         invite is invite_t = (
-            $invite_id   -> invite_id,
-            $inviter_id  -> _get_container_id(),
-            $inviter_name -> my_name,
-            // Embed my address document so the joiner can store it and re-register
-            // me after a code upgrade (see peer_ads / import_state).
-            $inviter_ad  -> address_document::get_my_address_document()
+            $d -> invite_id,
+            $n -> my_name,
+            $c -> my_identity $container_id,
+            $k -> my_identity $key_list,
+            $a -> my_ad $authorizations
         ).
 
         return transaction::success [
@@ -129,17 +164,41 @@ application actor loads libraries
         current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
 
         invite = (_read_or_abort invite_blob) safe invite_t.
-        inviter_id = invite $inviter_id.
+        inviter_id = invite $c.
         abort "This invite is your own — you cannot add yourself." when inviter_id == _get_container_id().
 
+        // Rebuild default_keys from the carried public keys: each key reports its
+        // own function and id, so this reproduces the inviter's default-key map
+        // exactly. With it we reconstruct the full identity (and hence its
+        // _value_id, which the self-signatures sign over) byte-for-byte, then the
+        // full address document. import_state later replays this reconstructed
+        // document through process_address_document to re-register the inviter's
+        // keys after a code upgrade — so it must validate, and it does.
+        inviter_keys = invite $k.
+        inviter_default_keys is (key_utils::t_function ->> key_utils::t_key_id) = (,).
+        sc inviter_keys -- (key -> )
+        {
+            inviter_default_keys (key_utils::key_get_function key) -> (_crypto_get_key_id key).
+        }
+        inviter_identity is key_storage::t_container_identity = (
+            $key_list     -> inviter_keys,
+            $default_keys -> inviter_default_keys,
+            $container_id -> inviter_id
+        ).
+        inviter_ad is address_document_types::t_address_document = (
+            $version        -> 1,
+            $identity       -> inviter_identity,
+            $authorizations -> invite $a
+        ).
+
         // Register the inviter under my chosen name, or the name they embedded.
-        contact_name = (custom_name == NIL ?? (invite $inviter_name) ; custom_name?).
+        contact_name = (custom_name == NIL ?? (invite $n) ; custom_name?).
         contacts inviter_id -> ($name -> contact_name, $container_id -> inviter_id).
         // Remember the inviter's address document so I can re-register them after
         // an upgrade (their keys are seed-stable, so this stays valid).
-        peer_ads inviter_id -> invite $inviter_ad.
+        peer_ads inviter_id -> inviter_ad.
 
-        invite_id = invite $invite_id.
+        invite_id = invite $d.
         my_self_name = my_name.
         my_ad = address_document::get_my_address_document().
 
@@ -187,6 +246,117 @@ application actor loads libraries
         return inbox.
     }
 
+    // Hand the agent every message it has not seen yet (status "unread") and
+    // flip those to "read". This is the ONLY place message bodies leave the
+    // packet. Delivery is the dedup point: a message is returned by get_messages
+    // exactly once, so an agent that reads and acts immediately never double-
+    // processes — no explicit acknowledgement is required for safety. To leave a
+    // message for another session instead, call defer_messages (status -> unread
+    // again); to discard it for good, call mark_processed (removed from inbox).
+    trn get_messages _
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        fresh is message_t[] = [].
+        new_inbox is message_t[] = [].
+        sc inbox -- ( -> m)
+        {
+            if (m $status) == "unread"
+            {
+                read_m is message_t = (
+                    $msg_id      -> m $msg_id,
+                    $sender_id   -> m $sender_id,
+                    $sender_name -> m $sender_name,
+                    $text        -> m $text,
+                    $date        -> m $date,
+                    $status      -> "read"
+                ).
+                fresh (_count fresh|) -> m.
+                new_inbox (_count new_inbox|) -> read_m.
+            }
+            else
+            {
+                new_inbox (_count new_inbox|) -> m.
+            }
+        }
+        inbox -> new_inbox.
+
+        return transaction::success [
+            _return_data ($messages -> fresh),
+            _save_state NIL
+        ].
+    }
+
+    // Remove the given messages from the inbox permanently — the agent is done
+    // with them. Idempotent: ids that are already gone are silently skipped.
+    trn mark_processed _:($msg_ids -> ids: int[])
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        wanted is (int ->> bool) = (,).
+        sc ids -- ( -> id) { wanted id -> TRUE. }
+
+        new_inbox is message_t[] = [].
+        removed is int = 0.
+        sc inbox -- ( -> m)
+        {
+            if wanted (m $msg_id)
+            {
+                removed -> removed + 1.
+            }
+            else
+            {
+                new_inbox (_count new_inbox|) -> m.
+            }
+        }
+        inbox -> new_inbox.
+
+        return transaction::success [
+            _return_data ($processed -> removed),
+            _save_state NIL
+        ].
+    }
+
+    // Put already-read messages back into the queue (status -> "unread") so a
+    // different session will pick them up on its next get_messages. The explicit,
+    // opt-in counterpart to the safe default: forgetting to defer just means the
+    // message stays handled by you; only a deliberate defer re-exposes it.
+    trn defer_messages _:($msg_ids -> ids: int[])
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        wanted is (int ->> bool) = (,).
+        sc ids -- ( -> id) { wanted id -> TRUE. }
+
+        new_inbox is message_t[] = [].
+        deferred is int = 0.
+        sc inbox -- ( -> m)
+        {
+            if (wanted (m $msg_id)) && ((m $status) == "read")
+            {
+                new_inbox (_count new_inbox|) -> (
+                    $msg_id      -> m $msg_id,
+                    $sender_id   -> m $sender_id,
+                    $sender_name -> m $sender_name,
+                    $text        -> m $text,
+                    $date        -> m $date,
+                    $status      -> "unread"
+                ).
+                deferred -> deferred + 1.
+            }
+            else
+            {
+                new_inbox (_count new_inbox|) -> m.
+            }
+        }
+        inbox -> new_inbox.
+
+        return transaction::success [
+            _return_data ($deferred -> deferred),
+            _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
@@ -203,6 +373,7 @@ application actor loads libraries
             $contacts        -> contacts,
             $pending_invites -> pending_invites,
             $inbox           -> inbox,
+            $next_msg_seq    -> next_msg_seq,
             $peer_ads        -> peer_ads
         ).
     }
@@ -211,19 +382,44 @@ application actor loads libraries
     {
         current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
 
-        d = data safe (
-            $my_name         -> str,
-            $contacts        -> (global_id ->> contact_t),
-            $pending_invites -> (global_id ->> str),
-            $inbox           -> message_t[],
-            $peer_ads        -> (global_id ->> address_document_types::t_address_document)
-        ).
-
-        my_name         -> d $my_name.
-        contacts        -> d $contacts.
-        pending_invites -> d $pending_invites.
-        inbox           -> d $inbox.
-        peer_ads        -> d $peer_ads.
+        // The fields that did not change across the schema bump are validated the
+        // same way for any version of the blob.
+        my_name         -> (data $my_name) safe str.
+        contacts        -> (data $contacts) safe (global_id ->> contact_t).
+        pending_invites -> (data $pending_invites) safe (global_id ->> str).
+        peer_ads        -> (data $peer_ads) safe (global_id ->> address_document_types::t_address_document).
+
+        // The inbox + next_msg_seq are the only parts the message-lifecycle change
+        // touched. A pre-lifecycle blob has no $next_msg_seq and inbox entries with
+        // no id/status — MIGRATE it forward (the whole point of code-independent
+        // state is that an old export upgrades, never resets): assign each legacy
+        // message a sequential id and status "unread", and seed next_msg_seq past
+        // them. A current blob is taken as-is.
+        if (data $next_msg_seq) == NIL
+        {
+            legacy_inbox = (data $inbox) safe (legacy_message_t[]).
+            migrated is message_t[] = [].
+            seq is int = 1.
+            sc legacy_inbox -- ( -> m)
+            {
+                migrated (_count migrated|) -> (
+                    $msg_id      -> seq,
+                    $sender_id   -> m $sender_id,
+                    $sender_name -> m $sender_name,
+                    $text        -> m $text,
+                    $date        -> m $date,
+                    $status      -> "unread"
+                ).
+                seq -> seq + 1.
+            }
+            inbox        -> migrated.
+            next_msg_seq -> seq.
+        }
+        else
+        {
+            inbox        -> (data $inbox) safe (message_t[]).
+            next_msg_seq -> (data $next_msg_seq) safe int.
+        }
 
         // Re-register every peer's keys so encrypted channels keep working after
         // the upgrade — no handshake needed (my own keys are unchanged, and the
@@ -276,15 +472,23 @@ application actor loads libraries
         sender_name = sender? $name.
         msg_date = current_transaction_info::get_transaction_time().
 
+        mid = next_msg_seq.
+        next_msg_seq -> next_msg_seq + 1.
+
         inbox (_count inbox|) -> (
+            $msg_id      -> mid,
             $sender_id   -> sender_id,
             $sender_name -> sender_name,
             $text        -> text,
-            $date        -> msg_date
+            $date        -> msg_date,
+            $status      -> "unread"
         ).
 
+        // The notification deliberately carries NO message body — only that a
+        // message arrived, from whom, and its id. The body stays in the packet
+        // and only leaves through get_messages.
         return transaction::success [
-            _notify_agent ($event -> $message_received, $sender_name -> sender_name, $text -> text, $date -> msg_date),
+            _notify_agent ($event -> $message_received, $sender_name -> sender_name, $msg_id -> mid, $date -> msg_date),
             _save_state NIL
         ].
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adapt-toolkit/a2adapt",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",