@adapt-toolkit/a2adapt 0.8.0 → 0.9.0

package/dist/cli.js

@@ -13,7 +13,7 @@ import * as fs2 from "node:fs";
 // src/config.ts
 import * as fs from "node:fs";
 import { homedir } from "node:os";
-import { resolve, join, dirname } from "node:path";
+import { resolve, join, dirname, basename } from "node:path";
 var DEFAULT_CONFIG = {
   brokerUrl: "ws://a2adapt.adaptframework.solutions/broker",
   port: 3030,
@@ -70,6 +70,29 @@ function writeConfig(cfg) {
   }
   return path;
 }
+var IDENTITY_FILENAME = ".a2adapt-identity";
+function buildIdentityFile(opts) {
+  if (!opts.name.trim()) throw new Error("identity name must not be empty");
+  const obj = { identity: opts.name.trim() };
+  if (opts.force) obj.force = true;
+  obj.expose_local = opts.exposeLocal ?? true;
+  obj.local_auto_accept = opts.localAutoAccept ?? true;
+  return obj;
+}
+function resolveIdentityFilePath(target) {
+  const abs = resolve(target);
+  return basename(abs) === IDENTITY_FILENAME ? abs : join(abs, IDENTITY_FILENAME);
+}
+function writeIdentityFile(target, opts, overwrite = false) {
+  const obj = buildIdentityFile(opts);
+  const path = resolveIdentityFilePath(target);
+  if (!overwrite && fs.existsSync(path)) {
+    throw new Error(`${path} already exists \u2014 pass overwrite to replace it`);
+  }
+  fs.mkdirSync(dirname(path), { recursive: true });
+  fs.writeFileSync(path, JSON.stringify(obj, null, 2) + "\n");
+  return path;
+}
 
 // src/cli.ts
 var CONFIG = loadConfig();
@@ -274,6 +297,93 @@ daemon is running (pid ${pid}); restart now to apply? [y/N]: `)).trim().toLowerC
   const r = spawnSync(process.execPath, [SELF, "start"], { stdio: "inherit" });
   if (r.status !== 0) process.exit(r.status ?? 1);
 }
+function flagPair(argv, on, off) {
+  if (argv.includes(off)) return { value: false, set: true };
+  if (argv.includes(on)) return { value: true, set: true };
+  return { value: void 0, set: false };
+}
+function flagValue(argv, name) {
+  const i = argv.indexOf(name);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : void 0;
+}
+async function cmdDefineLocalIdentityFile(argv) {
+  const name = flagValue(argv, "--name");
+  const force = flagPair(argv, "--force-bind", "--no-force-bind");
+  const localBook = flagPair(argv, "--local-book", "--no-local-book");
+  const autoAccept = flagPair(argv, "--auto-accept-local", "--no-auto-accept-local");
+  const overwrite = argv.includes("--overwrite");
+  const print = argv.includes("--print");
+  const target = flagValue(argv, "--path") ?? flagValue(argv, "--dir") ?? process.cwd();
+  const nonInteractive = name !== void 0 || force.set || localBook.set || autoAccept.set || print;
+  let opts;
+  if (nonInteractive) {
+    if (!name || !name.trim()) {
+      err("define-local-identity-file: --name is required in non-interactive mode.");
+      process.exit(1);
+    }
+    opts = {
+      name: name.trim(),
+      force: force.value ?? false,
+      exposeLocal: localBook.value ?? true,
+      localAutoAccept: autoAccept.value ?? true
+    };
+  } else {
+    opts = await runIdentitySurvey();
+  }
+  if (print) {
+    out(JSON.stringify(buildIdentityFile(opts), null, 2));
+    return;
+  }
+  const path = resolveIdentityFilePath(target);
+  if (!overwrite && fs2.existsSync(path)) {
+    if (nonInteractive) {
+      err(`define-local-identity-file: ${path} already exists \u2014 pass --overwrite to replace it.`);
+      process.exit(1);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let ok = false;
+    try {
+      const ans = (await rl.question(`
+${path} already exists \u2014 overwrite? [y/N]: `)).trim().toLowerCase();
+      ok = ans === "y" || ans === "yes";
+    } finally {
+      rl.close();
+    }
+    if (!ok) {
+      out("aborted \u2014 nothing written.");
+      return;
+    }
+  }
+  const written = writeIdentityFile(target, opts, true);
+  out("");
+  out(`wrote ${written}:`);
+  out(JSON.stringify(buildIdentityFile(opts), null, 2));
+}
+async function runIdentitySurvey() {
+  out(`a2adapt-mcp define-local-identity-file \u2014 interactive`);
+  out(`Answer the prompts; the result is written to ${join2(process.cwd(), IDENTITY_FILENAME)}.`);
+  out("");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const askYesNo = async (label, def) => {
+      const hint = def ? "Y/n" : "y/N";
+      const ans = (await rl.question(`  ${label} [${hint}]: `)).trim().toLowerCase();
+      if (ans === "") return def;
+      return ans === "y" || ans === "yes";
+    };
+    let name = "";
+    while (!name) {
+      name = (await rl.question("  Identity name: ")).trim();
+      if (!name) out("  (name is required)");
+    }
+    const force = await askYesNo("Force-bind (pin pre-authorizes evicting another session)?", false);
+    const exposeLocal = await askYesNo("Add to the host-local contact book?", true);
+    const localAutoAccept = await askYesNo("Auto-accept local invites/introductions?", true);
+    return { name, force, exposeLocal, localAutoAccept };
+  } finally {
+    rl.close();
+  }
+}
 function cmdWatch(which) {
   const offsets = /* @__PURE__ */ new Map();
   const scan = (initial) => {
@@ -321,9 +431,15 @@ function cmdWatch(which) {
         } catch {
           continue;
         }
-        out(
-          `[${name}] new message from ${msg.from ?? "?"}` + (msg.msg_id !== void 0 ? ` (#${msg.msg_id})` : "") + (msg.date ? `  (${msg.date})` : "")
-        );
+        if (msg.event === "local_contact_request") {
+          out(`[${name}] pending local introduction from ${msg.from ?? "?"} \u2014 respond_to_introduction to approve/reject`);
+        } else if (msg.event === "pending_message") {
+          out(`[${name}] ${msg.from ?? "?"} queued a message awaiting introduction approval (${msg.queued ?? "?"} queued)`);
+        } else {
+          out(
+            `[${name}] new message from ${msg.from ?? "?"}` + (msg.msg_id !== void 0 ? ` (#${msg.msg_id})` : "") + (msg.date ? `  (${msg.date})` : "")
+          );
+        }
       }
     }
   };
