agents-can-communicate 0.1.0

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

@@ -0,0 +1,162 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+const SCHEMA_VERSION = 1;
+
+// Installation state belongs to the machine, never to a project. A repository
+// carrying it would hand one machine's paths to every clone, where none of them
+// exist and all of them look like something to clean up.
+const recordPath = dataHome => path.join(dataHome, "acc", "installs.json");
+
+/**
+ * Content fingerprint, or null when the file is gone.
+ *
+ * Uninstall compares this against what is on disk, so ACC removes what it wrote
+ * and leaves what someone has since made their own. Deleting by name alone
+ * throws away other people's work on the strength of a path it recognises.
+ */
+export async function fingerprint(file) {
+  try {
+    return createHash("sha256").update(await readFile(file)).digest("hex");
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "EISDIR") return null;
+    throw error;
+  }
+}
+
+/**
+ * Fingerprint of a whole directory ACC created.
+ *
+ * Every file's path and contents, in sorted order, so an edit anywhere inside a
+ * plugin bundle is as visible as an edit to a single file. Sorting is what makes
+ * it reproducible: directory order is a filesystem detail, and a hash that
+ * depended on it would report a modification after a harmless copy.
+ */
+export async function treeFingerprint(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { recursive: true, withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    if (error.code === "ENOTDIR") return fingerprint(root);
+    throw error;
+  }
+  const files = entries.filter(entry => entry.isFile())
+    .map(entry => path.relative(root, path.join(entry.parentPath ?? entry.path, entry.name)))
+    .sort();
+  const hash = createHash("sha256");
+  for (const relative of files) {
+    hash.update(relative).update("\0");
+    hash.update(await fingerprint(path.join(root, relative)) ?? "");
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+const fingerprintFor = (artifact) => (artifact.kind === "tree"
+  ? treeFingerprint(artifact.path)
+  : fingerprint(artifact.path));
+
+export async function loadOwnership({ dataHome }) {
+  const file = recordPath(dataHome);
+  let source;
+  try {
+    source = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { schemaVersion: SCHEMA_VERSION, installs: [] };
+    throw error;
+  }
+  let record;
+  try {
+    record = JSON.parse(source);
+  } catch (error) {
+    // Treating a corrupt record as empty would make the next uninstall a no-op
+    // and orphan every file ACC has ever written on this machine.
+    throw new AccError(EXIT.DATA, "the installation record is not valid JSON",
+      { file, cause: error.message });
+  }
+  if (record?.schemaVersion !== SCHEMA_VERSION) {
+    throw new AccError(EXIT.DATA, "unknown installation record schemaVersion",
+      { file, schemaVersion: record?.schemaVersion ?? null });
+  }
+  return { schemaVersion: SCHEMA_VERSION, installs: record.installs ?? [] };
+}
+
+async function saveOwnership({ dataHome, record }) {
+  const file = recordPath(dataHome);
+  await mkdir(path.dirname(file), { recursive: true });
+  // Published by rename so a crash mid-write leaves the previous record intact
+  // rather than a truncated one that would fail to load at all.
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  await rename(temporary, file);
+}
+
+/**
+ * Record what an install wrote, replacing any previous record for that adapter.
+ *
+ * Replacing rather than appending is what makes a re-run after a crash safe: the
+ * second run's record describes what is actually on disk now, and an accumulated
+ * one would list artifacts from a layout that no longer exists.
+ */
+export async function recordInstall({ dataHome, adapterId, version, artifacts }) {
+  const stamped = await Promise.all(artifacts.map(async artifact => ({
+    path: artifact.path,
+    kind: artifact.kind ?? "file",
+    // A merge artifact is a file ACC edited but does not own, so its bytes are
+    // expected to change and hashing them would only ever produce a false alarm.
+    sha256: artifact.kind === "merge" ? null : await fingerprintFor(artifact),
+  })));
+  const record = await loadOwnership({ dataHome });
+  await saveOwnership({ dataHome, record: { schemaVersion: SCHEMA_VERSION,
+    installs: [...record.installs.filter(install => install.adapterId !== adapterId),
+      { adapterId, version, artifacts: stamped }] } });
+}
+
+const installFor = (record, adapterId) =>
+  record.installs.find(install => install.adapterId === adapterId) ?? null;
+
+/** Compare what was written against what is there now. Read-only. */
+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 ?? []) {
+    if (artifact.kind === "merge") { result.delegated.push(artifact.path); continue; }
+    const current = await fingerprintFor(artifact);
+    if (current === null) result.missing.push(artifact.path);
+    else if (current !== artifact.sha256) result.modified.push(artifact.path);
+    else result.intact.push(artifact.path);
+  }
+  return result;
+}
+
+/**
+ * Remove the files this adapter's install wrote, and only those.
+ *
+ * A modified file is kept and reported. A merge artifact is never deleted at
+ * all: the user owns that file and ACC owns some entries inside it, which is the
+ * adapter's own uninstall to unpick because it knows the format.
+ */
+export async function removeOwned({ dataHome, adapterId }) {
+  const record = await loadOwnership({ dataHome });
+  const install = installFor(record, adapterId);
+  const result = { adapterId, removed: [], kept: [], missing: [], delegated: [] };
+  if (install === null) return result;
+
+  for (const artifact of install.artifacts) {
+    if (artifact.kind === "merge") { result.delegated.push(artifact.path); continue; }
+    const current = await fingerprintFor(artifact);
+    if (current === null) { result.missing.push(artifact.path); continue; }
+    if (current !== artifact.sha256) { result.kept.push(artifact.path); continue; }
+    await rm(artifact.path, { force: true, recursive: artifact.kind === "tree" });
+    result.removed.push(artifact.path);
+  }
+
+  await saveOwnership({ dataHome, record: { schemaVersion: SCHEMA_VERSION,
+    installs: record.installs.filter(entry => entry.adapterId !== adapterId) } });
+  return result;
+}

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

