agents-can-communicate 0.2.0 → 0.3.0

package/node_modules/@agents-can-communicate/installer/src/native-activation.mjs

@@ -0,0 +1,161 @@
+import { execFile } from "node:child_process";
+import { access, constants } from "node:fs/promises";
+import path from "node:path";
+
+import { defaultBootstrap } from "@agents-can-communicate/adapter-sdk";
+
+import { installShellBootstrap, planShellBootstrap, uninstallShellBootstrap }
+  from "./shell-bootstrap.mjs";
+
+// The installer's side of a native activation: which owned mechanisms an
+// eligible adapter asked for, how they are applied in a fixed order, what is
+// recorded so uninstall removes only ACC's bytes, and how a recorded
+// activation is taken back. Adapter-owned native config is written by the
+// adapter's own install; a vendor service is started only here, only during
+// apply, and only when it did not already exist.
+
+export const LIVE_POLICIES = Object.freeze(["off", "actionable", "all"]);
+const MECHANISM_ORDER = ["native-config", "native-service", "shell-bootstrap"];
+const SERVICE_TIMEOUT_MS = 15_000;
+
+export const livePolicyOf = install => (LIVE_POLICIES.includes(install?.nativeActivation?.livePolicy)
+  ? install.nativeActivation.livePolicy : "off");
+
+export const shellOf = env => {
+  const shell = env?.SHELL;
+  return typeof shell === "string" && shell !== "" ? path.basename(shell) : null;
+};
+export const shimDirFor = stateRoot => path.join(stateRoot, "bin");
+// `.zshrc`, deliberately, and that makes the shim interactive-only: zsh reads
+// this file for interactive shells and not for `zsh -lc` or a script. An
+// interactive launch is where a client session comes from, and putting the PATH
+// entry somewhere every shell reads would put ACC in front of a vendor command
+// in scripts and CI that never asked for it. Worth knowing when checking an
+// install: a non-interactive shell resolving the vendor binary directly is this
+// choice working, not a broken bootstrap.
+export const rcFileFor = (home, shell) => (shell === "zsh" && typeof home === "string"
+  ? path.join(home, ".zshrc") : null);
+
+// The vendor executable a shim will exec: the first executable on PATH that is
+// not ACC's own shim directory, so a shim never resolves itself.
+export async function resolveExecutable(command, { pathEnv = "", exclude = [] } = {}) {
+  const excluded = exclude.filter(Boolean).map(directory => path.resolve(directory));
+  for (const directory of String(pathEnv).split(path.delimiter).filter(Boolean)) {
+    if (excluded.includes(path.resolve(directory))) continue;
+    const candidate = path.join(directory, command);
+    try {
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // not here; keep walking PATH
+    }
+  }
+  return null;
+}
+
+const defaultExec = (executable, args) => new Promise((resolve, reject) => {
+  execFile(executable, args, { timeout: SERVICE_TIMEOUT_MS, windowsHide: true },
+    error => (error === null ? resolve() : reject(error)));
+});
+
+const ordered = mechanisms => [...mechanisms].sort((left, right) =>
+  MECHANISM_ORDER.indexOf(left.kind) - MECHANISM_ORDER.indexOf(right.kind));
+
+const renderCommand = command => [command.executable, ...command.args].join(" ");
+
+/** What an activation would touch, in the operator's words. */
+export function describeActivation(activation) {
+  const lines = [];
+  for (const mechanism of ordered(activation.mechanisms)) {
+    if (mechanism.kind === "shell-bootstrap") {
+      lines.push(`create shim ${path.join(activation.shimDir, mechanism.command)} for `
+        + `${mechanism.command} (${activation.livePolicy} live delivery)`);
+      lines.push(`add a PATH block to ${activation.rcFile}`);
+    } else if (mechanism.kind === "native-config") {
+      lines.push(`write native config ${mechanism.artifactIds.join(", ")}`);
+    } else if (mechanism.preExisting) {
+      lines.push(`use the existing ${mechanism.serviceId} service`);
+    } else if (mechanism.applyCommand !== null) {
+      lines.push(`start the ${mechanism.serviceId} service: ${renderCommand(mechanism.applyCommand)}`);
+    }
+  }
+  return lines;
+}
+
+export function describeDeactivation(nativeActivation) {
+  const lines = [];
+  for (const mechanism of nativeActivation?.mechanisms ?? []) {
+    if (mechanism.kind === "shell-bootstrap") {
+      for (const file of mechanism.ownedFiles) lines.push(`remove shim ${file.path}`);
+      lines.push(`remove the PATH block from ${mechanism.rcFile.path} once no ACC shim remains`);
+    } else if (mechanism.kind === "native-service") {
+      lines.push(mechanism.createdByAcc && mechanism.teardownCommand !== null
+        ? `stop the ${mechanism.serviceId} service: ${renderCommand(mechanism.teardownCommand)}`
+        : `leave the ${mechanism.serviceId} service in place (${mechanism.createdByAcc
+          ? "no vendor teardown exists" : "it existed before ACC"})`);
+    }
+  }
+  return lines;
+}
+
+export async function applyNativeActivation({ adapter, activation, dataHome,
+  node = process.execPath, bootstrap = defaultBootstrap(), exec = defaultExec }) {
+  const record = { livePolicy: activation.livePolicy,
+    protocolContract: activation.protocolContract, mechanisms: [] };
+  let shell = null;
+  try {
+    for (const mechanism of ordered(activation.mechanisms)) {
+      if (mechanism.kind === "native-config") {
+        record.mechanisms.push({ kind: mechanism.kind, artifactIds: [...mechanism.artifactIds] });
+      } else if (mechanism.kind === "native-service") {
+        let createdByAcc = false;
+        if (!mechanism.preExisting && mechanism.applyCommand !== null) {
+          await exec(mechanism.applyCommand.executable, mechanism.applyCommand.args);
+          createdByAcc = true;
+        }
+        record.mechanisms.push({ kind: mechanism.kind, serviceId: mechanism.serviceId,
+          createdByAcc, teardownCommand: mechanism.teardownCommand });
+      } else {
+        const plan = planShellBootstrap({ shell: activation.shell, rcFile: activation.rcFile,
+          shimDir: activation.shimDir, runtime: { node, bootstrap, dataHome },
+          entries: [{ adapterId: adapter.id, command: mechanism.command,
+            realExecutable: mechanism.realExecutable, prefixArgs: mechanism.prefixArgs,
+            livePolicy: activation.livePolicy }] });
+        const result = await installShellBootstrap({ plan });
+        if (!result.ok) throw new Error(`shell bootstrap refused: ${result.reasonCode}`);
+        shell = result;
+        record.mechanisms.push({ kind: mechanism.kind, shimDir: activation.shimDir,
+          ownedFiles: result.shims.map(shim => ({ path: shim.path, sha256: shim.sha256 })),
+          rcFile: result.rcFile });
+      }
+    }
+    return { nativeActivation: record, appendedRcBlock: shell?.rcFile.appended === true };
+  } catch (error) {
+    // Only bytes this operation wrote are taken back; a pre-existing service
+    // or a user's own file is never touched on the way out.
+    if (shell !== null) {
+      await uninstallShellBootstrap({ ownership: { shims: shell.shims, shimDir: activation.shimDir,
+        rcFile: shell.rcFile } }).catch(() => null);
+    }
+    throw error;
+  }
+}
+
+export async function deactivateNative({ nativeActivation, exec = defaultExec }) {
+  const report = { shell: null, services: [] };
+  for (const mechanism of nativeActivation?.mechanisms ?? []) {
+    if (mechanism.kind === "shell-bootstrap") {
+      report.shell = await uninstallShellBootstrap({ ownership: { shims: mechanism.ownedFiles,
+        shimDir: mechanism.shimDir, rcFile: mechanism.rcFile } });
+    } else if (mechanism.kind === "native-service") {
+      if (mechanism.createdByAcc && mechanism.teardownCommand !== null) {
+        await exec(mechanism.teardownCommand.executable, mechanism.teardownCommand.args);
+        report.services.push({ serviceId: mechanism.serviceId, outcome: "stopped" });
+      } else {
+        report.services.push({ serviceId: mechanism.serviceId,
+          outcome: mechanism.createdByAcc ? "retained_no_teardown" : "retained_pre_existing" });
+      }
+    }
+  }
+  return report;
+}

