agents-can-communicate 0.1.0

package/node_modules/@agents-can-communicate/adapter-sdk/src/context-projector.mjs

@@ -0,0 +1,217 @@
+const DEFAULT_BUDGET_BYTES = 6_000;
+// Held back from the required lines so the "not shown" note can always be
+// written. A projection that silently drops what it could not fit is how an
+// agent ends up confidently unaware.
+// Enough for the note *and* the command that reads what the note is about. It
+// said only that something had been withheld, and nothing anywhere - not the
+// skills, not the docs - said how to see it. A turn that reports a thing the
+// reader cannot reach is how an agent ends up inventing its own way in.
+const NOTE_RESERVE = 80;
+const FENCE = "```";
+// A peer cannot close a block it cannot name. The fence carries a marker that
+// is stripped from peer content, so forged delimiters stay inside the block.
+const BLOCK = "acc-peer-message";
+
+const bytes = value => Buffer.byteLength(value, "utf8");
+
+// Written from char codes rather than a literal class: an escaped control
+// range in a regex literal is corrupted silently by editors and patches, and a
+// corrupted range fails open.
+const CONTROL_CHARACTERS = new RegExp(
+  `[${String.fromCharCode(0)}-${String.fromCharCode(8)}`
+  + `${String.fromCharCode(11)}-${String.fromCharCode(31)}${String.fromCharCode(127)}]`, "g");
+
+/**
+ * Render peer-controlled text as displayable data.
+ *
+ * Two separate jobs. Control sequences become visible escapes, so a message
+ * cannot repaint or retitle the human's terminal. Fence markers are stripped,
+ * so a message cannot break out of its own data block and continue as if ACC
+ * had written the following lines.
+ */
+function escapePeerText(value) {
+  return String(value)
+    .replaceAll(new RegExp(`${FENCE}${BLOCK}`, "g"), `'${FENCE}${BLOCK}`)
+    .replaceAll(FENCE, `'${FENCE}`)
+    .replace(CONTROL_CHARACTERS,
+      character => `\\u${character.codePointAt(0).toString(16).padStart(4, "0")}`);
+}
+
+function truncate(line, limit) {
+  if (bytes(line) <= limit) return line;
+  let cut = line;
+  while (bytes(`${cut}…`) > limit && cut.length > 0) cut = cut.slice(0, -1);
+  return `${cut}…`;
+}
+
+/**
+ * An attention line an agent can act on without a round trip.
+ *
+ * `- [task_unblocked] Tank sinks through mud` says work is waiting and does not
+ * say which work. The commands that take it - `acc task --take --task <id>` -
+ * all need the id, and the only other place it appears is `acc sync --json`. An
+ * agent that is told to act and not told on what improvises, which in this
+ * project has already meant one hand-editing the store rather than admitting it
+ * could not name the task.
+ *
+ * Every kind carries such an id and every one is the argument to a command:
+ * a message to `acc ack --message`, a task to `acc task --task`, a claim to
+ * `acc release --claim`. So they are all shown, not only the ones that happened
+ * to be noticed first.
+ */
+function attentionLines(attention) {
+  return attention.map(item => (typeof item.sourceId === "string" && item.sourceId !== ""
+    ? `- [${item.kind}] ${item.sourceId} ${item.summary}`
+    : `- [${item.kind}] ${item.summary}`));
+}
+
+/**
+ * Claims other sessions hold, and whether this session can be stopped from
+ * breaking them.
+ *
+ * Ranked with the required lines rather than the roster, because a claim is
+ * what changes what this session should do next. When it cannot be enforced -
+ * a model that edits through the shell, an MCP client with no hooks - saying so
+ * is the whole mitigation: ACC will not intercept the write, so respecting the
+ * claim is this session's own responsibility and it needs to know that.
+ */
+function claimNote(claim) {
+  // Enforcement is declared per claim, and the guard only ever blocks a guarded
+  // one. Reading this session's capability alone would announce a block that
+  // will never happen, on a claim whose owner explicitly did not ask for one.
+  if (claim.enforcement !== "guarded") {
+    return " - advisory; nothing will stop you, the owner is asking";
+  }
+  if (claim.enforceable === false) {
+    return " - not enforced for this session; do not edit it";
+  }
+  // Guarded, and this session can be stopped - but only on a file edit. No
+  // harness intercepts a shell command, so an edit made through one goes
+  // through whatever the claim says, and a session told merely "this is
+  // claimed" would reasonably assume otherwise.
+  return " - file edits are blocked; edits made through a shell are not";
+}
+
+function claimLines(claims) {
+  return claims.map(claim => {
+    const owner = claim.ownerParticipantId ?? claim.ownerSessionId ?? "another session";
+    return `- [claim] ${claim.resource} held by ${owner}${claimNote(claim)}`;
+  });
+}
+
+/**
+ * One group per message, never a flat list of lines.
+ *
+ * A block that the budget cuts in half is worse than a block that was left out:
+ * the fence never closes, and everything after it reads as ACC's own words
+ * rather than as a peer's. So a message is included whole or not at all.
+ *
+ * The id is carried because the reader needs it to acknowledge the message, and
+ * because the caller needs it to tell which messages actually reached the model
+ * before recording any of them as delivered. Ids, session ids and types are
+ * generated or schema-validated; only the subject and body are peer-authored,
+ * and only those are escaped.
+ */
+function peerBlocks(messages) {
+  return messages.map(message => [
+    `${FENCE}${BLOCK}`,
+    `id ${message.messageId} | from ${message.fromSessionId} | type ${message.type}`
+    + " | untrusted peer message",
+    escapePeerText(message.subject),
+    escapePeerText(message.body),
+    FENCE,
+  ]);
+}
+
+/**
+ * Project a SyncResult into bounded text for one adapter to inject.
+ *
+ * Priority is fixed: direct requests and conflicts first, roster detail last,
+ * because the budget is spent from the bottom. Whatever is dropped is counted
+ * rather than silently removed - a projection that hides its own omissions is
+ * how an agent ends up confidently unaware.
+ */
+export function projectContext(sync, { budgetBytes = DEFAULT_BUDGET_BYTES } = {}) {
+  const attention = [...(sync.attention ?? [])]
+    .sort((left, right) => left.priority - right.priority
+      || left.sourceId.localeCompare(right.sourceId));
+  const messages = sync.messages ?? [];
+  // Who is here, which is not the same as who has ever been here. The roster
+  // keeps closed sessions - `sync` needs them to decide what a cursor has missed
+  // - and a turn that lists them says "3 session(s)" for two participants, one
+  // of them shown twice with contradictory presence. Left alone it also grows
+  // without limit: every session ever opened would take a line out of the
+  // context budget, crowding out messages actually addressed to the reader.
+  // Stale stays: a session that crashed holding a claim is very much news.
+  const roster = (sync.roster ?? []).filter(item => item.presence !== "offline");
+  const claims = sync.claims ?? [];
+
+  // Every entry is a group that appears whole or not at all. Single-line groups
+  // may still be truncated - there is no fence in them to leave open.
+  const required = [
+    ...attentionLines(attention).map(line => [line]),
+    ...claimLines(claims).map(line => [line]),
+    ...peerBlocks(messages),
+  ];
+  // Solo costs nothing: a lone session pays no visible price, and "no peers" is
+  // still a cost when injected into every turn. But this is decided after the
+  // required lines are built, not before - a message already addressed to you,
+  // or a claim you could break, is not nothing, and returning early swallowed
+  // exactly the things worth saying to someone working alone.
+  if (sync.solo === true && required.length === 0) return "";
+
+  // Named by participant, because that is what another agent addresses work to
+  // - a session id cannot be used with `--to`. The branch says where they are,
+  // which is how a workspace spanning several worktrees stays legible.
+  const optional = roster.map(item => {
+    const who = item.participantId ?? item.sessionId;
+    const place = item.branch === null || item.branch === undefined
+      ? ""
+      : ` on ${item.branch}`;
+    return `- ${who}${place} (${item.harness}, ${item.presence})`;
+  });
+
+  const header = `${roster.length} session(s); cursor ${sync.cursor}`;
+  const lines = [header];
+  let used = bytes(header);
+
+  // Reserved so the note below always fits. Without it the projection could run
+  // out of room to say that it ran out of room.
+  const ceiling = budgetBytes - NOTE_RESERVE;
+  let dropped = 0;
+  for (const group of required) {
+    if (group.length === 1) {
+      const candidate = truncate(group[0], Math.max(0, ceiling - used - 1));
+      if (candidate === "" || used + bytes(candidate) + 1 > ceiling) { dropped += 1; continue; }
+      lines.push(candidate);
+      used += bytes(candidate) + 1;
+      continue;
+    }
+    const size = group.reduce((total, line) => total + bytes(line) + 1, 0);
+    // Skipped rather than stopped at: the groups are ordered by priority, and a
+    // large message must not hide the shorter ones behind it.
+    if (used + size > ceiling) { dropped += 1; continue; }
+    lines.push(...group);
+    used += size;
+  }
+  if (dropped > 0) {
+    const note = `- +${dropped} not shown, over budget; read them with `
+      + "`acc sync --scope full --json`";
+    lines.push(note);
+    used += bytes(note) + 1;
+  }
+
+  let shown = 0;
+  for (const line of optional) {
+    if (used + bytes(line) + 1 > budgetBytes - 16) break;
+    lines.push(line);
+    used += bytes(line) + 1;
+    shown += 1;
+  }
+  if (shown < optional.length) {
+    const note = `- +${optional.length - shown} more`;
+    if (used + bytes(note) + 1 <= budgetBytes) lines.push(note);
+  }
+
+  return lines.join("\n");
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/events.mjs

@@ -0,0 +1,55 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+// The shape every adapter normalises to. Kept here rather than in each adapter
+// so the four cannot drift: a consumer that has to ask which adapter produced an
+// event is a consumer that will eventually get it wrong.
+export const NORMALIZED_EVENT_KEYS = Object.freeze(["kind", "sessionId", "cwd", "model",
+  "parentSessionId", "tool", "targets"]);
+
+export const EVENT_KINDS = Object.freeze(["sessionStart", "sessionEnd", "heartbeat",
+  "beforeTurn", "beforeTool", "afterTool", "turnEnd", "childStart", "childEnd", "other"]);
+
+const data = (message, details) => {
+  throw new AccError(EXIT.DATA, message, details);
+};
+
+/**
+ * Build a normalised hook event.
+ *
+ * `targets` is the list of paths the call would write. It is a resource
+ * identifier, not conversation content: without it a guard has nothing to
+ * compare against a claim, and a declared write guard protects nothing. What is
+ * deliberately *not* here is the file's contents, the command text, the prompt
+ * and the transcript path - all of which the harnesses hand to hooks, and none
+ * of which ACC needs.
+ *
+ * A call whose targets cannot be determined declares none. Guessing a path from
+ * a shell command would produce a guard that is wrong in both directions: it
+ * would block work it has no claim over and miss writes it does.
+ */
+export function normalizedEvent(fields) {
+  for (const key of Object.keys(fields)) {
+    if (!NORMALIZED_EVENT_KEYS.includes(key)) {
+      data(`unknown normalised event field: ${key}`, { key });
+    }
+  }
+  const { kind, sessionId, cwd, model = null, parentSessionId = null, tool = null,
+    targets = [] } = fields;
+
+  if (!EVENT_KINDS.includes(kind)) data("unknown normalised event kind", { kind });
+  if (typeof sessionId !== "string" || sessionId === "") {
+    data("normalised event has no session id", { kind });
+  }
+  if (typeof cwd !== "string" || cwd === "") {
+    data("normalised event has no working directory", { kind });
+  }
+  if (!Array.isArray(targets)) data("normalised event targets must be an array", { kind });
+  for (const target of targets) {
+    if (typeof target !== "string" || target === "") {
+      data("normalised event target must be a non-empty string", { kind, target });
+    }
+  }
+
+  return Object.freeze({ kind, sessionId, cwd, model, parentSessionId, tool,
+    targets: Object.freeze([...targets]) });
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/hook-shim.mjs

@@ -0,0 +1,148 @@
+import { access, chmod, mkdir, readFile, readdir, rm, writeFile }
+  from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+/**
+ * Where the hook runtime lives, resolved from this package rather than looked
+ * up on PATH. A hook's environment does not reliably carry the user's PATH, and
+ * a command that cannot be found fails silently on every event.
+ */
+/**
+ * The hook runner, found rather than counted to.
+ *
+ * `../../../bin/acc-hook.mjs` is the answer in a development checkout and only
+ * there. Published, this module sits at
+ * `<package>/node_modules/@agents-can-communicate/adapter-sdk/src/`, which is one
+ * level deeper, so the path resolved to `node_modules/bin/acc-hook.mjs` and
+ * every install refused: `the hook runner does not exist`, for every client on
+ * the machine, from a clean `npm install` of the package.
+ *
+ * Nothing caught it. `acc install` exited 0 with the failures counted in a line
+ * that began with a success, and the release check threw that output away - so
+ * the gate reported PASS on a package whose main command could not run.
+ *
+ * Walking up for it holds in both layouts and in whatever a future one is: the
+ * nearest `bin/acc-hook.mjs` above this file is the one that belongs to this
+ * copy of the package.
+ */
+export const defaultRunner = () => {
+  let directory = fileURLToPath(new URL(".", import.meta.url));
+  for (;;) {
+    const candidate = path.join(directory, "bin", "acc-hook.mjs");
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(directory);
+    // Reached the root without finding one. The development answer is returned
+    // so the refusal that follows names a path a reader can recognise.
+    if (parent === directory) {
+      return fileURLToPath(new URL("../../../bin/acc-hook.mjs", import.meta.url));
+    }
+    directory = parent;
+  }
+};
+
+export const runnerExists = async runner => {
+  try {
+    await access(runner);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export async function assertRunner(runner) {
+  if (!await runnerExists(runner)) {
+    throw new AccError(EXIT.DATA,
+      "refusing to install: the hook runner does not exist", { runner });
+  }
+  return runner;
+}
+
+// What the shipped skill carries where the runnable command belongs.
+const PLACEHOLDER = "{{ACC}}";
+
+// Shell metacharacters in a path are the caller's problem to survive, not the
+// shell's to interpret.
+const quote = value => `"${String(value).replace(/(["\\$`])/g, "\\$1")}"`;
+
+/**
+ * Write the small shim a client's hook command points at.
+ *
+ * Clients disagree about how a hook command may be written - some expand a
+ * plugin-root variable, some demand an absolute path, one has no variable at
+ * all - but every one of them can run a shell script. The shim absorbs that
+ * difference and pins the interpreter and the runner to absolute paths at
+ * install time.
+ */
+export async function writeHookShim({ dir, adapterId, runner = defaultRunner(),
+  node = process.execPath, name = "acc-hook.sh" }) {
+  await assertRunner(runner);
+  const target = path.join(dir, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(target, [
+    "#!/bin/sh",
+    "# Generated by ACC at install time. The paths are pinned deliberately:",
+    "# a hook runs with an environment that may carry neither PATH nor a shell",
+    "# profile, and a command that cannot be found fails silently on every event.",
+    `exec ${quote(node)} ${quote(runner)} ${adapterId} "$@"`,
+    "",
+  ].join("\n"));
+  await chmod(target, 0o755);
+  return target;
+}
+
+/**
+ * Remove a directory this adapter installed, unless it has been kept back.
+ *
+ * The installer decides what may be deleted by comparing what is on disk
+ * against what ACC recorded writing. An adapter that removed its layout
+ * unconditionally would undo that decision - and the case it undoes is exactly
+ * the one that matters: someone put their own work inside a directory ACC
+ * created, and a recognised path is not a reason to delete it.
+ */
+export async function removeInstalledTree(target, keep = []) {
+  if (keep.includes(target)) return false;
+  await rm(target, { recursive: true, force: true });
+  return true;
+}
+
+/** Where the CLI lives, resolved from this package rather than from PATH. */
+export const defaultCli = () =>
+  fileURLToPath(new URL("../../../bin/acc.mjs", import.meta.url));
+
+/**
+ * Bake the runnable command into the skill this adapter installs.
+ *
+ * The skill is what tells an agent how to coordinate, and it used to say `acc`.
+ * A hook never depends on PATH - its command is pinned at install time - but the
+ * skill did, and on a machine where the package is not installed globally the
+ * word `acc` runs nothing.
+ *
+ * A model that cannot run the command does not stop. Observed on a real Claude
+ * Code session: told to take a task and finding no `acc`, it read the store's
+ * JSON, worked out the schema, and wrote records and events by hand - inventing
+ * an event type, a harness name, and its own generation tokens. So the command
+ * is pinned here for the same reason it is pinned in the shim.
+ */
+export async function bakeSkillCommand({ root, node = process.execPath,
+  cli = defaultCli() }) {
+  const command = `${quote(node)} ${quote(cli)}`;
+  const baked = [];
+  const walk = async directory => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) await walk(full);
+      else if (entry.name === "SKILL.md") {
+        const text = await readFile(full, "utf8");
+        if (!text.includes(PLACEHOLDER)) continue;
+        await writeFile(full, text.replaceAll(PLACEHOLDER, command));
+        baked.push(full);
+      }
+    }
+  };
+  await walk(root);
+  return baked;
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/index.mjs