@@ -476,6 +592,12 @@ function usage() {
   out("  serve     run in the foreground (used by start; handy for debugging)");
   out("  watch [identity]  stream one line per new inbound message (wake source for a Monitor)");
   out("");
+  out("  define-local-identity-file   write a .a2adapt-identity workspace pin");
+  out("    interactive (default): 4-question survey, writes to CWD");
+  out("    scripted: --name <s> [--force-bind] [--local-book] [--auto-accept-local]");
+  out("              negate with --no-force-bind / --no-local-book / --no-auto-accept-local");
+  out("              --dir <path> | --path <file> (default CWD) \xB7 --overwrite \xB7 --print");
+  out("");
   out("  install-service    install + start a boot-persistent service (systemd/launchd)");
   out("  uninstall-service  stop + remove that service");
   out("");
@@ -525,6 +647,9 @@ async function main() {
     case "setup":
       await cmdSetup();
       break;
+    case "define-local-identity-file":
+      await cmdDefineLocalIdentityFile(process.argv.slice(3));
+      break;
     case "watch":
       cmdWatch(process.argv[3]);
       break;

package/dist/hooks/runner.js

@@ -86,8 +86,14 @@ function findPinnedIdentity(start) {
       continue;
     }
     try {
-      const name = String(JSON.parse(raw).identity ?? "").trim();
-      return name || null;
+      const parsed = JSON.parse(raw);
+      const name = String(parsed.identity ?? "").trim();
+      if (!name) return null;
+      const pin = { identity: name };
+      if (typeof parsed.force === "boolean") pin.force = parsed.force;
+      if (typeof parsed.expose_local === "boolean") pin.expose_local = parsed.expose_local;
+      if (typeof parsed.local_auto_accept === "boolean") pin.local_auto_accept = parsed.local_auto_accept;
+      return pin;
     } catch {
       return null;
     }
@@ -117,9 +123,20 @@ function anyIdentityBound() {
     return err.code === "EPERM";
   }
 }
-function renderIdentityDirective(name, exists) {
-  const bind = exists ? `call \`choose_identity({ name: "${name}" })\` to bind it to this session` : `it does not exist yet \u2014 call \`create_identity({ name: "${name}" })\` to create and bind it`;
-  return `a2adapt \u2014 this workspace is pinned to identity "${name}" (via ${IDENTITY_FILE}). Before other a2adapt work, ${bind}. Then arm a Monitor on the wake source \`a2adapt-mcp watch ${name}\` so new mail wakes you. Do this once, up front. The pin is the workspace default: if the user explicitly asks to use a different identity, bind that instead \u2014 the user's choice always wins. If choose_identity reports the identity is held by another session, do NOT retry with force \u2014 tell the user it is bound elsewhere and ask whether to forcibly rebind it to this session; only pass force=true after they confirm.`;
+function renderIdentityDirective(pin, exists) {
+  const name = pin.identity;
+  let bind;
+  if (exists) {
+    bind = pin.force ? `call \`choose_identity({ name: "${name}", force: true })\` to bind it to this session (the workspace pin sets force, so evicting another holder is pre-authorized \u2014 no need to ask)` : `call \`choose_identity({ name: "${name}" })\` to bind it to this session`;
+  } else {
+    const extras = [];
+    if (pin.expose_local !== void 0) extras.push(`expose_local: ${pin.expose_local}`);
+    if (pin.local_auto_accept !== void 0) extras.push(`local_auto_accept: ${pin.local_auto_accept}`);
+    const args = [`name: "${name}"`, ...extras].join(", ");
+    bind = `it does not exist yet \u2014 call \`create_identity({ ${args} })\` to create and bind it`;
+  }
+  const forceTail = pin.force ? "" : ` If choose_identity reports the identity is held by another session, do NOT retry with force \u2014 tell the user it is bound elsewhere and ask whether to forcibly rebind it to this session; only pass force=true after they confirm.`;
+  return `a2adapt \u2014 this workspace is pinned to identity "${name}" (via ${IDENTITY_FILE}). Before other a2adapt work, ${bind}. Then arm a Monitor on the wake source \`a2adapt-mcp watch ${name}\` so new mail wakes you. Do this once, up front. The pin is the workspace default: if the user explicitly asks to use a different identity, bind that instead \u2014 the user's choice always wins.` + forceTail;
 }
 function sessionStart() {
   const raw = readStdin();
@@ -137,7 +154,7 @@ function sessionStart() {
   const pinned = findPinnedIdentity(cwd);
   const unread = collectUnread();
   const blocks = [];
-  if (pinned) blocks.push(renderIdentityDirective(pinned, identityExists(pinned)));
+  if (pinned) blocks.push(renderIdentityDirective(pinned, identityExists(pinned.identity)));
   if (unread.length > 0) blocks.push(renderContext(unread));
   if (blocks.length === 0) return noop();
   emit({
@@ -164,7 +181,7 @@ function userPromptSubmit() {
     continue: true,
     hookSpecificOutput: {
       hookEventName: "UserPromptSubmit",
-      additionalContext: renderIdentityDirective(pinned, identityExists(pinned))
+      additionalContext: renderIdentityDirective(pinned, identityExists(pinned.identity))
     }
   });
 }

package/dist/index.js

@@ -22427,7 +22427,7 @@ var StreamableHTTPServerTransport = class {
 };
 
 // src/index.ts
-import { resolve as resolve2, join as join2, dirname as dirname2 } from "node:path";
+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 { createServer as createHttpServer } from "node:http";
@@ -22440,7 +22440,7 @@ import { object_to_adapt_value } from "@adapt-toolkit/sdk/wrapper";
 // src/config.ts
 import * as fs from "node:fs";
 import { homedir } from "node:os";
-import { resolve, join, dirname } from "node:path";
+import { resolve, join, dirname, basename } from "node:path";
 var DEFAULT_CONFIG = {
   brokerUrl: "ws://a2adapt.adaptframework.solutions/broker",
   port: 3030,
@@ -22487,9 +22487,32 @@ function loadConfig() {
     gcIntervalMs: envInt("A2ADAPT_GC_INTERVAL_MS") ?? file.gcIntervalMs ?? DEFAULT_CONFIG.gcIntervalMs
   };
 }
+var IDENTITY_FILENAME = ".a2adapt-identity";
+function buildIdentityFile(opts) {
+  if (!opts.name.trim()) throw new Error("identity name must not be empty");
+  const obj = { identity: opts.name.trim() };
+  if (opts.force) obj.force = true;
+  obj.expose_local = opts.exposeLocal ?? true;
+  obj.local_auto_accept = opts.localAutoAccept ?? true;
+  return obj;
+}
+function resolveIdentityFilePath(target) {
+  const abs = resolve(target);
+  return basename(abs) === IDENTITY_FILENAME ? abs : join(abs, IDENTITY_FILENAME);
+}
+function writeIdentityFile(target, opts, overwrite = false) {
+  const obj = buildIdentityFile(opts);
+  const path = resolveIdentityFilePath(target);
+  if (!overwrite && fs.existsSync(path)) {
+    throw new Error(`${path} already exists \u2014 pass overwrite to replace it`);
+  }
+  fs.mkdirSync(dirname(path), { recursive: true });
+  fs.writeFileSync(path, JSON.stringify(obj, null, 2) + "\n");
+  return path;
+}
 
 // src/index.ts
-var VERSION = true ? "0.8.0" : "0.0.0-dev";
+var VERSION = true ? "0.9.0" : "0.0.0-dev";
 var CONFIG = loadConfig();
 var STATE_DIR = CONFIG.stateDir;
 var BROKER_URL = CONFIG.brokerUrl;
@@ -22499,6 +22522,7 @@ var GC_INTERVAL_MS = CONFIG.gcIntervalMs;
 var log = (...parts) => process.stderr.write(`a2adapt: ${parts.join(" ")}
 `);
 var NAME_RE = /^[A-Za-z0-9 _.-]{1,64}$/;
+var BOOK_DIR_NAME = "contact-book";
 function validateName(name) {
   if (!NAME_RE.test(name)) {
     return "name must be 1-64 chars of letters, digits, space, _ . or -";
@@ -22506,6 +22530,9 @@ function validateName(name) {
   if (name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
     return "invalid name";
   }
+  if (name === BOOK_DIR_NAME) {
+    return `"${BOOK_DIR_NAME}" is reserved for the local contact book`;
+  }
   return null;
 }
 function locateUnit() {
@@ -22528,6 +22555,8 @@ function locateUnit() {
 var UNIT;
 var wrapper;
 var identities = /* @__PURE__ */ new Map();
+var registrar = null;
+var registrarAdBlob = null;
 var sessionBinding = /* @__PURE__ */ new Map();
 var bindingOwner = /* @__PURE__ */ new Map();
 var evictedSessions = /* @__PURE__ */ new Set();
@@ -22551,6 +22580,102 @@ function listPersistedNames() {
   if (!fs2.existsSync(STATE_DIR)) return [];
   return fs2.readdirSync(STATE_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && fs2.existsSync(seedPath(join2(STATE_DIR, d.name)))).map((d) => d.name);
 }
+var bookDir = () => join2(STATE_DIR, BOOK_DIR_NAME);
+var registrarSeedPath = () => join2(bookDir(), "registrar.seed");
+var bookPath = () => join2(bookDir(), "book.json");
+function readBook() {
+  try {
+    const parsed = JSON.parse(fs2.readFileSync(bookPath(), "utf8"));
+    return parsed && typeof parsed.entries === "object" ? parsed.entries : {};
+  } catch {
+    return {};
+  }
+}
+function writeBook(entries) {
+  fs2.mkdirSync(bookDir(), { recursive: true });
+  const tmp = `${bookPath()}.tmp`;
+  fs2.writeFileSync(tmp, JSON.stringify({ v: 1, entries }, null, 2), { mode: 384 });
+  fs2.renameSync(tmp, bookPath());
+}
+function exportAdBlob(id) {
+  return Buffer.from(readonlyTx(id, "::actor::export_address_document").GetBinary());
+}
+async function publishToBook(id) {
+  if (!registrar) throw new Error("registrar is not available");
+  const adBlob = exportAdBlob(id);
+  const sigData = await mutatingTx(registrar, "::actor::sign_book_entry", {
+    name: id.name,
+    ad: registrar.pw.packet.NewBinaryFromBuffer(adBlob)
+  });
+  const entries = readBook();
+  entries[id.name] = {
+    v: 1,
+    name: id.name,
+    container_id: id.cid,
+    address_document: adBlob.toString("base64url"),
+    published_at: (/* @__PURE__ */ new Date()).toISOString(),
+    registrar_sig: Buffer.from(sigData.Reduce("sig").GetBinary()).toString("base64url")
+  };
+  writeBook(entries);
+  log(`[${id.name}] published to the local contact book`);
+}
+function unpublishFromBook(name) {
+  const entries = readBook();
+  if (!(name in entries)) return;
+  delete entries[name];
+  writeBook(entries);
+  log(`[${name}] removed from the local contact book`);
+}
+async function pinRegistrar(id) {
+  if (!registrarAdBlob) throw new Error("registrar is not available");
+  await mutatingTx(id, "::actor::pin_registrar", {
+    registrar_ad: id.pw.packet.NewBinaryFromBuffer(registrarAdBlob)
+  });
+}
+async function sendViaLocalBook(id, contact, text) {
+  if (!registrar) {
+    throw new Error(`"${contact}" is not a contact, and the local contact book is unavailable.`);
+  }
+  const entries = readBook();
+  const entry = entries[contact] ?? Object.values(entries).find((e) => e.container_id === contact);
+  if (!entry) {
+    throw new Error(
+      `"${contact}" is not a contact and has no local contact-book entry. Use generate_invite/add_contact for remote peers, or list_local_contact_book to see local ones.`
+    );
+  }
+  if (entry.container_id === id.cid) {
+    throw new Error("that contact-book entry is this identity itself.");
+  }
+  const targetAd = Buffer.from(entry.address_document, "base64url");
+  const entrySig = Buffer.from(entry.registrar_sig, "base64url");
+  const joinerAd = exportAdBlob(id);
+  const minted = await mutatingTx(registrar, "::actor::mint_introduction", {
+    joiner_ad: registrar.pw.packet.NewBinaryFromBuffer(joinerAd),
+    target_ad: registrar.pw.packet.NewBinaryFromBuffer(targetAd)
+  });
+  const introBlob = Buffer.from(minted.Reduce("intro").GetBinary());
+  await mutatingTx(id, "::actor::connect_local", {
+    name: entry.name,
+    target_ad: id.pw.packet.NewBinaryFromBuffer(targetAd),
+    intro: id.pw.packet.NewBinaryFromBuffer(introBlob),
+    entry_sig: id.pw.packet.NewBinaryFromBuffer(entrySig),
+    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.`;
+}
+async function ensureRegistrar() {
+  fs2.mkdirSync(bookDir(), { recursive: true });
+  let seed;
+  try {
+    seed = fs2.readFileSync(registrarSeedPath(), "utf8").trim();
+  } catch {
+    seed = randomBytes(24).toString("hex");
+    fs2.writeFileSync(registrarSeedPath(), seed, { mode: 384 });
+  }
+  registrar = await createPacket(BOOK_DIR_NAME, seed, bookDir(), false);
+  registrarAdBlob = exportAdBlob(registrar);
+  log(`contact-book registrar ready (${registrar.cid})`);
+}
 function hasSavedState(dir) {
   try {
     return fs2.existsSync(dataPath(dir)) && fs2.statSync(dataPath(dir)).size > 0;
@@ -22572,11 +22697,10 @@ function saveState(id) {
     log(`[${id.name}] failed to save state:`, String(err));
   }
 }
-function appendNotifyLog(id, from, msgId, date3) {
+function appendNotifyLog(id, event) {
   try {
     fs2.mkdirSync(id.dir, { recursive: true });
-    const line = JSON.stringify({ event: "message_received", from, msg_id: msgId, date: date3 }) + "\n";
-    fs2.appendFileSync(notifyLogPath(id.dir), line);
+    fs2.appendFileSync(notifyLogPath(id.dir), JSON.stringify(event) + "\n");
   } catch (err) {
     log(`[${id.name}] failed to append notifications.log:`, String(err));
   }
@@ -22660,7 +22784,7 @@ function wireHandlers(id) {
         const sender = payload.Reduce("sender_name").Visualize();
         const msgId = payload.Reduce("msg_id").Visualize();
         const date3 = payload.Reduce("date").Visualize();
-        appendNotifyLog(id, sender, msgId, date3);
+        appendNotifyLog(id, { event: "message_received", from: sender, msg_id: msgId, date: date3 });
         refreshUnread(id);
         process.nextTick(
           () => pushNotification(id.name, `[${id.name}] new message from ${sender} (#${msgId})`)
@@ -22671,6 +22795,29 @@ function wireHandlers(id) {
         process.nextTick(
           () => pushNotification(id.name, `[${id.name}] contact "${name}" (${cid}) accepted your invite.`)
         );
+      } else if (event === "local_contact_added") {
+        const name = payload.Reduce("name").Visualize();
+        const cid = payload.Reduce("container_id").Visualize();
+        process.nextTick(
+          () => pushNotification(id.name, `[${id.name}] local contact "${name}" (${cid}) connected via the contact book.`)
+        );
+      } else if (event === "local_contact_request") {
+        const name = payload.Reduce("name").Visualize();
+        const cid = payload.Reduce("container_id").Visualize();
+        appendNotifyLog(id, { event: "local_contact_request", from: name });
+        process.nextTick(
+          () => pushNotification(
+            id.name,
+            `[${id.name}] pending local introduction from "${name}" (${cid}) \u2014 approve or reject with respond_to_introduction.`
+          )
+        );
+      } else if (event === "pending_message") {
+        const name = payload.Reduce("sender_name").Visualize();
+        const queued = payload.Reduce("queued").Visualize();
+        appendNotifyLog(id, { event: "pending_message", from: name, queued });
+        process.nextTick(
+          () => pushNotification(id.name, `[${id.name}] "${name}" queued a message awaiting introduction approval (${queued} queued).`)
+        );
       }
       return;
     }
@@ -22689,7 +22836,7 @@ function wireHandlers(id) {
     }
   };
 }
-function createPacket(name, seed, dir) {
+function createPacket(name, seed, dir, track = true) {
   const config2 = new PacketWrapperConfigurator();
   config2.process_arguments([
     "--unit_hash",
@@ -22718,7 +22865,7 @@ function createPacket(name, seed, dir) {
           lock: Promise.resolve()
         };
         wireHandlers(id);
-        identities.set(name, id);
+        if (track) identities.set(name, id);
         log(`[${name}] packet created \u2014 container id ${id.cid}`);
         resolveCreate(id);
       },
@@ -22726,13 +22873,20 @@ function createPacket(name, seed, dir) {
     );
   });
 }
-async function provisionIdentity(name) {
+async function provisionIdentity(name, opts = { exposeLocal: true, localAutoAccept: true }) {
   const dir = identityDir(name);
   fs2.mkdirSync(dir, { recursive: true });
   const seed = randomBytes(24).toString("hex");
   fs2.writeFileSync(seedPath(dir), seed, { mode: 384 });
   const id = await createPacket(name, seed, dir);
   await mutatingTx(id, "::actor::set_my_name", { name });
+  await pinRegistrar(id);
+  if (!opts.localAutoAccept) {
+    await mutatingTx(id, "::actor::set_local_policy", { auto_accept: false });
+  }
+  if (opts.exposeLocal) {
+    await publishToBook(id);
+  }
   saveState(id);
   return id;
 }
@@ -22769,6 +22923,11 @@ async function bootWrapper() {
   wrapper = await adapt_wrapper.start(argv);
   wrapper.on_packet_created_cb = (cid) => log(`wrapper: packet ready ${cid.slice(0, 12)}\u2026`);
   wrapper.start();
+  try {
+    await ensureRegistrar();
+  } catch (err) {
+    log("failed to start the contact-book registrar (local contact book disabled):", String(err));
+  }
   const names = listPersistedNames();
   if (names.length === 0) {
     log("no persisted identities \u2014 start with create_identity");
@@ -22776,7 +22935,10 @@ async function bootWrapper() {
     log(`restoring ${names.length} identit${names.length === 1 ? "y" : "ies"}: ${names.join(", ")}`);
     for (const name of names) {
       try {
-        await restoreIdentity(name);
+        const id = await restoreIdentity(name);
+        if (registrar) {
+          await pinRegistrar(id);
+        }
       } catch (err) {
         log(`failed to restore "${name}":`, String(err));
       }
@@ -22841,6 +23003,20 @@ function renderInbox(v) {
   }
   return out;
 }
+function renderPending(v) {
+  const out = [];
+  if (v.IsNil()) return out;
+  for (const key of v.GetKeys()) {
+    const p = v.Reduce(key);
+    if (p.IsNil()) continue;
+    out.push({
+      container_id: typeof key === "string" ? key : key.Visualize(),
+      name: p.Reduce("name").Visualize(),
+      queued: parseInt(p.Reduce("queued").Visualize(), 10) || 0
+    });
+  }
+  return out;
+}
 function textResult(text, isError = false) {
   return { content: [{ type: "text", text }], isError };
 }
@@ -22876,21 +23052,52 @@ function createMcpServer(getSessionId) {
   };
   server.tool(
     "create_identity",
-    "Create a new self-sovereign identity (an ADAPT node) with the given display name and bind it to this session. The name is what peers see for you in invites. Persisted permanently; reject if the name already exists.",
-    { name: external_exports.string().min(1).describe('Display name for the new identity, e.g. "Alice".') },
-    async ({ name }) => {
+    "Create a new self-sovereign identity (an ADAPT node) with the given display name and bind it to this session. The name is what peers see for you in invites. Persisted permanently; reject if the name already exists. By default the identity is published to the LOCAL contact book, so other identities on this host can message it by name without an invite; pass expose_local=false to opt out.",
+    {
+      name: external_exports.string().min(1).describe('Display name for the new identity, e.g. "Alice".'),
+      expose_local: external_exports.boolean().default(true).describe("Publish this identity in the host-local contact book."),
+      local_auto_accept: external_exports.boolean().default(true).describe("Auto-accept local contact-book introductions (false = they queue for approval).")
+    },
+    async ({ name, expose_local, local_auto_accept }) => {
       const bad = validateName(name);
       if (bad) return textResult(`create_identity failed: ${bad}`, true);
       if (identities.has(name)) return textResult(`create_identity failed: an identity named "${name}" already exists.`, true);
       try {
-        const id = await provisionIdentity(name);
+        const id = await provisionIdentity(name, { exposeLocal: expose_local, localAutoAccept: local_auto_accept });
         bindSession(getSessionId(), name);
-        return textResult(`Created identity "${name}" (${id.cid}) and bound it to this session.`);
+        const exposure = expose_local ? ` Published to the local contact book${local_auto_accept ? "" : " (introductions require approval)"}.` : " Not exposed in the local contact book.";
+        return textResult(`Created identity "${name}" (${id.cid}) and bound it to this session.${exposure}`);
       } catch (err) {
         return textResult(`create_identity failed: ${String(err)}`, true);
       }
     }
   );
+  server.tool(
+    "define_local_identity_file",
+    "Write a `.a2adapt-identity` workspace-pin file that ties a directory to an identity, so a future Claude Code session here auto-binds it (and the SessionStart hook arms the right Monitor). Use this instead of hand-writing the file. Because this daemon is shared and its CWD is not the user's project, you MUST pass an absolute `path` (the target directory, or the full path ending in .a2adapt-identity). Refuses to overwrite unless overwrite=true.",
+    {
+      name: external_exports.string().min(1).describe("Identity name the workspace belongs to."),
+      path: external_exports.string().min(1).describe("Absolute target: a directory (file is created inside it) or a full path ending in .a2adapt-identity."),
+      force: external_exports.boolean().default(false).describe("Pin pre-authorizes force-binding (evicting another session) \u2014 no user prompt at bind time."),
+      expose_local: external_exports.boolean().default(true).describe("Publish this identity in the host-local contact book."),
+      local_auto_accept: external_exports.boolean().default(true).describe("Auto-accept local contact-book introductions (false = they queue for approval)."),
+      overwrite: external_exports.boolean().default(false).describe("Replace an existing .a2adapt-identity file.")
+    },
+    async ({ name, path, force, expose_local, local_auto_accept, overwrite }) => {
+      if (!isAbsolute(path)) {
+        return textResult(`define_local_identity_file failed: path must be absolute (got "${path}").`, true);
+      }
+      const opts = { name, force, exposeLocal: expose_local, localAutoAccept: local_auto_accept };
+      try {
+        const written = writeIdentityFile(path, opts, overwrite);
+        const json = JSON.stringify(buildIdentityFile(opts), null, 2);
+        return textResult(`Wrote ${written}:
+${json}`);
+      } catch (err) {
+        return textResult(`define_local_identity_file failed: ${String(err)}`, true);
+      }
+    }
+  );
   server.tool(
     "choose_identity",
     "Bind an existing identity to this session so the messaging tools act as it. Binding is exclusive: if the identity is already in use by another session, this is declined unless force=true, which evicts the other session. Never pass force=true on your own initiative \u2014 ask the user and get an explicit confirmation first.",
@@ -22960,6 +23167,11 @@ ${lines.join("\n")}`);
         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);
@@ -23040,24 +23252,113 @@ ${blob}`
   );
   server.tool(
     "list_contacts",
-    "List the contacts the bound identity knows about (name + container id).",
+    "List the contacts the bound identity knows about (name + container id), plus any pending local-contact-book introductions awaiting approval.",
     {},
     async () => {
       const { id, err } = boundOr();
       if (err) return err;
       try {
         const contacts = renderContacts(readonlyTx(id, "::actor::list_contacts"));
-        if (contacts.length === 0) return textResult("No contacts yet.");
-        return textResult(`Contacts (${contacts.length}):
-${contacts.map((c) => `\u2022 ${c.name} \u2014 ${c.container_id}`).join("\n")}`);
+        const pending = renderPending(readonlyTx(id, "::actor::list_pending_introductions"));
+        const lines = [];
+        lines.push(
+          contacts.length === 0 ? "No contacts yet." : `Contacts (${contacts.length}):
+${contacts.map((c) => `\u2022 ${c.name} \u2014 ${c.container_id}`).join("\n")}`
+        );
+        if (pending.length > 0) {
+          lines.push(
+            `Pending local introductions (${pending.length}) \u2014 approve/reject with respond_to_introduction:
+` + pending.map((p) => `\u2022 ${p.name} \u2014 ${p.container_id} (${p.queued} queued message${p.queued === 1 ? "" : "s"})`).join("\n")
+          );
+        }
+        return textResult(lines.join("\n\n"));
       } catch (e) {
         return textResult(`list_contacts failed: ${String(e)}`, true);
       }
     }
   );
+  server.tool(
+    "list_local_contact_book",
+    "List the host-local contact book: identities on THIS host that are exposed for inviteless connection. Any of them can be messaged directly with send_message.",
+    {},
+    async () => {
+      const entries = Object.values(readBook());
+      if (entries.length === 0) return textResult("The local contact book is empty.");
+      const sid = getSessionId();
+      const mine = sessionBinding.get(sid);
+      const lines = entries.map((e) => {
+        const tag = e.name === mine ? "  \u2190 this session" : "";
+        return `\u2022 ${e.name} \u2014 ${e.container_id} (published ${e.published_at})${tag}`;
+      });
+      return textResult(`Local contact book (${entries.length}):
+${lines.join("\n")}`);
+    }
+  );
+  server.tool(
+    "set_local_book_policy",
+    "Change the bound identity's local-contact-book settings: expose (publish/unpublish it in the book) and/or auto_accept (whether local introductions are accepted automatically or queue for approval).",
+    {
+      expose: external_exports.boolean().optional().describe("Publish (true) or remove (false) this identity in the local contact book."),
+      auto_accept: external_exports.boolean().optional().describe("Auto-accept local introductions (false = queue them for approval).")
+    },
+    async ({ expose, auto_accept }) => {
+      const { id, err } = boundOr();
+      if (err) return err;
+      if (expose === void 0 && auto_accept === void 0) {
+        return textResult("set_local_book_policy: pass expose and/or auto_accept.", true);
+      }
+      const done = [];
+      try {
+        if (auto_accept !== void 0) {
+          await mutatingTx(id, "::actor::set_local_policy", { auto_accept });
+          done.push(`auto_accept=${auto_accept}`);
+        }
+        if (expose === true) {
+          await publishToBook(id);
+          done.push("published in the local contact book");
+        } else if (expose === false) {
+          unpublishFromBook(id.name);
+          done.push("removed from the local contact book");
+        }
+        return textResult(`Updated "${id.name}": ${done.join("; ")}.`);
+      } catch (e) {
+        return textResult(`set_local_book_policy failed: ${String(e)}`, true);
+      }
+    }
+  );
+  server.tool(
+    "respond_to_introduction",
+    "Approve or reject a pending local-contact-book introduction (see list_contacts for the pending list). Approving registers the contact and delivers any messages it queued while waiting; rejecting drops the introduction and its queue.",
+    {
+      contact: external_exports.string().min(1).describe("Pending introduction to act on (name or container id)."),
+      action: external_exports.enum(["approve", "reject"]).describe("approve or reject.")
+    },
+    async ({ contact, action }) => {
+      const { id, err } = boundOr();
+      if (err) return err;
+      try {
+        if (action === "approve") {
+          const data2 = await mutatingTx(id, "::actor::approve_introduction", { contact });
+          const name2 = data2.Reduce("approved").Visualize();
+          const cid = data2.Reduce("container_id").Visualize();
+          const flushed = data2.Reduce("flushed").Visualize();
+          refreshUnread(id);
+          return textResult(
+            `Approved "${name2}" (${cid}) \u2014 now a contact. ${flushed} queued message(s) moved to the inbox (read them with get_messages).`
+          );
+        }
+        const data = await mutatingTx(id, "::actor::reject_introduction", { contact });
+        const name = data.Reduce("rejected").Visualize();
+        const dropped = data.Reduce("dropped_messages").Visualize();
+        return textResult(`Rejected the introduction from "${name}" and dropped ${dropped} queued message(s).`);
+      } catch (e) {
+        return textResult(`respond_to_introduction failed: ${String(e)}`, true);
+      }
+    }
+  );
   server.tool(
     "send_message",
-    "Send an end-to-end-encrypted message to a known contact (by name or container id). Requires a bound identity.",
+    "Send an end-to-end-encrypted message to a known contact (by name or container id). If the recipient is not a contact yet but is published in the host-local contact book, the connection is established automatically (no invite needed) and the message is delivered with the introduction. Requires a bound identity.",
     {
       contact: external_exports.string().min(1).describe("Contact name or container id to send to."),
       text: external_exports.string().min(1).describe("The message text.")
@@ -23069,13 +23370,21 @@ ${contacts.map((c) => `\u2022 ${c.name} \u2014 ${c.container_id}`).join("\n")}`)
         await mutatingTx(id, "::actor::send_message", { contact, text });
         return textResult(`Message sent to "${contact}".`);
       } catch (e) {
-        return textResult(`send_message failed: ${String(e)}`, true);
+        if (!/Unknown contact/.test(String(e))) {
+          return textResult(`send_message failed: ${String(e)}`, true);
+        }
+        try {
+          const sent = await sendViaLocalBook(id, contact, text);
+          return textResult(sent);
+        } catch (e2) {
+          return textResult(`send_message failed: ${String(e2)}`, true);
+        }
       }
     }
   );
   server.tool(
     "remove_contact",
-    "Forget a contact (by name or container id) \u2014 drops it from the bound identity's contacts, so you can no longer message them and inbound messages from them are rejected. This is a contacts-layer forget, NOT a key wipe: the per-peer channel key material persists, so re-adding the same peer reuses the existing encrypted channel rather than re-handshaking. Requires a bound identity.",
+    "Forget a contact (by name or container id) \u2014 drops it from the bound identity's contacts, so you can no longer message them and inbound messages from them are rejected. This is a contacts-layer forget, NOT a key wipe: the per-peer channel key material persists, so re-adding the same peer reuses the existing encrypted channel rather than re-handshaking. Note: if the removed peer is still published in the host-local contact book, a later send_message to it will reconnect through the book. Requires a bound identity.",
     { contact: external_exports.string().min(1).describe("Contact name or container id to remove.") },
     async ({ contact }) => {
       const { id, err } = boundOr();

package/dist/mufl_code/actor.mu

@@ -17,9 +17,22 @@
 //   defer_messages          — flip processed/ready_to_delete messages back to unread
 //   gc                      — two-generation GC of handled messages (host-fired, not a tool)
 //
+// Local contact book (host-fired transactions; see the design notes above
+// local_introduce below):
+//   export_address_document — (readonly) my signed address document as a blob
+//   pin_registrar           — pin the host registrar's signing keys (pin-once)
+//   set_local_policy        — toggle auto-accept of local introductions
+//   mint_introduction       — registrar-only in practice: sign an introduction credential
+//   sign_book_entry         — registrar-only in practice: sign a contact-book entry
+//   connect_local           — register a book contact + send local_introduce (+ first message)
+//   approve_introduction    — accept a pending local introduction (flushes its queue)
+//   reject_introduction     — drop a pending local introduction
+//   list_pending_introductions — (readonly) pending introductions (names + queue sizes)
+//
 // External transactions (inbound, not exposed as tools):
 //   accept_contact          — inviter learns the joiner's identity + name
 //   receive_message         — store a decrypted inbound message
+//   local_introduce         — same-host peer connects via the local contact book
 //
 // Naming model (personal invites): generate_invite('Bob') tags a pending invite
 // with the peer-name "Bob"; whoever redeems it is registered under "Bob" (the
@@ -67,6 +80,38 @@ application actor loads libraries
         // migrates blobs in this shape forward — see below.
         metadef legacy_message_t: ($sender_id -> global_id, $sender_name -> str, $text -> str, $date -> time).
 
+        // ---- local contact book wire shapes ---------------------------------
+        // Introduction credential, minted PER CONNECT ATTEMPT by the host's
+        // registrar packet (never stored in the book). It binds the joiner's
+        // identity AND address document to one target, with freshness + a nonce,
+        // so possession of book material alone authorizes nothing: only the
+        // registrar (whose key never leaves the host) can mint one, which is
+        // what makes "local" a cryptographic property rather than a convention.
+        metadef intro_t: (
+            $version       -> int,
+            $joiner_cid    -> global_id,
+            $joiner_ad_hash -> hash_code,
+            $target_cid    -> global_id,
+            $iat           -> time,
+            $nonce         -> global_id
+        ).
+        metadef signed_intro_t: ($i -> intro_t, $s -> crypto_signature).
+        // What the registrar signs for a contact-book entry (tamper-evidence for
+        // the host-side book file; verified by the SENDER in connect_local).
+        metadef book_entry_t: ($version -> int, $name -> str, $ad_hash -> hash_code).
+        // A not-yet-approved local introduction, with its bounded message queue.
+        metadef pending_msg_t: ($text -> str, $date -> time).
+        metadef pending_intro_t: ($name -> str, $ad -> address_document_types::t_address_document, $messages -> pending_msg_t[]).
+        metadef pending_view_t: ($name -> str, $queued -> int).
+
+        // Acceptance window for an introduction credential (seconds since mint;
+        // small negative slack for clock oddities) and the matching nonce-table
+        // retention horizon (window + slack, so a nonce outlives its credential).
+        intro_max_age_seconds is int = 300.
+        intro_max_skew_seconds is int = 30.
+        seen_nonce_cap is int = 1024.
+        pending_queue_cap is int = 50.
+
         // 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).
@@ -94,6 +139,20 @@ application actor loads libraries
         // every peer's keys in key_storage so encrypted channels survive the upgrade
         // with no re-handshake. Only peer PUBLIC keys travel here, never secrets.
         peer_ads is (global_id ->> address_document_types::t_address_document) = (,).
+        // The host registrar's address document (pinned once at identity
+        // creation / injected on upgrade) — its $identity $key_list is what
+        // introduction credentials are verified against. NIL means this identity
+        // accepts no local-book introductions at all.
+        registrar_ad is address_document_types::t_address_document+ = NIL.
+        // Whether a verified local introduction registers the joiner immediately
+        // (TRUE) or parks it in pending_introductions for explicit approval.
+        local_auto_accept is bool = TRUE.
+        // Replay guard for introduction credentials: nonce -> when it was seen.
+        // Lazily purged past the freshness horizon, hard-capped at seen_nonce_cap.
+        seen_nonces is (global_id ->> time) = (,).
+        // Verified-but-unapproved local introductions (when auto-accept is off),
+        // each with a bounded queue of messages awaiting approval.
+        pending_introductions is (global_id ->> pending_intro_t) = (,).
 
         // Signal the host to persist the packet. Only emitted at the end of a
         // complete procedure — intermediate states (e.g. channel handshake) are
@@ -114,6 +173,35 @@ application actor loads libraries
             abort "Unknown contact: " + ref when found == NIL.
             return found?.
         }
+
+        // Append a message to the inbox under a fresh id; returns the id.
+        fn deposit_message (sender_id: global_id, sender_name: str, text: str, msg_date: time) -> int
+        {
+            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,
+                $status      -> "unread"
+            ).
+            return mid.
+        }
+
+        // Resolve a pending introduction by joiner name or stringified container
+        // id; aborts when nothing matches.
+        fn resolve_pending (ref: str) -> global_id
+        {
+            found is global_id+ = NIL.
+            sc pending_introductions -- (cid -> p) ?? found == NIL && ((p $name) == ref || (_str cid) == ref)
+            {
+                found -> cid.
+            }
+            abort "No pending introduction matches: " + ref when found == NIL.
+            return found?.
+        }
     }
 
     // ---- user transactions --------------------------------------------------
@@ -394,6 +482,180 @@ application actor loads libraries
         ].
     }
 
+    // ---- local contact book ---------------------------------------------------
+    // The book itself lives HOST-SIDE (wrapper-local file, remote peers have no
+    // path to it) and stores only public address material — essentially a stored
+    // multi-use invite. It bypasses invite generation/delivery, NOT the key
+    // exchange: connecting still runs the normal encrypted_channel handshake.
+    // Authorization is per attempt: the host's registrar packet mints a fresh,
+    // short-lived, registrar-signed introduction credential for each connect, and
+    // the target verifies it against its pinned registrar keys. An external peer
+    // can never produce one, so the local boundary holds cryptographically.
+
+    trn readonly export_address_document _
+    {
+        return (_write address_document::get_my_address_document()).
+    }
+
+    trn pin_registrar _:($registrar_ad -> registrar_ad_blob: bin, $replace -> replace: bool+)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        ad = (_read_or_abort registrar_ad_blob) safe address_document_types::t_address_document.
+        if registrar_ad != NIL
+        {
+            // Idempotent re-pin of the same keys is a no-op; CHANGING the pinned
+            // keys is a deliberate act and must be requested explicitly, so no
+            // future internal-path code can substitute a registrar silently.
+            if (_value_id (registrar_ad? $identity $key_list)) == (_value_id (ad $identity $key_list))
+            {
+                return transaction::success [
+                    _return_data ($pinned -> TRUE, $changed -> FALSE)
+                ].
+            }
+            abort "A different registrar key list is already pinned; pass $replace -> TRUE to overwrite." when replace == NIL || replace? != TRUE.
+        }
+        registrar_ad -> ad.
+        return transaction::success [
+            _return_data ($pinned -> TRUE, $changed -> TRUE),
+            _save_state NIL
+        ].
+    }
+
+    trn set_local_policy _:($auto_accept -> auto_accept: bool)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+        local_auto_accept -> auto_accept.
+        return transaction::success [
+            _return_data ($auto_accept -> auto_accept),
+            _save_state NIL
+        ].
+    }
+
+    // Mint an introduction credential. Only meaningful on the host's REGISTRAR
+    // packet: targets verify the signature against their pinned registrar keys,
+    // so a credential minted by any other packet simply fails verification.
+    // Stateless — nothing to save. iat is stamped with transaction time so mint
+    // and verify use the same clock domain.
+    trn mint_introduction _:($joiner_ad -> joiner_ad_blob: bin, $target_ad -> target_ad_blob: bin)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        joiner_ad = (_read_or_abort joiner_ad_blob) safe address_document_types::t_address_document.
+        target_ad = (_read_or_abort target_ad_blob) safe address_document_types::t_address_document.
+        intro is intro_t = (
+            $version        -> 1,
+            $joiner_cid     -> joiner_ad $identity $container_id,
+            $joiner_ad_hash -> _value_id joiner_ad,
+            $target_cid     -> target_ad $identity $container_id,
+            $iat            -> (current_transaction_info::get_transaction_time())?,
+            $nonce          -> _new_id "a2adapt local introduction"
+        ).
+        signed is signed_intro_t = ($i -> intro, $s -> key_storage::default_sign (_value_id intro)).
+        return transaction::success [
+            _return_data ($intro -> (_write signed))
+        ].
+    }
+
+    // Sign a contact-book entry (registrar packet only, same caveat as above).
+    // Makes the host-side book file tamper-evident: senders re-derive this record
+    // from the entry they read and verify the signature before connecting.
+    trn sign_book_entry _:($name -> name: str, $ad -> ad_blob: bin)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        ad = (_read_or_abort ad_blob) safe address_document_types::t_address_document.
+        entry is book_entry_t = ($version -> 1, $name -> name, $ad_hash -> _value_id ad).
+        return transaction::success [
+            _return_data ($sig -> (_write (key_storage::default_sign (_value_id entry))))
+        ].
+    }
+
+    // Connect to a same-host peer found in the local contact book: verify the
+    // book entry's registrar signature, register the peer as a contact, then
+    // introduce myself over the encrypted channel — carrying the credential the
+    // host just minted for this attempt, plus (optionally) the first message so
+    // introduction + first delivery are one atomic transaction on the target
+    // (no introduce-vs-message ordering race).
+    trn connect_local _:($name -> name: str, $target_ad -> target_ad_blob: bin, $intro -> intro_blob: bin, $entry_sig -> entry_sig_blob: bin, $text -> text: str+)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+        abort "No registrar pinned — the local contact book is unavailable for this identity." when registrar_ad == NIL.
+
+        target_ad = (_read_or_abort target_ad_blob) safe address_document_types::t_address_document.
+        target_id = target_ad $identity $container_id.
+        abort "This contact-book entry is your own identity." when target_id == _get_container_id().
+
+        entry is book_entry_t = ($version -> 1, $name -> name, $ad_hash -> _value_id target_ad).
+        entry_sig = (_read_or_abort entry_sig_blob) safe crypto_signature.
+        abort "Contact-book entry failed registrar verification." when key_storage::check_signature_new_container (_value_id entry) entry_sig (registrar_ad? $identity $key_list) != TRUE.
+
+        contacts target_id -> ($name -> name, $container_id -> target_id).
+        peer_ads target_id -> target_ad.
+
+        my_self_name = my_name.
+        my_ad = address_document::get_my_address_document().
+        return encrypted_channel::execute_transaction target_id (fn (_) -> transaction::results::type {
+            return transaction::success [
+                encrypted_channel::send_encrypted_tx target_id (
+                    $name -> "::actor::local_introduce",
+                    $targ -> ($joiner_name -> my_self_name, $joiner_ad -> my_ad, $intro -> intro_blob, $text -> text)
+                ),
+                _return_data ($connected -> name, $container_id -> target_id),
+                _save_state NIL
+            ].
+        }).
+    }
+
+    trn approve_introduction _:($contact -> ref: str)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        pid = resolve_pending ref.
+        entry = (pending_introductions pid)?.
+        contacts pid -> ($name -> entry $name, $container_id -> pid).
+        peer_ads pid -> entry $ad.
+
+        queued = entry $messages.
+        flushed is int = 0.
+        sc queued -- ( -> m)
+        {
+            deposit_message pid (entry $name) (m $text) (m $date).
+            flushed -> flushed + 1.
+        }
+        delete pending_introductions pid.
+
+        return transaction::success [
+            _return_data ($approved -> entry $name, $container_id -> pid, $flushed -> flushed),
+            _save_state NIL
+        ].
+    }
+
+    trn reject_introduction _:($contact -> ref: str)
+    {
+        current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+
+        pid = resolve_pending ref.
+        entry = (pending_introductions pid)?.
+        dropped = _count (entry $messages)|.
+        delete pending_introductions pid.
+
+        return transaction::success [
+            _return_data ($rejected -> entry $name, $container_id -> pid, $dropped_messages -> dropped),
+            _save_state NIL
+        ].
+    }
+
+    trn readonly list_pending_introductions _
+    {
+        out is (global_id ->> pending_view_t) = (,).
+        sc pending_introductions -- (cid -> p)
+        {
+            out cid -> ($name -> p $name, $queued -> _count (p $messages)|).
+        }
+        return out.
+    }
+
     // ---- 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
@@ -406,12 +668,18 @@ application actor loads libraries
     trn readonly export_state _
     {
         return (
-            $my_name         -> my_name,
-            $contacts        -> contacts,
-            $pending_invites -> pending_invites,
-            $inbox           -> inbox,
-            $next_msg_seq    -> next_msg_seq,
-            $peer_ads        -> peer_ads
+            $my_name           -> my_name,
+            $contacts          -> contacts,
+            $pending_invites   -> pending_invites,
+            $inbox             -> inbox,
+            $next_msg_seq      -> next_msg_seq,
+            $peer_ads          -> peer_ads,
+            $registrar_ad      -> registrar_ad,
+            $local_auto_accept -> local_auto_accept,
+            // Nonces are exported so a restart does not reopen the replay window
+            // for still-fresh credentials; stale ones are purged lazily anyway.
+            $seen_nonces       -> seen_nonces,
+            $pending_introductions -> pending_introductions
         ).
     }
 
@@ -476,6 +744,25 @@ application actor loads libraries
             next_msg_seq -> (data $next_msg_seq) safe int.
         }
 
+        // Local-contact-book state arrived after the original schema — every
+        // field is optional in old blobs and defaults stay in place when absent.
+        if (data $registrar_ad) != NIL
+        {
+            registrar_ad -> (data $registrar_ad) safe address_document_types::t_address_document.
+        }
+        if (data $local_auto_accept) != NIL
+        {
+            local_auto_accept -> (data $local_auto_accept) safe bool.
+        }
+        if (data $seen_nonces) != NIL
+        {
+            seen_nonces -> (data $seen_nonces) safe (global_id ->> time).
+        }
+        if (data $pending_introductions) != NIL
+        {
+            pending_introductions -> (data $pending_introductions) safe (global_id ->> pending_intro_t).
+        }
+
         // Re-register every peer's keys so encrypted channels keep working after
         // the upgrade — no handshake needed (my own keys are unchanged, and the
         // peers' self-signed address documents re-authorize on this fresh packet).
@@ -483,6 +770,12 @@ application actor loads libraries
         {
             address_document::process_address_document ad TRUE.
         }
+        // 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)
+        {
+            address_document::process_address_document (p $ad) TRUE.
+        }
 
         return transaction::success [
             _return_data ($imported -> TRUE, $contacts -> _count contacts|, $peers -> _count peer_ads|),
@@ -499,15 +792,18 @@ application actor loads libraries
 
         sender_id = current_transaction_info::get_external_envelope_or_abort() $from.
 
-        // The name I assigned when I generated the invite wins; fall back to the
-        // joiner's self-name if this invite is unknown (shouldn't happen).
+        // Only an invite I generated (and have not yet consumed) authorizes a
+        // contact registration. Without this gate any invite blob would be a
+        // multi-use bearer credential: anyone who ever saw one could register
+        // themselves as my contact with a self-chosen name.
         assigned_name = pending_invites invite_id.
-        contact_name = (assigned_name == NIL ?? joiner_name ; assigned_name?).
+        abort "Unknown or already-redeemed invite." when assigned_name == NIL.
+        contact_name = assigned_name?.
 
         contacts sender_id -> ($name -> contact_name, $container_id -> sender_id).
         // Remember the joiner's address document for upgrade-time re-registration.
         peer_ads sender_id -> joiner_ad.
-        if pending_invites invite_id != NIL { delete pending_invites invite_id. }
+        delete pending_invites invite_id.
 
         return transaction::success [
             _notify_agent ($event -> $contact_accepted, $name -> contact_name, $container_id -> sender_id),
@@ -521,23 +817,30 @@ application actor loads libraries
         encrypted_channel::check_encrypted_or_abort().
 
         sender_id = current_transaction_info::get_external_envelope_or_abort() $from.
+        msg_date = (current_transaction_info::get_transaction_time())?.
         sender = contacts sender_id.
-        abort "Message from an unknown sender was rejected." when sender == NIL.
+
+        if sender == NIL
+        {
+            // A verified-but-unapproved local introduction may message me before
+            // approval: queue (bounded) inside its pending entry. Approval
+            // flushes the queue into the inbox in order; anything else from an
+            // unknown sender is rejected as before.
+            p = pending_introductions sender_id.
+            abort "Message from an unknown sender was rejected." when p == NIL.
+            entry = p?.
+            queued = entry $messages.
+            abort "Pending-introduction message queue is full; awaiting approval." when (_count queued|) >= pending_queue_cap.
+            queued (_count queued|) -> ($text -> text, $date -> msg_date).
+            pending_introductions sender_id -> ($name -> entry $name, $ad -> entry $ad, $messages -> queued).
+            return transaction::success [
+                _notify_agent ($event -> $pending_message, $sender_name -> entry $name, $queued -> _count queued|),
+                _save_state NIL
+            ].
+        }
 
         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,
-            $status      -> "unread"
-        ).
+        mid = deposit_message sender_id sender_name text msg_date.
 
         // The notification deliberately carries NO message body — only that a
         // message arrived, from whom, and its id. The body stays in the packet
@@ -547,4 +850,97 @@ application actor loads libraries
             _save_state NIL
         ].
     }
+
+    // A same-host peer connects via the local contact book. The credential must
+    // have been minted by THIS HOST's registrar for THIS sender and THIS target,
+    // recently, and never seen before — five checks that together make the book
+    // path unusable from outside the host:
+    //   1. registrar signature over the credential (pinned key list)
+    //   2. envelope $from == credential.joiner_cid   (no splicing someone
+    //      else's credential onto your own channel)
+    //   3. hash(joiner_ad) == credential.joiner_ad_hash (no AD substitution)
+    //   4. credential.target_cid == me               (no cross-target reuse)
+    //   5. freshness window + unseen nonce           (no replay)
+    // The encrypted channel itself authenticates that the sender controls its
+    // keys, so no extra challenge-response is needed.
+    trn local_introduce _:($joiner_name -> joiner_name: str, $joiner_ad -> joiner_ad: address_document_types::t_address_document, $intro -> intro_blob: bin, $text -> text: str+)
+    {
+        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.
+        abort "This identity does not accept local-contact-book introductions." when registrar_ad == NIL.
+
+        signed = (_read_or_abort intro_blob) safe signed_intro_t.
+        intro = signed $i.
+        abort "Unsupported introduction credential version." when (intro $version) != 1.
+        abort "Introduction credential was not signed by this host's registrar." when key_storage::check_signature_new_container (_value_id intro) (signed $s) (registrar_ad? $identity $key_list) != TRUE.
+        abort "Introduction credential was minted for a different sender." when (intro $joiner_cid) != sender_id.
+        abort "Introduction credential does not match the sender's address document." when (intro $joiner_ad_hash) != _value_id joiner_ad.
+        abort "Introduction credential targets a different identity." when (intro $target_cid) != _get_container_id().
+
+        now = (current_transaction_info::get_transaction_time())?.
+        age = _substract_seconds now (intro $iat).
+        abort "Introduction credential is outside its freshness window." when age > intro_max_age_seconds || age < (0 - intro_max_skew_seconds).
+
+        // Lazy nonce GC (drop everything past the retention horizon), then the
+        // replay check, then a hard cap so a misbehaving local peer cannot bloat
+        // packet state inside the window.
+        horizon = intro_max_age_seconds + intro_max_skew_seconds.
+        fresh_nonces is (global_id ->> time) = (,).
+        sc seen_nonces -- (n -> t)
+        {
+            if (_substract_seconds now t) <= horizon { fresh_nonces n -> t. }
+        }
+        seen_nonces -> fresh_nonces.
+        abort "Replayed introduction credential." when seen_nonces (intro $nonce) != NIL.
+        abort "Too many concurrent introductions; try again shortly." when (_count seen_nonces|) >= seen_nonce_cap.
+        seen_nonces (intro $nonce) -> now.
+
+        existing = contacts sender_id.
+        if existing != NIL
+        {
+            // Already a contact (idempotent re-introduction): keep my assigned
+            // name, refresh the stored address document, deliver any payload.
+            peer_ads sender_id -> joiner_ad.
+            if text != NIL
+            {
+                mid = deposit_message sender_id (existing? $name) text? now.
+                return transaction::success [
+                    _notify_agent ($event -> $message_received, $sender_name -> existing? $name, $msg_id -> mid, $date -> now),
+                    _save_state NIL
+                ].
+            }
+            return transaction::success [ _save_state NIL ].
+        }
+
+        if local_auto_accept
+        {
+            contacts sender_id -> ($name -> joiner_name, $container_id -> sender_id).
+            peer_ads sender_id -> joiner_ad.
+            if text != NIL
+            {
+                mid = deposit_message sender_id joiner_name text? now.
+                return transaction::success [
+                    _notify_agent ($event -> $local_contact_added, $name -> joiner_name, $container_id -> sender_id),
+                    _notify_agent ($event -> $message_received, $sender_name -> joiner_name, $msg_id -> mid, $date -> now),
+                    _save_state NIL
+                ].
+            }
+            return transaction::success [
+                _notify_agent ($event -> $local_contact_added, $name -> joiner_name, $container_id -> sender_id),
+                _save_state NIL
+            ].
+        }
+
+        // Pending-approval policy: park the introduction (with its optional
+        // first message) until approve_introduction / reject_introduction.
+        queued is pending_msg_t[] = [].
+        if text != NIL { queued 0 -> ($text -> text?, $date -> now). }
+        pending_introductions sender_id -> ($name -> joiner_name, $ad -> joiner_ad, $messages -> queued).
+        return transaction::success [
+            _notify_agent ($event -> $local_contact_request, $name -> joiner_name, $container_id -> sender_id, $queued -> _count queued|),
+            _save_state NIL
+        ].
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adapt-toolkit/a2adapt",
-  "version": "0.8.0",
+  "version": "0.9.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",
@@ -49,8 +49,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@adapt-toolkit/sdk": "^0.2.4",
-    "@adapt-toolkit/sdk-native": "^0.2.3"
+    "@adapt-toolkit/sdk": "^0.4.0",
+    "@adapt-toolkit/sdk-native": "^0.4.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",