package/node_modules/@agents-can-communicate/installer/src/ownership.mjs

@@ -110,7 +110,7 @@ async function saveOwnership({ dataHome, record }) {
  * runtime, and leaves the bundle inside the client exactly where it was.
  */
 export async function recordInstall({ dataHome, adapterId, version, accVersion = null,
-  artifacts, createdDirectories = [] }) {
+  artifacts, createdDirectories = [], nativeActivation = null }) {
   const stamped = await Promise.all(artifacts.map(async artifact => ({
     path: artifact.path,
     kind: artifact.kind ?? "file",
@@ -127,7 +127,11 @@ export async function recordInstall({ dataHome, adapterId, version, accVersion =
   await saveOwnership({ dataHome, record: { schemaVersion: SCHEMA_VERSION,
     installs: [...record.installs.filter(install => install.adapterId !== adapterId),
       { adapterId, version, accVersion, artifacts: stamped,
-        ...(directories.length === 0 ? {} : { createdDirectories: directories }) }] } });
+        ...(directories.length === 0 ? {} : { createdDirectories: directories }),
+        // Present only for a consented native activation. A record without it
+        // - every 0.2 install - reads as live policy off and is never rewritten
+        // merely to add the field.
+        ...(nativeActivation === null ? {} : { nativeActivation }) }] } });
 }
 
 const installFor = (record, adapterId) =>

package/node_modules/@agents-can-communicate/installer/src/plan.mjs

@@ -1,5 +1,8 @@
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
+import { LIVE_POLICIES, describeActivation, describeDeactivation, rcFileFor, shimDirFor }
+  from "./native-activation.mjs";
+
 /**
  * Turn a detection report into exactly what would happen.
  *
@@ -9,14 +12,26 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
  */
 export function planInstallation({ adapters, detected, context, action = "install",
   recorded = [], accVersion = null, allowDowngrade = false, requested = [],
-  delivery = "off" }) {
+  deliveryByAdapter = {} }) {
   if (!["install", "uninstall"].includes(action)) {
     throw new AccError(EXIT.USAGE, `unknown installation action: ${action}`, { action });
   }
-  if (!["off", "actionable", "all"].includes(delivery)) {
-    throw new AccError(EXIT.USAGE, `unknown delivery policy: ${delivery}`, { delivery });
-  }
   const byId = new Map(adapters.map(adapter => [adapter.id, adapter]));
+  // One explicit answer per selected client. A missing entry is off; a policy
+  // for a client that is not part of this run is a mistake to say out loud,
+  // not something to store for later.
+  if (deliveryByAdapter === null || typeof deliveryByAdapter !== "object") {
+    throw new AccError(EXIT.USAGE, "deliveryByAdapter must map adapter ids to policies");
+  }
+  for (const [adapterId, policy] of Object.entries(deliveryByAdapter)) {
+    if (!byId.has(adapterId)) {
+      throw new AccError(EXIT.USAGE,
+        `delivery policy names ${adapterId}, which is not part of this install`, { adapterId });
+    }
+    if (!LIVE_POLICIES.includes(policy)) {
+      throw new AccError(EXIT.USAGE, `unknown delivery policy: ${policy}`, { adapterId, policy });
+    }
+  }
   // What ACC recorded writing, by client. For an uninstall this is the
   // authority rather than detection: the record is the only account of what was
   // written, and a client's configuration directory outlives the client.
@@ -86,15 +101,31 @@ export function planInstallation({ adapters, detected, context, action = "instal
     // From the record when the client is gone, because that is what was written
     // and so what will be removed. Asking the adapter instead would describe an
     // install for a machine this one no longer is.
-    const liveDeliverySupported = entry.capabilities?.delivery?.livePush === true;
+    const delivery = deliveryByAdapter[entry.adapterId] ?? "off";
+    const native = entry.nativeDelivery ?? null;
+    const liveDeliverySupported = native?.state === "eligible"
+      && native.activationPlan?.eligible === true;
     const effectiveLivePolicy = liveDeliverySupported ? delivery : "off";
     const deliveryDiagnostic = action === "install" && delivery !== "off"
       && !liveDeliverySupported
       ? entry.deliveryDiagnostic ?? adapter.deliveryFallback?.diagnostic
-        ?? `${adapter.displayName ?? adapter.id} has no certified live delivery for this client; durable fallback remains active`
+        ?? `${adapter.displayName ?? adapter.id} cannot receive native delivery `
+          + `(${native?.reasonCode ?? "native_delivery_unsupported"}); durable fallback remains active`
       : null;
     const installContext = { ...context, requestedLivePolicy: delivery,
       livePolicy: effectiveLivePolicy };
+    // A consented activation that this run keeps, activates, or takes back.
+    // Only an explicit off or an uninstall removes one; an absent record never
+    // creates one.
+    const previous = recordedById.get(entry.adapterId)?.nativeActivation ?? null;
+    const nativeActivation = action === "install" && effectiveLivePolicy !== "off"
+      ? { livePolicy: effectiveLivePolicy, protocolContract: native.eligibility.protocolContract,
+        shell: context?.shell ?? null, rcFile: rcFileFor(context?.home, context?.shell),
+        shimDir: typeof context?.stateRoot === "string" ? shimDirFor(context.stateRoot) : null,
+        mechanisms: native.activationPlan.mechanisms }
+      : null;
+    const deactivation = previous !== null
+      && (action === "uninstall" || effectiveLivePolicy === "off") ? previous : null;
     const artifacts = (record?.artifacts ?? adapter.planInstall(installContext))
       .map(artifact => ({ path: artifact.path, kind: artifact.kind ?? "file" }))
       .sort((a, b) => a.path.localeCompare(b.path));
@@ -112,6 +143,8 @@ export function planInstallation({ adapters, detected, context, action = "instal
       livePolicy: delivery,
       effectiveLivePolicy,
       ...(deliveryDiagnostic === null ? {} : { deliveryDiagnostic }),
+      ...(nativeActivation === null ? {} : { nativeActivation }),
+      ...(deactivation === null ? {} : { deactivation }),
       artifacts,
       // Said in the operator's terms, not in paths: which files ACC creates
       // outright and which belong to the user and are only edited.
@@ -123,6 +156,8 @@ export function planInstallation({ adapters, detected, context, action = "instal
           .map(a => `${action === "install" ? "create" : "remove"} ${a.path}`),
         ...artifacts.filter(a => a.kind === "merge")
           .map(a => `${action === "install" ? "add ACC entries to" : "remove ACC entries from"} ${a.path}`),
+        ...(nativeActivation === null ? [] : describeActivation(nativeActivation)),
+        ...(deactivation === null ? [] : describeDeactivation(deactivation)),
       ],
     });
   }

package/node_modules/@agents-can-communicate/installer/src/shell-bootstrap.mjs

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, readdir, readFile, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
+
+// The reversible shell half of native delivery: one marked PATH block in the
+// user's zsh rc and one per-command shim in an ACC-owned directory. The shim
+// keeps the user's command name, runs the bounded bootstrap check, and then
+// replaces itself with the real vendor executable through `exec`; ACC is never
+// the parent of a model session. Every byte ACC writes is recorded with its
+// hash so uninstall removes only what is still ACC's and refuses a block or
+// shim someone has edited.
+
+export const BLOCK_BEGIN = "# >>> agents-can-communicate native delivery >>>";
+export const BLOCK_END = "# <<< agents-can-communicate native delivery <<<";
+export const SHIM_MARKER = "# agents-can-communicate native delivery shim";
+export const SUPPORTED_SHELLS = Object.freeze(["zsh"]);
+export const SHIM_POLICIES = Object.freeze(["actionable", "all"]);
+const COMMAND_NAME = /^[a-z][a-z0-9_.-]*$/;
+
+const usage = (message, details = {}) => { throw new AccError(EXIT.USAGE, message, details); };
+const sha256 = text => createHash("sha256").update(text).digest("hex");
+// Single-quoted POSIX literal: the only escaping is the quote itself, so no
+// byte of a path or argument is ever interpreted by the shell.
+export const shellLiteral = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+const isAbsolute = value => typeof value === "string" && path.isAbsolute(value);
+const inside = (root, candidate) => {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+export function renderPathBlock(shimDir) {
+  return `${BLOCK_BEGIN}\nexport PATH=${shellLiteral(shimDir)}:"$PATH"\n${BLOCK_END}\n`;
+}
+
+export function validateShimEntry(entry) {
+  if (entry === null || typeof entry !== "object") usage("a shim entry must be an object");
+  for (const key of Object.keys(entry)) {
+    if (!["adapterId", "command", "realExecutable", "prefixArgs", "livePolicy"].includes(key)) {
+      usage(`unknown shim entry field ${key}`, { key });
+    }
+  }
+  assertPortableId(entry.adapterId, "shim adapter id");
+  if (typeof entry.command !== "string" || !COMMAND_NAME.test(entry.command)) {
+    usage("a shim command must be a bare command name", { command: entry.command });
+  }
+  if (!isAbsolute(entry.realExecutable)) usage("a shim realExecutable must be an absolute path");
+  if (!Array.isArray(entry.prefixArgs) || entry.prefixArgs.some(arg => typeof arg !== "string"
+    || arg === "" || /[\0\n]/.test(arg))) {
+    usage("shim prefixArgs must be non-empty argument strings without NUL or newline");
+  }
+  if (!SHIM_POLICIES.includes(entry.livePolicy)) {
+    usage("a shim livePolicy must be actionable or all; off means no shim", { livePolicy: entry.livePolicy });
+  }
+  return Object.freeze({ ...entry, prefixArgs: Object.freeze([...entry.prefixArgs]) });
+}
+
+export function renderCommandShim({ node, bootstrap, dataHome, entry }) {
+  const shim = validateShimEntry(entry);
+  for (const [name, value] of Object.entries({ node, bootstrap, dataHome })) {
+    if (!isAbsolute(value)) usage(`shim ${name} must be an absolute path`, { [name]: value });
+  }
+  const real = shellLiteral(shim.realExecutable);
+  const check = [node, bootstrap, "--adapter", shim.adapterId, "--real-executable",
+    shim.realExecutable, "--data-home", dataHome].map(shellLiteral).join(" ");
+  const prefix = shim.prefixArgs.map(shellLiteral).join(" ");
+  return [
+    "#!/bin/sh",
+    `${SHIM_MARKER} for ${shellLiteral(shim.command)}. Generated; do not edit.`,
+    "# ACC_BYPASS=1 runs the vendor command untouched. A failed or missing check",
+    "# does the same: the vendor command is never blocked on ACC.",
+    'if [ "${ACC_BYPASS-}" = "1" ]; then',
+    "  unset ACC_NATIVE_DELIVERY_POLICY",
+    `  exec ${real} "$@"`,
+    "fi",
+    `if ${check} </dev/null >/dev/null 2>&1; then`,
+    `  ACC_NATIVE_DELIVERY_POLICY=${shellLiteral(shim.livePolicy)}`,
+    "  export ACC_NATIVE_DELIVERY_POLICY",
+    `  exec ${real}${prefix === "" ? "" : ` ${prefix}`} "$@"`,
+    "fi",
+    "unset ACC_NATIVE_DELIVERY_POLICY",
+    `exec ${real} "$@"`,
+    "",
+  ].join("\n");
+}
+
+export function planShellBootstrap({ shell, rcFile, shimDir, entries = [], runtime = null }) {
+  if (!SUPPORTED_SHELLS.includes(shell)) {
+    return Object.freeze({ eligible: false, reasonCode: "unsupported_shell", shell: shell ?? null,
+      rcFile: null, shimDir: null, block: null, shims: Object.freeze([]), runtime: null });
+  }
+  if (!isAbsolute(rcFile) || !isAbsolute(shimDir)) usage("rcFile and shimDir must be absolute");
+  const validated = entries.map(validateShimEntry);
+  const commands = new Set();
+  for (const entry of validated) {
+    if (commands.has(entry.command)) usage(`duplicate shim command ${entry.command}`);
+    commands.add(entry.command);
+    // A shim that resolved to itself would loop forever; the real executable
+    // is resolved before the shim directory is ever on PATH.
+    if (inside(shimDir, entry.realExecutable)) {
+      usage("a shim realExecutable cannot live inside the shim directory",
+        { realExecutable: entry.realExecutable });
+    }
+  }
+  return Object.freeze({ eligible: true, reasonCode: null, shell, rcFile, shimDir,
+    block: renderPathBlock(shimDir), runtime,
+    shims: Object.freeze(validated.map(entry => Object.freeze({
+      path: path.join(shimDir, entry.command), entry }))) });
+}
+
+const defaultIo = Object.freeze({ readFile, writeFile, mkdir, chmod, rename, rm, rmdir, readdir });
+
+async function readText(io, file) {
+  try {
+    return await io.readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function writeAtomic(io, file, content, mode) {
+  const temporary = `${file}.${process.pid}.tmp`;
+  await io.writeFile(temporary, content, { mode });
+  await io.rename(temporary, file);
+  await io.chmod(file, mode);
+}
+
+// The block's exact span inside the rc text, or null. The block is matched by
+// its two sentinel lines so a user's other lines are never touched.
+export function locateBlock(text) {
+  if (typeof text !== "string") return null;
+  const begin = text.indexOf(BLOCK_BEGIN);
+  if (begin === -1 || (begin > 0 && text[begin - 1] !== "\n")) return null;
+  const endLine = text.indexOf(BLOCK_END, begin);
+  if (endLine === -1) return null;
+  const end = text.indexOf("\n", endLine);
+  return { start: begin, end: end === -1 ? text.length : end + 1 };
+}
+
+export async function installShellBootstrap({ plan, io = defaultIo }) {
+  if (!plan?.eligible) return { ok: false, reasonCode: plan?.reasonCode ?? "unsupported_shell" };
+  const { node, bootstrap, dataHome } = plan.runtime ?? {};
+  const current = await readText(io, plan.rcFile);
+  const span = locateBlock(current);
+  const existing = span === null ? null : current.slice(span.start, span.end);
+  if (existing !== null && existing !== plan.block) {
+    return { ok: false, reasonCode: "rc_block_modified", rcFile: plan.rcFile };
+  }
+  await io.mkdir(plan.shimDir, { recursive: true, mode: 0o700 });
+  await io.chmod(plan.shimDir, 0o700);
+  const shims = [];
+  for (const shim of plan.shims) {
+    const content = renderCommandShim({ node, bootstrap, dataHome, entry: shim.entry });
+    await writeAtomic(io, shim.path, content, 0o700);
+    shims.push({ path: shim.path, command: shim.entry.command, sha256: sha256(content) });
+  }
+  let appended = false;
+  if (existing === null) {
+    const base = current ?? "";
+    const separator = base === "" || base.endsWith("\n") ? "" : "\n";
+    await writeAtomic(io, plan.rcFile, `${base}${separator}${plan.block}`, 0o600);
+    appended = true;
+  }
+  return { ok: true, reasonCode: null, shell: plan.shell, shimDir: plan.shimDir,
+    rcFile: { path: plan.rcFile, blockSha256: sha256(plan.block), appended },
+    shims };
+}
+
+export async function uninstallShellBootstrap({ ownership, io = defaultIo }) {
+  const result = { ok: true, reasonCode: null, removedShims: [], keptShims: [],
+    missingShims: [], rcBlock: "absent" };
+  for (const shim of ownership?.shims ?? []) {
+    const content = await readText(io, shim.path);
+    if (content === null) { result.missingShims.push(shim.path); continue; }
+    if (sha256(content) !== shim.sha256) { result.keptShims.push(shim.path); continue; }
+    await io.rm(shim.path, { force: true });
+    result.removedShims.push(shim.path);
+  }
+  const shimDir = ownership?.shimDir;
+  let remaining = [];
+  if (typeof shimDir === "string") {
+    const names = await io.readdir(shimDir).catch(() => []);
+    for (const name of names) {
+      const content = await readText(io, path.join(shimDir, name));
+      if (content !== null && content.includes(SHIM_MARKER)) remaining.push(name);
+    }
+  }
+  const rcFile = ownership?.rcFile;
+  const text = typeof rcFile?.path === "string" ? await readText(io, rcFile.path) : null;
+  const span = locateBlock(text);
+  if (span !== null) {
+    const block = text.slice(span.start, span.end);
+    if (sha256(block) !== rcFile.blockSha256) {
+      result.rcBlock = "modified";
+      result.ok = false;
+      result.reasonCode = "rc_block_modified";
+    } else if (remaining.length > 0) {
+      result.rcBlock = "kept";
+    } else {
+      await writeAtomic(io, rcFile.path, text.slice(0, span.start) + text.slice(span.end), 0o600);
+      result.rcBlock = "removed";
+    }
+  }
+  if (typeof shimDir === "string" && remaining.length === 0 && result.keptShims.length === 0) {
+    await io.rmdir(shimDir).catch(() => null);
+  }
+  return result;
+}

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/src/fields.mjs

@@ -74,6 +74,23 @@ export const listOf = inner => (value, field) => {
 export const nullable = inner => (value, field) =>
   (value === null ? null : inner(value, field));
 
+/**
+ * A field that may be absent entirely.
+ *
+ * For a fact that either happened or did not, absence is the honest encoding of
+ * "not yet" - and it is what a record written before the field existed already
+ * says. Every record carries a schemaVersion, but adding a required field to a
+ * kind that outlives an upgrade turns a stored record into an unreadable one:
+ * measured, one binding written by the previous build made `acc status` fail
+ * outright with "deliveryBinding requires retiredAt". A coordination tool must
+ * not refuse to read its own store because it was upgraded.
+ */
+export const optional = inner => {
+  const check = (value, field) => (value === undefined ? undefined : inner(value, field));
+  check.optional = true;
+  return check;
+};
+
 export const positiveInteger = (value, field) => {
   if (!Number.isSafeInteger(value) || value <= 0) {
     invalid(field, "must be a positive integer", value);

package/node_modules/@agents-can-communicate/protocol/src/schema.mjs

@@ -1,6 +1,6 @@
 import { assertMessageSemantics, MESSAGE_KINDS, OBLIGATIONS } from "./conversations.mjs";
 import { AccError, EXIT } from "./errors.mjs";
-import { id, invalid, listOf, nullable, oneOf, plainObject, positiveInteger,
+import { id, invalid, listOf, nullable, oneOf, optional, plainObject, positiveInteger,
   resourceUri, sequence, text, timestamp } from "./fields.mjs";
 
 export const SCHEMA_VERSION = 3;
@@ -64,6 +64,16 @@ const EVENT_TYPES = Object.freeze([
 ]);
 
 const eventType = oneOf(...EVENT_TYPES);
+
+// nextTurn is the durable hook projection; the other four are what a native
+// transport proved for one session generation. A mode listed twice would let a
+// reader count capabilities it does not have.
+export const DELIVERY_MODES = Object.freeze(["nextTurn", "livePush", "idleWake", "busyQueue",
+  "replyRoute"]);
+const uniqueListOf = check => (value, field) => {
+  listOf(check)(value, field);
+  if (new Set(value).size !== value.length) invalid(field, "must not repeat entries", value);
+};
 const receiptState = oneOf("queued", "offered", "retrieved", "acknowledged");
 
 const DURABLE_RECORDS = Object.freeze({
@@ -104,9 +114,13 @@ const DURABLE_RECORDS = Object.freeze({
 const RECORDS = Object.freeze({
   ...DURABLE_RECORDS,
   deliveryBinding: { sessionId: id, generation: id, adapterId: id, clientVersion: line,
-    availableModes: listOf(oneOf("nextTurn", "livePush", "replyRoute")),
+    availableModes: uniqueListOf(oneOf(...DELIVERY_MODES)),
     livePolicy: oneOf("off", "actionable", "all"), opaqueEndpointRef: prose,
-    leaseUntil: timestamp },
+    // The lease says how long the endpoint's owner has vouched for it; the
+    // retirement says the session gave it up. They were once the same field -
+    // clearing expired the lease - which made a renewal by a channel that had
+    // not yet noticed indistinguishable from a legitimate extension.
+    leaseUntil: timestamp, retiredAt: optional(nullable(timestamp)) },
 });
 
 export const RECORD_KINDS = Object.freeze(Object.keys(DURABLE_RECORDS));
@@ -128,6 +142,7 @@ export function validateRecord(kind, value) {
   }
   for (const [field, check] of Object.entries(fields)) {
     if (!Object.hasOwn(value, field)) {
+      if (check.optional === true) continue;
       throw new AccError(EXIT.DATA, `${kind} requires ${field}`, { kind, field });
     }
     check(value[field], field);

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [
@@ -54,6 +54,7 @@
     "docs/DESIGN_DECISIONS.md",
     "docs/GETTING_STARTED.md",
     "docs/GLOSSARY.md",
+    "docs/HOW_IT_WORKS.md",
     "docs/MCP.md",
     "docs/PROTOCOL.md",
     "docs/RELEASING.md",