@@ -0,0 +1,16 @@
+// Capability contract, context projection, config ownership, and the binding
+// that survives between two ephemeral hook processes.
+export { CAPABILITY_SHAPE, assertCapabilities, defineAdapter } from "./capabilities.mjs";
+export { EVENT_KINDS, NORMALIZED_EVENT_KEYS, normalizedEvent } from "./events.mjs";
+export { assertRunner, bakeSkillCommand, defaultCli, defaultRunner, removeInstalledTree,
+  runnerExists, writeHookShim }
+  from "./hook-shim.mjs";
+export { BEGIN, END, removeTomlBlock, renderBlock, stripBlock, tomlString, writeTomlBlock }
+  from "./toml-block.mjs";
+export { projectContext } from "./context-projector.mjs";
+export { formatJsonAs, jsonStyleOf, mergeOwnedConfig, mergeOwnedEntries, ownedEntries, ownedKeys,
+  acccreatedFile, removeIfEmpty, removeOwnedConfig, removeOwnedEntries, writeForeignJson,
+  blankJson, blankText } from "./config-merge.mjs";
+export { clearSessionBinding, listSessionBindings, loadSessionBinding,
+  storeSessionBinding }
+  from "./session-binding.mjs";

package/node_modules/@agents-can-communicate/adapter-sdk/src/session-binding.mjs

