agents-can-communicate 0.3.0 → 0.4.0

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

@@ -6,6 +6,7 @@ import { defaultBootstrap } from "@agents-can-communicate/adapter-sdk";
 
 import { installShellBootstrap, planShellBootstrap, uninstallShellBootstrap }
   from "./shell-bootstrap.mjs";
+import { LIVE_POLICIES, livePolicyOf } from "./live-policy.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
@@ -14,13 +15,10 @@ import { installShellBootstrap, planShellBootstrap, uninstallShellBootstrap }
 // 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"]);
+export { LIVE_POLICIES, livePolicyOf };
 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;
@@ -124,7 +122,7 @@ export async function applyNativeActivation({ adapter, activation, dataHome,
         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,
+        record.mechanisms.push({ kind: mechanism.kind, command: mechanism.command, shimDir: activation.shimDir,
           ownedFiles: result.shims.map(shim => ({ path: shim.path, sha256: shim.sha256 })),
           rcFile: result.rcFile });
       }
@@ -141,12 +139,28 @@ export async function applyNativeActivation({ adapter, activation, dataHome,
   }
 }
 
+// Compare planned mechanisms with the deletion authority saved by older installs.
+export function planActivationRetirements({ previous, desired }) {
+  const wanted = desired?.mechanisms ?? [];
+  const matches = (old, next) => old.kind === next.kind && (old.kind === "native-service"
+    ? old.serviceId === next.serviceId : old.kind === "native-config"
+      ? JSON.stringify([...old.artifactIds].sort()) === JSON.stringify([...next.artifactIds].sort())
+      : typeof old.command === "string" ? old.command === next.command
+        : old.ownedFiles?.length > 0
+          && old.ownedFiles.every(file => path.basename(file.path) === next.command));
+  return (previous?.mechanisms ?? []).filter(old => !wanted.some(next => matches(old, next)));
+}
+
 export async function deactivateNative({ nativeActivation, exec = defaultExec }) {
-  const report = { shell: null, services: [] };
+  const report = { shell: null, services: [], retainedMechanisms: [] };
   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 } });