@@ -0,0 +1,62 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+/**
+ * Turn a detection report into exactly what would happen.
+ *
+ * Pure and deterministic: same detection, same plan, byte for byte. That is what
+ * makes `--dry-run` worth reading - a plan computed differently from the thing
+ * it previews is a decoration, and the operator would find out only afterwards.
+ */
+export function planInstallation({ adapters, detected, context, action = "install" }) {
+  if (!["install", "uninstall"].includes(action)) {
+    throw new AccError(EXIT.USAGE, `unknown installation action: ${action}`, { action });
+  }
+  const byId = new Map(adapters.map(adapter => [adapter.id, adapter]));
+  const operations = [];
+  const skipped = [];
+
+  // Sorted by id, so two runs on the same machine produce identical JSON and a
+  // diff between them means something changed rather than that a registry
+  // enumerated in a different order.
+  for (const entry of [...detected].sort((a, b) => a.adapterId.localeCompare(b.adapterId))) {
+    const adapter = byId.get(entry.adapterId);
+    if (adapter === undefined) {
+      skipped.push({ adapterId: entry.adapterId, reason: "no adapter for this client" });
+      continue;
+    }
+    if (!entry.present) {
+      // Named rather than dropped: "nothing happened" and "that client is not
+      // installed on this machine" look the same in an empty list.
+      skipped.push({ adapterId: entry.adapterId,
+        reason: `${entry.displayName ?? entry.adapterId} is not installed on this machine` });
+      continue;
+    }
+    if (typeof adapter.planInstall !== "function") {
+      skipped.push({ adapterId: entry.adapterId,
+        reason: "this adapter cannot describe what it would write" });
+      continue;
+    }
+
+    const artifacts = adapter.planInstall(context)
+      .map(artifact => ({ path: artifact.path, kind: artifact.kind ?? "file" }))
+      .sort((a, b) => a.path.localeCompare(b.path));
+
+    operations.push({
+      adapterId: adapter.id,
+      displayName: adapter.displayName,
+      action,
+      clientVersion: entry.version ?? null,
+      alreadyInstalled: entry.installed === true,
+      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.
+      summary: [
+        ...artifacts.filter(a => a.kind === "tree")
+          .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}`),
+      ],
+    });
+  }
+  return { schemaVersion: 1, action, operations, skipped };
+}

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

@@ -0,0 +1,12 @@
+{
+  "name": "@agents-can-communicate/mcp-server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/server.mjs"
+  },
+  "files": [
+    "src/"
+  ]
+}

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

@@ -0,0 +1,58 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+// Peer-authored strings reach a human's terminal through whatever renders these
+// resources, so control sequences become visible escapes here rather than
+// somewhere downstream. Attribution is never dropped: a message without its
+// sender and type is indistinguishable from an instruction.
+function escapeText(value) {
+  let result = "";
+  for (const character of String(value)) {
+    const code = character.codePointAt(0);
+    result += (code < 32 && code !== 10 && code !== 9) || code === 127
+      ? `\\u${code.toString(16).padStart(4, "0")}`
+      : character;
+  }
+  return result;
+}
+
+const attributedMessage = message => ({
+  messageId: message.messageId,
+  from: message.fromSessionId,
+  type: message.type,
+  priority: message.priority,
+  requiresAck: message.requiresAck,
+  sentAt: message.sentAt,
+  trust: "untrusted peer content",
+  subject: escapeText(message.subject),
+  body: escapeText(message.body),
+});
+
+export async function readResource(uri, { service, participantId, workspaceId }) {
+  const snapshot = await service.store.snapshot(workspaceId);
+  switch (uri) {
+    case "acc://snapshot":
+      return { ...snapshot,
+        messages: snapshot.messages.map(attributedMessage) };
+    case "acc://roster":
+      return (await service.sync({ workspaceId })).roster;
+    case "acc://workstreams":
+      return snapshot.workstreams;
+    case "acc://tasks":
+      return snapshot.tasks;
+    case "acc://inbox": {
+      const mine = new Set(snapshot.receipts
+        .filter(receipt => receipt.recipientParticipantId === participantId)
+        .map(receipt => receipt.messageId));
+      // A participant sees what was addressed to it, plus what it sent, so a
+      // fresh reader can follow its own thread.
+      return snapshot.messages
+        .filter(message => mine.has(message.messageId)
+          || message.toParticipantIds.includes(participantId)
+          || snapshot.sessions.some(session => session.sessionId === message.fromSessionId
+            && session.participantId === participantId))
+        .map(attributedMessage);
+    }
+    default:
+      throw new AccError(EXIT.DATA, `unknown resource: ${uri}`, { uri });
+  }
+}

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

@@ -0,0 +1,250 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { clearSessionBinding, loadSessionBinding, storeSessionBinding }
+  from "@agents-can-communicate/adapter-sdk";
+
+import { readResource } from "./resources.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 SERVER_INFO = Object.freeze({ name: "agents-can-communicate", version: "0.0.0" });
+
+const META = "io.modelcontextprotocol";
+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
+ * 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) {
+  const key = `mcp:${context.participantId}:${context.workspaceId}`;
+  const existing = await loadSessionBinding({ runtimeDir: context.runtimeDir,
+    harnessSessionId: key });
+  if (existing !== null) {
+    try {
+      return await context.service.heartbeatSession({ sessionId: existing.accSessionId,
+        generation: existing.generation, workspaceId: context.workspaceId });
+    } catch (error) {
+      if (error.code !== EXIT.CONFLICT) throw error;
+      // The recorded generation is gone. Clearing before reopening keeps the
+      // failure visible instead of silently accumulating bindings.
+      await clearSessionBinding({ runtimeDir: context.runtimeDir, harnessSessionId: key });
+    }
+  }
+  const session = await context.service.openSession({
+    workspaceId: context.workspaceId,
+    participantId: context.participantId,
+    displayName: context.participantId,
+    harness: "mcp",
+    heartbeatCadenceMs: HEARTBEAT_CADENCE_MS,
+    descriptor: context.descriptor,
+  });
+  await storeSessionBinding({ runtimeDir: context.runtimeDir, harnessSessionId: key,
+    accSessionId: session.sessionId, generation: session.generation });
+  return session;
+}
+
+/**
+ * A poll is this client's turn.
+ *
+ * The hook runtime hands a session its pending messages when it builds a turn,
+ * and marks them delivered. An MCP client has no turn and no hook, and no tool
+ * ever handed it anything: it saw a `direct_request` line carrying a subject and
+ * an id, and to read what a peer had actually said it had to ask for the whole
+ * snapshot and search every message in the workspace for its own name.
+ *
+ * The receipt never moved either. It stayed `queued` for as long as the client
+ * ran, so the sender was told its message had not been delivered by an agent
+ * that had answered it.
+ *
+ * Returning them here is delivery, in the same sense and with the same honesty
+ * as the turn: what is handed over is marked `injected`, and nothing else is.
+ * Acknowledgement stays a separate act, because being shown something is not
+ * agreeing to it.
+ */
+async function syncWithMail(service, owner, context, args) {
+  const sync = await service.sync({ ...owner, cursor: args.cursor ?? null,
+    scope: args.scope, limit: args.limit });
+  const messages = await service.pendingMessages({
+    workspaceId: context.workspaceId,
+    participantId: context.participantId,
+    exceptSessionId: owner.sessionId });
+  if (messages.length === 0) return sync;
+
+  for (const message of messages) {
+    // One failure must not swallow the rest: the client is holding the message
+    // either way, and a receipt that cannot be written is not a reason to hide
+    // what a peer said.
+    await service.markDelivery({ ...owner, messageId: message.messageId,
+      state: "injected" }).catch(() => null);
+  }
+  return { ...sync, messages };
+}
+
+async function callTool(name, args, context) {
+  const session = await resolveSession(context);
+  const owner = { sessionId: session.sessionId, generation: session.generation,
+    workspaceId: context.workspaceId, descriptor: context.descriptor };
+  const service = context.service;
+
+  switch (name) {
+    case "acc_sync":
+      return syncWithMail(service, owner, context, args);
+    case "acc_work":
+      if (args.clear === true) return service.clearIntent({ ...owner });
+      return service.setIntent({ ...owner, summary: args.summary, mode: args.mode,
+        state: args.state, workstreamId: args.workstreamId ?? null,
+        resourceHints: args.resourceHints ?? [] });
+    case "acc_claim":
+      if (args.action === "release") return service.releaseClaim({ ...owner,
+        claimId: args.claimId }) ?? { released: args.claimId };
+      if (args.action === "renew") return service.renewClaim({ ...owner,
+        claimId: args.claimId, leaseSeconds: args.leaseSeconds });
+      return service.acquireClaim({ ...owner, resource: args.resource,
+        mode: args.mode ?? "exclusive", enforcement: "advisory",
+        reason: args.reason ?? "unspecified", leaseSeconds: args.leaseSeconds });
+    case "acc_message":
+      return service.sendMessage({ ...owner, toParticipantIds: args.to ?? [],
+        subject: args.subject, body: args.body, type: args.type ?? "note",
+        priority: args.priority, requiresAck: args.requiresAck === true,
+        workstreamId: args.workstreamId ?? null });
+    case "acc_task":
+      if (args.action === "claim") return service.claimTask({ ...owner,
+        taskId: args.taskId, force: args.force === true });
+      if (args.action === "decline") return service.declineTask({ ...owner,
+        taskId: args.taskId, reason: args.reason });
+      if (args.action === "transition") return service.transitionTask({ ...owner,
+        taskId: args.taskId, state: args.state });
+      return service.createTask({ ...owner, workstreamId: args.workstreamId,
+        title: args.title, detail: args.detail, taskId: args.taskId,
+        assigneeParticipantId: args.assigneeParticipantId,
+        dependsOn: args.dependsOn ?? [] });
+    case "acc_request":
+      return service.requestWork({ ...owner, toParticipantId: args.toParticipantId,
+        title: args.title, detail: args.detail, workstreamId: args.workstreamId,
+        priority: args.priority, dependsOn: args.dependsOn ?? [] });
+    case "acc_ack":
+      return service.markDelivery({ ...owner, messageId: args.messageId,
+        state: args.state ?? "acknowledged" });
+    case "acc_decide":
+      return service.recordDecision({ ...owner, title: args.title, outcome: args.outcome,
+        authority: args.authority ?? "workstream", workstreamId: args.workstreamId ?? null,
+        decidedBy: args.decidedBy, supersedes: args.supersedes ?? null,
+        humanConfirmed: args.humanConfirmed === true });
+    case "acc_workstream":
+      if (args.action === "coordinate") {
+        return service.acquireCoordinator({ ...owner, workstreamId: args.workstreamId });
+      }
+      if (args.action === "release") {
+        return service.releaseCoordinator({ ...owner, workstreamId: args.workstreamId });
+      }
+      return service.createWorkstream({ ...owner, title: args.title,
+        objective: args.objective });
+    case "acc_finish":
+      return service.finishSession({ ...owner, goal: args.goal, status: args.status,
+        completed: args.completed ?? [], remaining: args.remaining ?? [],
+        blockers: args.blockers ?? [], toParticipantId: args.toParticipantId ?? null });
+    default:
+      throw new AccError(EXIT.USAGE, `unknown tool: ${name}`, { name });
+  }
+}
+
+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] });
+    case "resources/list":
+      return complete({ resources: [...RESOURCES] });
+    case "resources/read": {
+      const value = await readResource(params.uri, context);
+      return complete({ contents: [{ uri: params.uri, mimeType: "application/json",
+        text: JSON.stringify(value, null, 2) }] });
+    }
+    case "tools/call": {
+      try {
+        const value = await callTool(params.name, params.arguments ?? {}, context);
+        return complete({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+          structuredContent: JSON.stringify(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}` }] });
+      }
+    }
+    default:
+      throw Object.assign(new Error(`unknown method: ${method}`), { rpcCode: -32601 });
+  }
+}
+
+/**
+ * Newline-delimited JSON-RPC over the given streams. stdout carries protocol
+ * messages only; anything the server wants to say goes to stderr.
+ */
+export async function serve({ input, output, log, context }) {
+  const write = value => output.write(`${JSON.stringify(value)}\n`);
+  let buffer = "";
+
+  for await (const chunk of input) {
+    buffer += chunk;
+    let index = buffer.indexOf("\n");
+    while (index !== -1) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      index = buffer.indexOf("\n");
+      if (line === "") continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        write({ jsonrpc: "2.0", error: { code: -32700, message: "parse error" } });
+        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) });
+      } catch (error) {
+        log?.(`${message.method}: ${error.message}`);
+        write({ jsonrpc: "2.0", id: message.id, error: {
+          code: error.rpcCode ?? -32603,
+          message: error.message,
+          ...(error.rpcData === undefined ? {} : { data: error.rpcData }) } });
+      }
+    }
+  }
+}