@@ -0,0 +1,95 @@
+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;
+
+// Harness session ids are foreign input of unknown shape. Hashing them makes
+// the filename safe by construction rather than by sanitising, so no id can
+// select which file is written.
+const fileFor = (runtimeDir, harnessSessionId) => path.join(runtimeDir, "bindings",
+  `${createHash("sha256").update(String(harnessSessionId)).digest("hex").slice(0, 32)}.json`);
+
+/**
+ * Hook executables are ephemeral: the process that attaches is gone by the time
+ * the next hook fires. The binding is what lets a later hook heartbeat and
+ * detach the exact generation instead of opening a second session.
+ *
+ * It lives in the runtime directory, never the project, and carries identity
+ * only - no prompt, no transcript, no harness state.
+ */
+export async function storeSessionBinding({ runtimeDir, harnessSessionId, accSessionId,
+  generation }) {
+  const file = fileFor(runtimeDir, harnessSessionId);
+  await mkdir(path.dirname(file), { recursive: true });
+  const record = { schemaVersion: SCHEMA_VERSION, harnessSessionId, accSessionId, generation };
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  // Replace rather than append: re-attaching supersedes the old generation, and
+  // two live bindings for one harness session would be worse than none.
+  await rename(temporary, file);
+}
+
+export async function loadSessionBinding({ runtimeDir, harnessSessionId }) {
+  const file = fileFor(runtimeDir, harnessSessionId);
+  let source;
+  try {
+    source = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  let record;
+  try {
+    record = JSON.parse(source);
+  } catch (error) {
+    // Returning null here would make the hook silently open a second session
+    // and orphan the first. Failing closed is the honest outcome.
+    throw new AccError(EXIT.DATA, "session binding is not valid JSON",
+      { file, cause: error.message });
+  }
+  if (record?.schemaVersion !== SCHEMA_VERSION) {
+    throw new AccError(EXIT.DATA, "unknown session binding schemaVersion",
+      { file, schemaVersion: record?.schemaVersion });
+  }
+  return { accSessionId: record.accSessionId, generation: record.generation };
+}
+
+export async function clearSessionBinding({ runtimeDir, harnessSessionId }) {
+  await rm(fileFor(runtimeDir, harnessSessionId), { force: true });
+}
+
+/**
+ * Every binding in this workspace, whole.
+ *
+ * `loadSessionBinding` answers "which session is *this* harness session", which
+ * needs the harness id up front. The CLI has the opposite problem: an agent runs
+ * `acc work` from a shell that was never told any id, so the question is which
+ * of the live bindings is the one that spawned it.
+ *
+ * A file that cannot be read is skipped rather than fatal - the caller is trying
+ * to identify itself among several, and one unreadable neighbour should not stop
+ * it recognising its own.
+ */
+export async function listSessionBindings({ runtimeDir }) {
+  const dir = path.join(runtimeDir, "bindings");
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const bindings = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const record = await readFile(path.join(dir, name), "utf8")
+      .then(JSON.parse).catch(() => null);
+    if (record?.schemaVersion !== SCHEMA_VERSION) continue;
+    bindings.push({ harnessSessionId: record.harnessSessionId,
+      accSessionId: record.accSessionId, generation: record.generation });
+  }
+  return bindings;
+}