+      if (report.shell.keptShims.length > 0 || report.shell.rcBlock === "modified") {
+        report.retainedMechanisms.push({ ...mechanism,
+          ownedFiles: mechanism.ownedFiles.filter(file => report.shell.keptShims.includes(file.path)) });
+      }
     } else if (mechanism.kind === "native-service") {
       if (mechanism.createdByAcc && mechanism.teardownCommand !== null) {
         await exec(mechanism.teardownCommand.executable, mechanism.teardownCommand.args);

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 = [], nativeActivation = null }) {
+  artifacts, createdDirectories = [], deliveryPolicy, nativeActivation = null }) {
   const stamped = await Promise.all(artifacts.map(async artifact => ({
     path: artifact.path,
     kind: artifact.kind ?? "file",
@@ -128,6 +128,7 @@ export async function recordInstall({ dataHome, adapterId, version, accVersion =
     installs: [...record.installs.filter(install => install.adapterId !== adapterId),
       { adapterId, version, accVersion, artifacts: stamped,
         ...(directories.length === 0 ? {} : { createdDirectories: directories }),
+        ...(deliveryPolicy === undefined ? {} : { deliveryPolicy }),
         // 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.
@@ -221,7 +222,10 @@ export async function verifyOwned({ dataHome, adapterId }) {
   const install = installFor(await loadOwnership({ dataHome }), adapterId);
   const result = { adapterId, present: install !== null, modified: [], missing: [],
     intact: [], delegated: [] };
-  for (const artifact of install?.artifacts ?? []) {
+  const nativeFiles = (install?.nativeActivation?.mechanisms ?? [])
+    .filter(item => item.kind === "shell-bootstrap").flatMap(item => item.ownedFiles)
+    .map(file => ({ ...file, kind: "file" }));
+  for (const artifact of [...(install?.artifacts ?? []), ...nativeFiles]) {
     if (artifact.kind === "merge") { result.delegated.push(artifact.path); continue; }
     const current = await fingerprintFor(artifact);
     if (current === null) result.missing.push(artifact.path);
@@ -252,12 +256,14 @@ export async function removeOwnedArtifacts({ dataHome, adapterId }) {
 }
 
 /** Forget one install only after every adapter-owned cleanup step succeeded. */
-export async function finalizeRemoval({ dataHome, adapterId }) {
+export async function finalizeRemoval({ dataHome, adapterId, retainedNativeActivation = null }) {
   const record = await loadOwnership({ dataHome });
   if (installFor(record, adapterId) === null) return false;
 
   await saveOwnership({ dataHome, record: { schemaVersion: SCHEMA_VERSION,
-    installs: record.installs.filter(entry => entry.adapterId !== adapterId) } });
+    installs: record.installs.flatMap(entry => entry.adapterId !== adapterId ? [entry]
+      : retainedNativeActivation === null ? [] : [{ ...entry, artifacts: [], createdDirectories: [],
+        deliveryPolicy: "off", nativeActivation: retainedNativeActivation }]) } });
   return true;
 }
 

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

@@ -1,6 +1,6 @@
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
-import { LIVE_POLICIES, describeActivation, describeDeactivation, rcFileFor, shimDirFor }
+import { LIVE_POLICIES, describeActivation, describeDeactivation, planActivationRetirements, rcFileFor, shimDirFor }
   from "./native-activation.mjs";
 
 /**
@@ -124,8 +124,8 @@ export function planInstallation({ adapters, detected, context, action = "instal
         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 retirements = planActivationRetirements({ previous, desired: nativeActivation });
+    const deactivation = retirements.length > 0 ? { ...previous, mechanisms: retirements } : 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));

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

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

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

@@ -0,0 +1,85 @@
+import { createRequire } from "node:module";
+
+import { MCP_CAPABILITIES } from "./tools.mjs";
+
+export const PROTOCOL_VERSION = "2026-07-28";
+export const INITIALIZED_VERSIONS = Object.freeze(["2025-11-25", "2025-06-18"]);
+export const SUPPORTED_VERSIONS = Object.freeze([PROTOCOL_VERSION, ...INITIALIZED_VERSIONS]);
+const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version;
+const SERVER_INFO = Object.freeze({ name: "agents-can-communicate", version: PACKAGE_VERSION });
+const CAPABILITIES = Object.freeze({ tools: {}, resources: {} });
+const VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
+const CAPABILITIES_KEY = "io.modelcontextprotocol/clientCapabilities";
+const isObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const rpcError = (rpcCode, message, rpcData) =>
+  Object.assign(new Error(message), { rpcCode, rpcData });
+
+const complete = result => ({ resultType: "complete",
+  _meta: { "io.modelcontextprotocol/serverInfo": SERVER_INFO }, ...result });
+
+function requireProtocolMeta(params) {
+  const meta = params?._meta ?? {};
+  const version = meta[VERSION_KEY];
+  if (typeof version !== "string" || !isObject(meta[CAPABILITIES_KEY])) {
+    throw rpcError(-32602,
+      "each request requires _meta protocolVersion and clientCapabilities");
+  }
+  if (version !== PROTOCOL_VERSION) {
+    throw rpcError(-32022, `unsupported protocol version: ${version}`,
+      { supported: [...SUPPORTED_VERSIONS], requested: version });
+  }
+}
+
+/**
+ * Dual-era stdio: 2025 clients initialize their transport; 2026 requests carry
+ * their own metadata. Only protocol readiness is connection-local. ACC identity
+ * and durable session continuity always come from the server's launch config.
+ */
+export function createProtocol() {
+  let phase = "uninitialized";
+  return {
+    notify(message) {
+      if (message.method === "notifications/initialized" && phase === "initializing") {
+        phase = "ready";
+      }
+    },
+    async request({ method, params }, execute) {
+      if (method === "initialize") {
+        if (phase !== "uninitialized") throw rpcError(-32600, "already initialized");
+        if (typeof params?.protocolVersion !== "string" || !isObject(params.capabilities)
+          || !isObject(params.clientInfo) || typeof params.clientInfo.name !== "string"
+          || typeof params.clientInfo.version !== "string") {
+          throw rpcError(-32602, "initialize requires protocolVersion, capabilities and clientInfo");
+        }
+        const protocolVersion = INITIALIZED_VERSIONS.includes(params.protocolVersion)
+          ? params.protocolVersion : INITIALIZED_VERSIONS[0];
+        phase = "initializing";
+        return { protocolVersion, capabilities: CAPABILITIES, serverInfo: SERVER_INFO };
+      }
+
+      const meta = params?._meta;
+      const modern = method === "server/discover"
+        || (isObject(meta) && (Object.hasOwn(meta, VERSION_KEY)
+          || Object.hasOwn(meta, CAPABILITIES_KEY)));
+      if (modern) {
+        // Never inherit even one missing metadata field from an initialize.
+        requireProtocolMeta(params);
+      } else if (method !== "ping" && phase !== "ready") {
+        if (phase === "initializing") throw rpcError(-32600, "client has not sent initialized");
+        requireProtocolMeta(params);
+      }
+      const result = method === "server/discover"
+        ? { supportedVersions: [...SUPPORTED_VERSIONS], capabilities: CAPABILITIES,
+          serverInfo: SERVER_INFO, accCapabilities: MCP_CAPABILITIES }
+        : method === "ping" ? {} : await execute();
+      if (modern) return complete(result);
+      // 2025 structuredContent only accepts objects. Preserve the original
+      // JSON in text content for array/scalar tools such as acc_inbox.
+      if (Object.hasOwn(result, "structuredContent") && !isObject(result.structuredContent)) {
+        const { structuredContent, ...legacy } = result;
+        return legacy;
+      }
+      return result;
+    },
+  };
+}

package/node_modules/@agents-can-communicate/mcp-server/src/resources.mjs

@@ -43,9 +43,10 @@ export async function readResource(uri, { service, participantId, workspaceId, s
         throw new AccError(EXIT.DATA, "the inbox resource requires a resolved session",
           { participantId });
       }
-      const inbox = await service.readInbox({ workspaceId, sessionId: session.sessionId,
+      const inbox = await service.listInbox({ workspaceId, sessionId: session.sessionId,
         generation: session.generation });
-      return inbox.map(item => attributedMessage(item.message));
+      return { ...inbox, items: inbox.items.map(item => ({ ...item,
+        message: attributedMessage(item.message) })) };
     }
     default:
       throw new AccError(EXIT.DATA, `unknown resource: ${uri}`, { uri });

package/node_modules/@agents-can-communicate/mcp-server/src/server.mjs

@@ -1,5 +1,3 @@
-import { createRequire } from "node:module";
-
 import { AccError, EXIT, GENERIC_MESSAGE_KINDS, VALID_OBLIGATIONS }
   from "@agents-can-communicate/protocol";
 import { clearSessionBinding, loadSessionBinding, storeSessionBinding }
@@ -7,52 +5,34 @@ import { clearSessionBinding, loadSessionBinding, storeSessionBinding }
 
 import { readResource } from "./resources.mjs";
 import { validateToolInput } from "./input-validator.mjs";
-import { MCP_CAPABILITIES, PUBLIC_TOOLS, RESOURCES } from "./tools.mjs";
-
-export const PROTOCOL_VERSION = "2026-07-28";
-export const SUPPORTED_VERSIONS = Object.freeze([PROTOCOL_VERSION]);
-const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version;
-const SERVER_INFO = Object.freeze({ name: "agents-can-communicate", version: PACKAGE_VERSION });
+import { PUBLIC_TOOLS, RESOURCES } from "./tools.mjs";
+import { createProtocol } from "./protocol.mjs";
 
-const META = "io.modelcontextprotocol";
+export { PROTOCOL_VERSION, SUPPORTED_VERSIONS } from "./protocol.mjs";
 const HEARTBEAT_CADENCE_MS = 60_000;
 
-const complete = result => ({ resultType: "complete",
-  _meta: { [`${META}/serverInfo`]: SERVER_INFO }, ...result });
-
-function requireProtocolMeta(params) {
-  const meta = params?._meta ?? {};
-  const version = meta[`${META}/protocolVersion`];
-  const capabilities = meta[`${META}/clientCapabilities`];
-  // The revision requires both on every request and mandates -32602 when one is
-  // missing. No prior request may be used to supply them.
-  if (typeof version !== "string" || capabilities === undefined) {
-    throw Object.assign(new Error(
-      "each request requires _meta protocolVersion and clientCapabilities"),
-    { rpcCode: -32602 });
-  }
-  if (!SUPPORTED_VERSIONS.includes(version)) {
-    throw Object.assign(new Error(`unsupported protocol version: ${version}`),
-      { rpcCode: -32022, rpcData: { supported: [...SUPPORTED_VERSIONS] } });
-  }
-  return { version, capabilities };
-}
-
 /**
  * Resolve the ACC session for this server from its own launch configuration.
  *
- * Approved 2026-08-16. The protocol is stateless and forbids treating process or
+ * Approved 2026-08-16. The 2026 interface forbids treating process or
  * connection identity as session continuity, so the session cannot be anchored
  * to the stdio process. It is derived from the participant and workspace this
  * server was configured with - available identically on every request - and
  * persisted through a binding so a restarted process resolves to the same
  * session instead of creating a second participant.
  */
-async function resolveSession(context) {
+async function resolveSession(context, { forFinish = false } = {}) {
   const key = `mcp:${context.participantId}:${context.workspaceId}`;
   const existing = await loadSessionBinding({ runtimeDir: context.runtimeDir,
     harnessSessionId: key });
   if (existing !== null) {
+    if (forFinish) {
+      const current = await context.service.locateSession(existing.accSessionId, context.workspaceId);
+      // Core validates and closes this exact generation, including retries.
+      // A prior heartbeat could race another finish and reopen a different owner.
+      if (current !== null
+        && current.record.generation === existing.generation) return current.record;
+    }
     try {
       return await context.service.heartbeatSession({ sessionId: existing.accSessionId,
         generation: existing.generation, workspaceId: context.workspaceId });
@@ -131,7 +111,7 @@ function obligationFor(kind, explicit, addressed) {
  * agreeing to it.
  */
 async function callTool(name, args, context) {
-  const session = await resolveSession(context);
+  const session = await resolveSession(context, { forFinish: name === "acc_finish" });
   const owner = { sessionId: session.sessionId, generation: session.generation,
     workspaceId: context.workspaceId, descriptor: context.descriptor };
   const service = context.service;
@@ -141,7 +121,7 @@ async function callTool(name, args, context) {
       return service.collectStatus({});
     case "acc_sync":
       return service.sync({ ...owner, cursor: args.cursor ?? null,
-        scope: args.scope, limit: args.limit });
+        scope: args.scope, limit: args.limit, messageId: args.messageId, kind: args.kind, current: args.current });
     case "acc_work":
       if (args.clear === true) {
         await service.clearIntent({ ...owner });
@@ -164,11 +144,19 @@ async function callTool(name, args, context) {
       const routed = await recordAndOffer({ router: context.deliveryRouter, record: () =>
         service.sendMessage({ ...owner, clientMessageId: clientMessageId(args, service),
         toParticipantIds, subject: args.subject, body: args.body, kind,
-        obligation: obligationFor(kind, args.obligation, toParticipantIds.length > 0) }) });
+        supersedes: args.supersedes, withdraws: args.withdraws,
+        obligation: obligationFor(kind, args.obligation, toParticipantIds.length > 0
+          || args.supersedes !== undefined || args.withdraws !== undefined) }) });
       const message = routed.recorded;
       return { message, delivery: routed.delivery };
     }
     case "acc_inbox":
+      if (args.messageId === undefined) {
+        return service.listInbox({ ...owner, cursor: args.cursor, limit: args.limit });
+      }
+      if (args.cursor !== undefined || args.limit !== undefined) {
+        throw new AccError(EXIT.USAGE, "an exact inbox read cannot use cursor or limit");
+      }
       return service.readInbox({ ...owner, messageId: args.messageId });
     case "acc_reply": {
       const routed = await recordAndOffer({ router: context.deliveryRouter,
@@ -176,7 +164,8 @@ async function callTool(name, args, context) {
         record: () => service.replyToMessage({ ...owner, messageId: args.messageId,
           body: args.body, subject: args.subject,
           clientMessageId: clientMessageId(args, service) }) });
-      return { message: routed.recorded.reply, delivery: routed.delivery };
+      return { message: routed.recorded.reply, receipt: routed.recorded.receipt,
+        delivery: routed.delivery };
     }
     case "acc_request": {
       const routed = await recordAndOffer({ router: context.deliveryRouter,
@@ -204,27 +193,20 @@ async function callTool(name, args, context) {
 
 async function handle(message, context) {
   const { method, params } = message;
-  if (method === "server/discover") {
-    requireProtocolMeta(params);
-    return complete({ supportedVersions: [...SUPPORTED_VERSIONS], capabilities: {
-      tools: {}, resources: {} }, serverInfo: SERVER_INFO, accCapabilities: MCP_CAPABILITIES });
-  }
-  requireProtocolMeta(params);
   switch (method) {
     case "tools/list":
-      return complete({ tools: [...PUBLIC_TOOLS] });
+      return { tools: [...PUBLIC_TOOLS] };
     case "resources/list":
-      return complete({ resources: [...RESOURCES] });
+      return { resources: [...RESOURCES] };
     case "resources/read": {
-      // Snapshot and roster are observation-only. Inbox is a delivery boundary:
-      // resolve this configured participant's durable session and let the core
-      // inbox service record that the returned bodies were retrieved.
+      // Inbox discovery uses this configured participant's current owner but
+      // returns summaries only. Reading this resource never retrieves bodies.
       const resourceContext = params.uri === "acc://inbox"
         ? { ...context, session: await resolveSession(context) }
         : context;
       const value = await readResource(params.uri, resourceContext);
-      return complete({ contents: [{ uri: params.uri, mimeType: "application/json",
-        text: JSON.stringify(value, null, 2) }] });
+      return { contents: [{ uri: params.uri, mimeType: "application/json",
+        text: JSON.stringify(value, null, 2) }] };
     }
     case "tools/call": {
       try {
@@ -235,13 +217,13 @@ async function handle(message, context) {
         }
         validateToolInput(tool.inputSchema, args);
         const value = await callTool(params.name, args, context);
-        return complete({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
-          structuredContent: value });
+        return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+          structuredContent: value };
       } catch (error) {
         // A failing operation is a tool result, not a transport failure: the
         // model must see it and be able to react.
-        return complete({ isError: true,
-          content: [{ type: "text", text: `${params.name}: ${error.message}` }] });
+        return { isError: true,
+          content: [{ type: "text", text: `${params.name}: ${error.message}` }] };
       }
     }
     default:
@@ -255,6 +237,7 @@ async function handle(message, context) {
  */
 export async function serve({ input, output, log, context }) {
   const write = value => output.write(`${JSON.stringify(value)}\n`);
+  const protocol = createProtocol();
   let buffer = "";
 
   for await (const chunk of input) {
@@ -269,13 +252,32 @@ export async function serve({ input, output, log, context }) {
       try {
         message = JSON.parse(line);
       } catch {
-        write({ jsonrpc: "2.0", error: { code: -32700, message: "parse error" } });
+        write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+        continue;
+      }
+      // Validate the envelope before accessing fields or treating it as a notification.
+      const id = typeof message?.id === "string" || typeof message?.id === "number"
+        ? message.id : null;
+      if (message === null || typeof message !== "object" || Array.isArray(message)
+        || message.jsonrpc !== "2.0" || typeof message.method !== "string"
+        || (message.id !== undefined && message.id !== null
+          && typeof message.id !== "string" && typeof message.id !== "number")) {
+        write({ jsonrpc: "2.0", id, error: { code: -32600, message: "invalid request" } });
+        continue;
+      }
+      // Once the envelope is valid, notifications get no reply, even for invalid params.
+      if (message.id === undefined || message.id === null) {
+        protocol.notify(message);
+        continue;
+      }
+      if (message.params !== undefined
+        && (message.params === null || typeof message.params !== "object")) {
+        write({ jsonrpc: "2.0", id, error: { code: -32602, message: "invalid params" } });
         continue;
       }
-      // Notifications get no reply, by rule.
-      if (message.id === undefined || message.id === null) continue;
       try {
-        write({ jsonrpc: "2.0", id: message.id, result: await handle(message, context) });
+        write({ jsonrpc: "2.0", id: message.id,
+          result: await protocol.request(message, () => handle(message, context)) });
       } catch (error) {
         log?.(`${message.method}: ${error.message}`);
         write({ jsonrpc: "2.0", id: message.id, error: {

package/node_modules/@agents-can-communicate/mcp-server/src/tools.mjs

@@ -1,13 +1,14 @@
-import { GENERIC_MESSAGE_KINDS } from "@agents-can-communicate/protocol";
+import { GENERIC_MESSAGE_KINDS, MESSAGE_KINDS } from "@agents-can-communicate/protocol";
 
 // The model-facing surface stays at a small set of high-level operations.
 //
-// Every description says that delivery is polled, because a tool description is
-// the only contract the model ever sees. MCP guarantees no lifecycle, no push,
-// and no write guard, so promising any of them here would be a lie the model
-// cannot check.
-const POLLED = "Delivery is polled: call this again to observe changes. "
-  + "MCP provides no push notification and no wake.";
+// MCP receives by polling. Outgoing messages can use the recipient's native
+// adapter without giving this MCP client native lifecycle, context, or guards.
+// Polling guidance must never tell the model to repeat a mutation to read state.
+const POLLED = "Poll for changes; MCP has no incoming push or wake.";
+const MUTATION_POLL = "Poll acc_inbox, acc_status, or acc_sync for changes instead of repeating this mutation.";
+const OUTGOING = "Commits first; eligible, opted-in native offers are possible. Pending messages otherwise stay queued. "
+  + "Inspect delivery; retry with the same clientMessageId and payload.";
 
 const object = (properties, required = []) => ({
   type: "object",
@@ -29,21 +30,25 @@ export const PUBLIC_TOOLS = Object.freeze([
   {
     name: "acc_sync",
     description: `Read coordination state for this workspace: roster, attention items, and `
-      + `events since a cursor. Use scope "full" to answer questions about the whole `
-      + `workspace, including other participants' collapsed child sessions. Use acc_inbox `
-      + `instead for addressed messages. ${POLLED}`,
+      + `events since a cursor. Use scope "history" for bounded message summaries, then `
+      + `messageId to read one complete historical message without changing receipts. `
+      + `Scope "full" is an unbounded forensic workspace snapshot. Use acc_inbox for `
+      + `your addressed messages. ${POLLED}`,
     inputSchema: object({
-      cursor: string("Resume from this cursor; omit to start from the beginning."),
-      scope: { type: "string", enum: ["delta", "full"],
-        description: "delta is a bounded update; full returns the whole workspace snapshot." },
+      cursor: string("Event sequence for delta/full; nextCursor message id for history. Omit for the newest history page."),
+      scope: { type: "string", enum: ["delta", "full", "history"],
+        description: "delta: events; history: read-only message discovery; full: complete forensic snapshot." },
       limit: { type: "integer", minimum: 1, maximum: 500,
-        description: "Maximum number of events to return." },
+        description: "Maximum events (default 100), or history summaries (default 20, also byte-bounded)." },
+      kind: { type: "string", enum: [...MESSAGE_KINDS], description: "Filter history before paging." },
+      current: { type: "boolean", description: "With history and kind decision, list only terminal decisions/withdrawals; conflicts remain visible." },
+      messageId: string("Read this complete history message; requires history scope and no list controls."),
     }),
   },
   {
     name: "acc_work",
     description: `Publish what this session is doing now as one concise Intent. Intent is `
-      + `awareness, not authorisation: it never reserves a resource. ${POLLED}`,
+      + `awareness, not authorisation: it never reserves a resource. ${MUTATION_POLL}`,
     inputSchema: { ...object({
       summary: string("One line describing the current work."),
       mode: { type: "string",
@@ -63,7 +68,7 @@ export const PUBLIC_TOOLS = Object.freeze([
     name: "acc_claim",
     description: `Acquire or renew a claim on a resource URI. Claims are `
       + `workspace-wide and advisory here: this client has no write guard, so a claim `
-      + `informs peers rather than preventing an edit. ${POLLED}`,
+      + `informs peers rather than preventing an edit. ${MUTATION_POLL}`,
     inputSchema: { ...object({
       resource: string("Resource URI, for example file:packages/core/**."),
       action: { type: "string", enum: ["acquire", "renew"] },
@@ -82,15 +87,14 @@ export const PUBLIC_TOOLS = Object.freeze([
   },
   {
     name: "acc_release",
-    description: `Release a claim this session owns. ${POLLED}`,
+    description: `Release a claim this session owns. ${MUTATION_POLL}`,
     inputSchema: object({
       claimId: string("The claim to release."),
     }, ["claimId"]),
   },
   {
     name: "acc_message",
-    description: `Durably record a typed message to other participants. Recipients read it `
-      + `when they next poll; there is no push guarantee and no wake. ${POLLED}`,
+    description: `Durably record a typed message to other participants. ${OUTGOING} ${MUTATION_POLL}`,
     inputSchema: object({
       to: stringList("Recipient participant ids."),
       subject: string("Short subject line."),
@@ -99,28 +103,38 @@ export const PUBLIC_TOOLS = Object.freeze([
         enum: [...GENERIC_MESSAGE_KINDS] },
       obligation: { type: "string", enum: ["none", "acknowledge", "reply"],
         description: "Override only where the kind/obligation matrix permits it." },
-      clientMessageId: string("Retry key; omit to generate one and return it in message."),
+      clientMessageId: string("Retry key; supply before sending if needed after a lost response. Omit to generate one returned in message."),
+      supersedes: { ...stringList("Decision IDs this new decision replaces. Inherits recipients and authors. Exclusive with withdraws."),
+        minItems: 1, maxItems: 16, uniqueItems: true },
+      withdraws: { ...stringList("Decision IDs explicitly withdrawn, with body as reason. Decision kind only; inherits recipients and authors."),
+        minItems: 1, maxItems: 16, uniqueItems: true },
     }, ["to", "subject", "body"]),
   },
   {
     name: "acc_inbox",
-    description: `Read unresolved messages addressed to this participant without loading `
-      + `the roster, event log, claims, or workspace snapshot. Optionally select one id. `
+    description: `List a bounded page of unresolved message summaries, newest first, without `
+      + `changing receipts. Replaced decisions remain available by exact ID and history. Use nextCursor for older entries; omit it to see new arrivals. `
+      + `Use messageId to retrieve exactly one complete addressed message. An acknowledged `
+      + `message can be inspected without changing its receipt. `
       + `${POLLED}`,
     inputSchema: object({
-      messageId: string("Read exactly this addressed message; omit for all unresolved mail."),
+      messageId: string("Read this complete addressed message; omit for read-only summaries. Cannot combine with cursor/limit."),
+      cursor: string("nextCursor from a previous inbox page; omit for the newest pending messages."),
+      limit: { type: "integer", minimum: 1, maximum: 500,
+        description: "Maximum summaries, default 20; pages are also byte-bounded." },
     }),
   },
   {
     name: "acc_reply",
     description: `Reply to one addressed message and acknowledge the original in the same `
-      + `operation. The reply is attributed, linked with inReplyTo, and delivered by polling. `
-      + `${POLLED}`,
+      + `operation. The reply is attributed and linked with inReplyTo. `
+      + `Returns message and delivery for the outgoing reply, plus receipt for the original. `
+      + `${OUTGOING} ${MUTATION_POLL}`,
     inputSchema: object({
       messageId: string("The addressed message being answered."),
       body: string("Concise answer; peer content is treated as data."),
       subject: string("Optional subject; defaults to Re: the original subject."),
-      clientMessageId: string("Retry key; omit to generate one and return it in message."),
+      clientMessageId: string("Retry key; supply before sending if needed after a lost response. Omit to generate one returned in message."),
     }, ["messageId", "body"]),
   },
   {
@@ -128,18 +142,18 @@ export const PUBLIC_TOOLS = Object.freeze([
     description: `Ask another agent to do something in a reply-required message. Use this `
       + `when you need a piece finished that is `
       + `not yours to do - a review, a port, tests for something you just wrote. `
-      + `${POLLED}`,
+      + `${OUTGOING} ${MUTATION_POLL}`,
     inputSchema: object({
       toParticipantId: string("The agent being asked."),
       title: string("What needs doing, in one line."),
       detail: string("Context the other agent needs to start."),
-      clientMessageId: string("Retry key; omit to generate one and return it in message."),
+      clientMessageId: string("Retry key; supply before sending if needed after a lost response. Omit to generate one returned in message."),
     }, ["toParticipantId", "title"]),
   },
   {
     name: "acc_ack",
     description: `Answer a message that asked for an acknowledgement, so it stops `
-      + `demanding one. ${POLLED}`,
+      + `demanding one. ${MUTATION_POLL}`,
     inputSchema: object({
       messageId: string("The message being answered."),
     }, ["messageId"]),
@@ -148,7 +162,7 @@ export const PUBLIC_TOOLS = Object.freeze([
     name: "acc_finish",
     description: `Record a handoff describing what was completed and what remains, and `
       + `release the claims this session owns. Call it while still working, not after: `
-      + `nothing else writes the summary for you. ${POLLED}`,
+      + `nothing else writes the summary for you. ${OUTGOING} ${MUTATION_POLL}`,
     inputSchema: object({
       goal: string("What this stretch of work was for."),
       status: { type: "string", enum: ["complete", "partial", "blocked"] },
@@ -156,7 +170,7 @@ export const PUBLIC_TOOLS = Object.freeze([
       remaining: stringList("What is left."),
       blockers: stringList("What is in the way."),
       toParticipantId: string("Participant taking over, if any."),
-      clientMessageId: string("Retry key; omit to generate one and return it in message."),
+      clientMessageId: string("Retry key; supply before sending if needed after a lost response. Omit to generate one returned in message."),
     }, ["goal"]),
   },
 ]);
@@ -165,9 +179,9 @@ export const RESOURCES = Object.freeze([
   { uri: "acc://snapshot", name: "Workspace snapshot", mimeType: "application/json",
     description: "The whole coordination state: participants, intents, claims, and messages." },
   { uri: "acc://roster", name: "Participant roster", mimeType: "application/json",
-    description: "Sessions with their harness and presence, including collapsed children." },
+    description: "Sessions with their harness and presence." },
   { uri: "acc://inbox", name: "Inbox", mimeType: "application/json",
-    description: "Messages addressed to this participant, rendered as attributed data." },
+    description: "Read-only pending message headers. Continue with acc_inbox cursor; retrieve a body with messageId." },
 ]);
 
 // Declared, not assumed. Manual MCP tool polling is not next-turn injection,

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

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