package/node_modules/@agents-can-communicate/adapter-sdk/src/toml-block.mjs

@@ -0,0 +1,71 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// Two clients keep configuration ACC must add to in TOML, and ACC ships without
+// dependencies. Parsing and re-emitting the file would mean writing a TOML
+// round-tripper and losing the user's comments and formatting to it. Instead ACC
+// owns a delimited region and never reads the rest: install replaces the region,
+// uninstall deletes it, and everything outside comes back byte for byte.
+export const BEGIN = "# >>> agents-can-communicate (managed; edits here are overwritten)";
+export const END = "# <<< agents-can-communicate";
+
+/**
+ * Remove ACC's region and nothing else.
+ *
+ * Written to survive a file with no block, several blocks, or a block the user
+ * has half-deleted: an unterminated marker consumes to end of file rather than
+ * leaving stray table headers behind, which would fail the client's schema and
+ * lock the user out of their own tool.
+ */
+export function stripBlock(source) {
+  const kept = [];
+  let inside = false;
+  for (const line of source.split("\n")) {
+    if (line.trimEnd() === BEGIN) { inside = true; continue; }
+    if (inside) {
+      if (line.trimEnd() === END) inside = false;
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+export const renderBlock = body => [BEGIN, ...body, END].join("\n");
+
+// TOML basic strings take backslash escapes. A path is user-controlled input, so
+// it is escaped rather than trusted to be boring.
+export const tomlString = value =>
+  `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+/**
+ * Replace ACC's region in a TOML file, creating the file if needed.
+ *
+ * The block goes at the end because a table header there closes whatever table
+ * preceded it: appended anywhere else, the user's last section would swallow
+ * ACC's keys.
+ */
+export async function writeTomlBlock(file, body) {
+  const existing = await readFile(file, "utf8").catch(error => {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  });
+  const withoutOurs = stripBlock(existing);
+  const separator = withoutOurs === "" || withoutOurs.endsWith("\n") ? "" : "\n";
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${withoutOurs}${separator}${renderBlock(body)}\n`);
+  return file;
+}
+
+/** Remove ACC's region, reporting whether anything was there. */
+export async function removeTomlBlock(file) {
+  const existing = await readFile(file, "utf8").catch(error => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (existing === null) return false;
+  const stripped = stripBlock(existing);
+  if (stripped === existing) return false;
+  await writeFile(file, stripped);
+  return true;
+}

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

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