agents-can-communicate 0.1.0

package/node_modules/@agents-can-communicate/cli/src/args.mjs

@@ -0,0 +1,163 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+// Commands the model is offered stay few and high level; attach, heartbeat, and
+// detach exist for adapters and are deliberately not advertised as model tools.
+//
+// `--session` and `--generation` are optional on every agent-facing command:
+// the CLI works out which session is calling it (see session-owner.mjs). They
+// stay accepted because an adapter, a script, or an agent holding a session id
+// from `acc status --json` has a reason to be explicit. They remain required on
+// attach, heartbeat and detach, which are the adapter's own lifecycle calls.
+export const COMMANDS = Object.freeze({
+  attach: { required: ["participant"], optional: ["harness", "cadence", "parent", "session"] },
+  heartbeat: { required: ["session", "generation"], optional: [] },
+  detach: { required: ["session", "generation"], optional: [] },
+  sync: { required: [], optional: ["session", "cursor", "limit", "scope"] },
+  work: { required: [], optional: ["session", "generation", "summary", "mode",
+    "state", "workstream"], repeated: ["hint"], flags: ["clear"] },
+  claim: { required: ["resource"],
+    optional: ["session", "generation", "mode", "enforcement", "reason", "lease"] },
+  release: { required: ["claim"],
+    optional: ["session", "generation", "authority", "reason"] },
+  message: { required: ["subject", "body"],
+    optional: ["session", "generation", "type", "priority", "workstream"],
+    repeated: ["to"], flags: ["requires-ack"] },
+  // Asking another agent to do something: one call, because a task nobody was
+  // told about and a message pointing at no task are each useless.
+  request: { required: ["to", "title"],
+    optional: ["session", "generation", "detail", "workstream", "priority"],
+    repeated: ["depends-on"] },
+  // Create a task, or act on one with --task. A workstream is optional: small
+  // requests should not have to invent a project first.
+  task: { required: [], optional: ["session", "generation", "workstream", "title",
+    "detail", "assignee", "state", "task", "reason"],
+    repeated: ["depends-on"], flags: ["take", "decline", "force"] },
+  // Create one, or take and hand back the coordination of one that exists.
+  // Creating a workstream raised `coordinator_missing` on every turn from then
+  // on, and nothing could answer it: the two core operations that do had no
+  // surface at all.
+  workstream: { required: [], optional: ["session", "generation", "title", "objective",
+    "workstream"], flags: ["take", "release"] },
+  // Messages not tied to a task need a way to be answered too. Without one a
+  // `requiresAck` message raised an attention item nothing could ever clear.
+  ack: { required: ["message"], optional: ["session", "generation", "state"] },
+  // Recording what was settled, so the next session does not reopen it. The
+  // protocol has described this object from the start and nothing could make
+  // one: no command, no tool.
+  decide: { required: ["title", "outcome"],
+    optional: ["session", "generation", "authority", "workstream", "supersedes"],
+    repeated: ["decided-by"], flags: ["human"] },
+  finish: { required: ["goal"], optional: ["session", "generation", "status", "to"],
+    repeated: ["completed", "remaining", "blocker"] },
+  status: { required: [], optional: ["participant"], flags: ["all"] },
+  doctor: { required: [], optional: ["home"], flags: ["repair"] },
+  // The one command with a subcommand. Kept as an explicit list rather than a
+  // free positional: `acc config delete` should fail at the parser, not deep
+  // inside a handler that has already decided what to do.
+  config: { required: [], optional: [], flags: ["yes", "force"],
+    subcommands: ["init", "validate"] },
+  install: { required: [], optional: ["adapter", "home"], flags: ["dry-run", "yes"] },
+  uninstall: { required: [], optional: ["adapter", "home"], flags: ["yes"] },
+  // The two things a person types first after installing from a registry. The
+  // CLI answered neither: `acc --version` and `acc --help` were both "unknown
+  // command", and `acc` on its own asked for a command without naming one.
+  help: { required: [], optional: [] },
+  version: { required: [], optional: [] },
+});
+
+// Spelled as the commands they mean, and only in first position. A message body
+// legitimately begins with "--" - exchanging diffs is the point of this tool -
+// so reading them anywhere in the argv would make `acc message --body "--help"`
+// print the help instead of sending it.
+const ALIASES = Object.freeze({ "--help": "help", "-h": "help",
+  "--version": "version", "-v": "version", "-V": "version" });
+
+const GLOBAL = Object.freeze(["json", "workspace", "cwd"]);
+
+function usage(message, details = {}) {
+  throw new AccError(EXIT.USAGE, message, details);
+}
+
+const camel = name => name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+
+export function parseArgs(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    usage("a command is required - `acc help` lists them");
+  }
+  const [first, ...rest] = argv;
+  const command = ALIASES[first] ?? first;
+  const spec = COMMANDS[command];
+  if (spec === undefined) {
+    usage(`unknown command: ${command} - \`acc help\` lists them`, { command });
+  }
+
+  let tokens = rest;
+  let subcommand;
+  if (spec.subcommands !== undefined) {
+    [subcommand, ...tokens] = rest;
+    if (subcommand === undefined || !spec.subcommands.includes(subcommand)) {
+      usage(`${command} requires one of: ${spec.subcommands.join(", ")}`,
+        { command, subcommand: subcommand ?? null });
+    }
+  }
+
+  const repeated = new Set(spec.repeated ?? []);
+  const flags = new Set([...(spec.flags ?? []), "json"]);
+  const known = new Set([...(spec.required ?? []), ...(spec.optional ?? []),
+    ...repeated, ...(spec.flags ?? []), ...GLOBAL]);
+  const options = {};
+
+  // Free-text values legitimately start with "--": a message body carrying a
+  // diff begins "--- a/file", and agents exchanging evidence is the point of
+  // this tool. So a following token is only treated as a missing value when it
+  // names a real option of this command, which still catches the actual typo
+  // (--subject --body x). --name=value is the unambiguous form for the rest.
+  const looksLikeOption = value => typeof value === "string" && value.startsWith("--")
+    && known.has(value.slice(2).split("=", 1)[0]);
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token.startsWith("--") || token.length === 2) usage(`unexpected argument: ${token}`);
+    const separator = token.indexOf("=");
+    const name = separator === -1 ? token.slice(2) : token.slice(2, separator);
+    const inline = separator === -1 ? undefined : token.slice(separator + 1);
+    if (!known.has(name)) usage(`unknown option for ${command}: --${name}`, { command, name });
+    const key = camel(name);
+
+    if (flags.has(name)) {
+      if (inline !== undefined) usage(`option --${name} does not take a value`);
+      if (Object.hasOwn(options, key)) usage(`option --${name} may be used only once`);
+      options[key] = true;
+      continue;
+    }
+
+    let value = inline;
+    if (value === undefined) {
+      const next = tokens[index + 1];
+      if (next === undefined || looksLikeOption(next)) {
+        usage(`option --${name} requires a value`);
+      }
+      value = next;
+      index += 1;
+    }
+    if (value === "") usage(`option --${name} requires a value`);
+    if (repeated.has(name)) (options[key] ??= []).push(value);
+    else if (Object.hasOwn(options, key)) usage(`option --${name} may be used only once`);
+    else options[key] = value;
+  }
+
+  for (const name of spec.required ?? []) {
+    if (!Object.hasOwn(options, camel(name))) {
+      usage(`${command} requires --${name}`, { command, option: name });
+    }
+  }
+  return { command, options: subcommand === undefined ? options : { ...options, subcommand } };
+}
+
+export function positiveNumber(value, name) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    usage(`--${name} must be a positive number`, { value });
+  }
+  return parsed;
+}

package/node_modules/@agents-can-communicate/cli/src/claim-spelling.mjs

@@ -0,0 +1,79 @@
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT, normaliseResource } from "@agents-can-communicate/protocol";
+
+/**
+ * The spelling the filesystem itself uses.
+ *
+ * `normaliseResource` settles `./`, `//` and `..`, which is all a string can
+ * settle. Letter case it cannot: on the filesystem this project is certified on,
+ * `src/Physics.mjs` and `src/physics.mjs` are the same file, and a claim on one
+ * did not cover a write to the other. Measured - the claim was taken, `acc
+ * status` said `protection guarded`, and the write went through.
+ *
+ * Asking the filesystem answers it on both kinds of machine at once, with no
+ * case rule anywhere: macOS `realpath` returns the name as stored, so both
+ * spellings arrive at the same resource, and on Linux they are genuinely two
+ * files and stay two resources. The guard canonicalises its targets the same
+ * way, so the two sides meet.
+ *
+ * The path usually does not exist yet - claiming before creating is the point -
+ * so the deepest existing ancestor is resolved and the rest appended.
+ */
+async function onDisk(absolute) {
+  let current = absolute;
+  const trailing = [];
+  for (;;) {
+    try {
+      return path.join(await realpath(current), ...trailing);
+    } catch (error) {
+      if (error.code !== "ENOENT" && error.code !== "ENOTDIR") return absolute;
+      const parent = path.dirname(current);
+      if (parent === current) return absolute;
+      trailing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+const GLOB = "/**";
+
+/**
+ * A `file:` claim, spelled the way the project spells it. Anything the
+ * filesystem cannot answer for - another scheme, a path outside the workspace -
+ * comes back as it went in rather than being invented into something else.
+ */
+export async function canonicalClaim(resource, descriptor) {
+  const normalised = normaliseResource(resource);
+  if (typeof normalised !== "string" || !normalised.startsWith("file:")) return normalised;
+  const root = descriptor?.source === "git" && descriptor.git !== undefined
+    ? descriptor.git.worktreeRoot
+    : descriptor?.roots?.[0];
+  if (typeof root !== "string") return normalised;
+
+  const rest = normalised.slice("file:".length);
+  const glob = rest.endsWith(GLOB);
+  const body = glob ? rest.slice(0, -GLOB.length) : rest;
+  if (body === "") return normalised;
+
+  const resolved = await onDisk(path.resolve(root, body));
+  // A directory claimed without the glob covers exactly itself, which is to say
+  // nothing anyone writes. Saying so beats storing a claim that reads like
+  // protection and is not.
+  //
+  // The protocol refuses the shapes a string alone can condemn - a trailing
+  // slash, a `*` that is not the understood glob - so that a surface with no
+  // filesystem still refuses them. This is the half only the filesystem knows:
+  // whether `file:src` happens to be a directory.
+  if (!glob && await stat(resolved).then(entry => entry.isDirectory(), () => false)) {
+    throw new AccError(EXIT.USAGE,
+      `${normalised} is a directory; claim ${normalised}/** to cover what is in it`,
+      { resource });
+  }
+  const relative = path.relative(await onDisk(root), resolved);
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return normalised;
+  }
+  return `file:${relative.split(path.sep).join("/")}${glob ? GLOB : ""}`;
+}

package/node_modules/@agents-can-communicate/cli/src/config-command.mjs

@@ -0,0 +1,149 @@
+import { constants } from "node:fs";
+import { open, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, CONFIG_FILENAME, EXIT, createId, defaultProjectConfig,
+  validateProjectConfig } from "@agents-can-communicate/protocol";
+
+const configPathIn = cwd => path.join(cwd, CONFIG_FILENAME);
+
+/**
+ * The file `init` would write, rendered once and used for both the preview and
+ * the write. Rendering twice invites a preview that differs from what lands,
+ * which is worse than showing nothing.
+ */
+function renderConfig({ displayName, ids }) {
+  return `${JSON.stringify({
+    schemaVersion: 1,
+    // Generated rather than derived from the path: the whole point of writing
+    // this file is an identity that survives the directory being moved,
+    // renamed, or cloned somewhere else.
+    workspaceId: ids.next("workspace"),
+    displayName,
+    roots: ["."],
+    policy: { claimMode: "advisory", contextBudgetBytes: 6000 },
+    requiredAdapters: [],
+  }, null, 2)}\n`;
+}
+
+async function readConfig(cwd) {
+  const file = configPathIn(cwd);
+  let handle;
+  try {
+    // Same rule as discovery: a config reached through a symlink may point
+    // anywhere, so it is refused rather than followed.
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new AccError(EXIT.DATA, "cannot safely read the workspace config",
+      { file, cause: error.message });
+  }
+  try {
+    return JSON.parse(await handle.readFile("utf8"));
+  } catch (error) {
+    throw new AccError(EXIT.DATA, "the workspace config is not valid JSON",
+      { file, cause: error.message });
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Sessions that would stop seeing each other the moment this file lands.
+ *
+ * The config carries its own `workspaceId`, so writing one moves the project to
+ * a new workspace. Sessions attached to the old one keep heartbeating it and
+ * vanish from everyone else's roster - measured: `1 live` before, `0 live`
+ * after. They do not recover on their own either: a session re-attaches at
+ * SessionStart and at nothing else, so the client has to be restarted.
+ *
+ * A coordination tool that silently stops coordinating is the worst way for
+ * this to be found, so it is refused unless the caller says to go ahead.
+ */
+async function attachedSessions(probeWorkspace) {
+  if (typeof probeWorkspace !== "function") return [];
+  try {
+    const context = await probeWorkspace();
+    const status = await context.service.collectStatus({});
+    return status.participants.filter(item => item.presence !== "offline");
+  } catch {
+    // Nothing to warn about if the workspace cannot be opened at all - and this
+    // command must still run on a workspace ACC cannot read, which is half of
+    // what it is for.
+    return [];
+  }
+}
+
+async function initConfig({ cwd, interactive, yes, confirm, ids, displayName,
+  force = false, probeWorkspace }) {
+  const file = configPathIn(cwd);
+  if (await readConfig(cwd) !== null) {
+    // A committed identity is shared by everyone on the project. Replacing it
+    // on a mistyped command would split one workspace into two.
+    throw new AccError(EXIT.CONFLICT, `${CONFIG_FILENAME} already exists`, { file });
+  }
+
+  const attached = await attachedSessions(probeWorkspace);
+  if (attached.length > 0 && !force) {
+    const who = attached.map(item => `${item.participantId} (${item.harness})`).join(", ");
+    throw new AccError(EXIT.CONFLICT,
+      `${attached.length} session(s) are attached here and would stop seeing each `
+      + `other: ${who}. They re-attach only when their client starts, so close them `
+      + "first, or pass --force to write anyway.",
+      { file, sessions: attached.map(item => item.sessionId) });
+  }
+
+  const preview = renderConfig({ ids, displayName: displayName ?? path.basename(cwd) });
+
+  if (!yes) {
+    if (!interactive) {
+      throw new AccError(EXIT.USAGE,
+        "refusing to write without confirmation; pass --yes in a non-interactive run",
+        { file });
+    }
+    const approved = await confirm(`write ${file}?\n\n${preview}`);
+    if (!approved) return { subcommand: "init", written: false, file, preview };
+  }
+
+  // Written with O_EXCL: between the existence check and here, another process
+  // may have created the file, and clobbering it would be the same mistake the
+  // check exists to prevent.
+  const handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+  try {
+    await handle.writeFile(preview, "utf8");
+  } finally {
+    await handle.close();
+  }
+  return { subcommand: "init", written: true, file, preview };
+}
+
+async function validateConfig({ cwd }) {
+  const file = configPathIn(cwd);
+  const raw = await readConfig(cwd);
+  if (raw === null) {
+    // Not an error. Config is optional, and the policy that applies without one
+    // is worth reporting rather than leaving the reader to guess.
+    return { subcommand: "validate", valid: true, present: false, file,
+      config: defaultProjectConfig() };
+  }
+  return { subcommand: "validate", valid: true, present: true, file,
+    config: validateProjectConfig(raw, { source: file }) };
+}
+
+/**
+ * `acc config init` and `acc config validate`.
+ *
+ * `init` never writes without agreement: it asks in an interactive run and
+ * demands `--yes` otherwise. `validate` only reads - a command a user runs to
+ * find out what is wrong must not change the thing it is inspecting.
+ */
+export async function runConfigCommand({ subcommand, cwd, interactive = true, yes = false,
+  confirm, displayName, force = false, probeWorkspace,
+  ids = { next: kind => createId(kind) } }) {
+  if (subcommand === "init") {
+    return initConfig({ cwd, interactive, yes, confirm, ids, displayName,
+      force, probeWorkspace });
+  }
+  if (subcommand === "validate") return validateConfig({ cwd });
+  throw new AccError(EXIT.USAGE, `unknown config subcommand: ${subcommand}`, { subcommand });
+}

package/node_modules/@agents-can-communicate/cli/src/doctor-command.mjs

@@ -0,0 +1,85 @@
+import { homedir } from "node:os";
+
+import { detectInstallation, verifyOwned } from "@agents-can-communicate/installer";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { ALL_ADAPTERS, clientContext } from "./install-command.mjs";
+import { platformPaths } from "./platform-paths.mjs";
+import { diagnoseFilesystemStore, repairFilesystemStore }
+  from "@agents-can-communicate/storage-filesystem";
+
+/**
+ * Doctor composes the store's own report with core health rules. Repair fails
+ * closed: anything blocked or corrupt stops the run rather than being repaired
+ * on top of state the tool cannot even read.
+ */
+async function diagnoseAdapters({ options, runtime }) {
+  // The same home `acc install --home` writes to, or the real one. Reading a
+  // different home than install wrote to reports every adapter as missing.
+  const home = options?.home ?? runtime?.env?.HOME ?? homedir();
+  const clients = clientContext(home);
+  const { data: dataHome } = platformPaths({ platform: runtime?.platform,
+    env: runtime?.env ?? {} });
+  const adapters = ALL_ADAPTERS();
+  const detected = await detectInstallation({ adapters, context: clients });
+
+  return Promise.all(detected.map(async entry => {
+    // Compared against what ACC recorded writing, so a plugin someone has since
+    // edited reads as theirs rather than as a healthy ACC install.
+    const owned = await verifyOwned({ dataHome, adapterId: entry.adapterId });
+    const remediation = [];
+    if (entry.present && !entry.installed) {
+      remediation.push(`acc install --adapter ${entry.adapterId}`);
+    }
+    if (owned.modified.length > 0) {
+      remediation.push(`acc install --adapter ${entry.adapterId}  # files were edited`);
+    }
+    if (owned.missing.length > 0) {
+      remediation.push(`acc install --adapter ${entry.adapterId}  # files are missing`);
+    }
+    return { ...entry, owned: { modified: owned.modified, missing: owned.missing,
+      intact: owned.intact.length }, remediation };
+  }));
+}
+
+export async function runDoctor({ options, context, runtime }) {
+  const root = context.paths.root;
+  const report = options.repair === true
+    ? await repairFilesystemStore({ root, clock: context.service.clock })
+    : await diagnoseFilesystemStore({ root });
+  const adapters = await diagnoseAdapters({ options, runtime });
+
+  // Before the store is read for anything else. `collectStatus` reads every
+  // record, so on the store this command exists to describe it threw first and
+  // took the diagnosis with it: one truncated file and `acc doctor` answered
+  // "invalid JSON record", naming nothing, while `inspect` had already found
+  // the file and put it in a list nobody ever saw.
+  if (!report.healthy) {
+    const broken = [...report.blocked, ...report.corrupt];
+    throw new AccError(EXIT.DATA,
+      `store state is ambiguous; repair is blocked. ${broken.length} unreadable:\n  `
+      + `${broken.slice(0, 10).join("\n  ")}`
+      + (broken.length > 10 ? `\n  and ${broken.length - 10} more` : ""),
+      { workspaceId: context.descriptor.id, source: context.descriptor.source,
+        runtimeRoot: root, store: report, adapters,
+        remediation: ["inspect blocked and corrupt paths before repairing"] });
+  }
+
+  const status = await context.service.collectStatus({});
+
+  const data = {
+    workspaceId: context.descriptor.id,
+    source: context.descriptor.source,
+    runtimeRoot: root,
+    materialised: status.materialised,
+    protection: status.protection,
+    store: report,
+    // Capabilities are reported from what is actually installed, never assumed.
+    adapters,
+    remediation: adapters.flatMap(adapter => adapter.remediation),
+  };
+  const installed = adapters.filter(adapter => adapter.installed).length;
+  const text = `store healthy; ${status.counts.live} live session(s); `
+    + `protection ${status.protection}; ${installed} of ${adapters.length} adapter(s) installed`;
+  return { data, text };
+}

package/node_modules/@agents-can-communicate/cli/src/git-probe.mjs

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Git exports GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE and friends into the
+ * environment of everything it runs, hooks included. Inheriting them makes a
+ * probe describe whichever repository invoked us rather than the workspace at
+ * `cwd` - which, during the reconciliation, is exactly how a test suite running
+ * under a pre-push hook mutated the repository it was meant to be testing.
+ * ACC adapters are hook-driven by design, so the default probe strips them.
+ */
+export function hermeticEnv(env = process.env) {
+  return Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("GIT_")));
+}
+
+export function createGitProbe({ run } = {}) {
+  const exec = run ?? (async (cwd, args) =>
+    (await execFileAsync("git", args, { cwd, env: hermeticEnv() })).stdout.trim());
+
+  return async function gitProbe({ cwd }) {
+    const commonDir = await exec(cwd, ["rev-parse", "--path-format=absolute",
+      "--git-common-dir"]);
+    if (typeof commonDir !== "string" || commonDir.length === 0) return null;
+    const worktreeRoot = await exec(cwd, ["rev-parse", "--show-toplevel"]);
+    // A detached head or an unborn branch is normal, not an error: enrichment
+    // reports what exists and leaves the rest null.
+    const branch = await exec(cwd, ["branch", "--show-current"]).catch(() => "");
+    const head = await exec(cwd, ["rev-parse", "HEAD"]).catch(() => "");
+    const remote = await exec(cwd, ["remote", "get-url", "origin"]).catch(() => "");
+    return {
+      commonDir: path.resolve(cwd, commonDir),
+      worktreeRoot: path.resolve(cwd, worktreeRoot),
+      branch: branch.length > 0 ? branch : null,
+      head: head.length > 0 ? head : null,
+      remote: remote.length > 0 ? remote : null,
+    };
+  };
+}

package/node_modules/@agents-can-communicate/cli/src/help.mjs

@@ -0,0 +1,78 @@
+import { COMMANDS } from "./args.mjs";
+
+/**
+ * What `acc` says to a person who has just installed it.
+ *
+ * The list of commands is read from the command table, so a command that exists
+ * is always listed. Only the heading a command sits under and its one line are
+ * written here, and the tests prove both cover every command in the table.
+ *
+ * The required options are deliberately not repeated: the parser already
+ * answers `acc claim` with "claim requires --resource", which is the same
+ * answer at the moment it is actually needed.
+ */
+const GROUPS = Object.freeze([
+  ["Set up", ["install", "uninstall", "doctor", "config"]],
+  ["In a session", ["status", "sync", "work", "claim", "release", "ack", "message",
+    "request", "task", "workstream", "decide", "finish"]],
+  ["Driven by adapters, not by people", ["attach", "heartbeat", "detach"]],
+  ["About acc", ["help", "version"]],
+]);
+
+const SUMMARY = Object.freeze({
+  install: "install adapters for the clients on this machine",
+  uninstall: "remove what acc wrote, keep what you edited",
+  doctor: "clients, versions, install health, and what to run next",
+  config: "write or check acc.workspace.json (init | validate)",
+  status: "who else is here, what they hold, how protected this workspace is",
+  sync: "what has happened since a cursor; silent while you are alone",
+  work: "publish what this session is doing, or --clear when it has stopped",
+  claim: "reserve a resource; exit 5 when someone else already holds it",
+  release: "give a claim back",
+  ack: "answer a message that asked for one, so it stops asking",
+  message: "send a typed message to named participants",
+  request: "ask another agent to do something: the work and the why, in one call",
+  task: "create work, --take it, or move its --state along",
+  workstream: "group related work, and steer it with --take / --release",
+  decide: "record what was settled, so the next session does not reopen it",
+  finish: "write the handoff and release what this session held",
+  attach: "open a session; an adapter calls this, not a person",
+  heartbeat: "say the session is still alive",
+  detach: "close a session",
+  help: "this list",
+  version: "print the version that is installed",
+});
+
+/** The same list `acc help --json` returns, so a tool can read it too. */
+export function describeCommands() {
+  return GROUPS.map(([heading, names]) => ({
+    heading,
+    commands: names.map(name => ({
+      name,
+      summary: SUMMARY[name],
+      required: COMMANDS[name].required ?? [],
+      subcommands: COMMANDS[name].subcommands ?? [],
+    })),
+  }));
+}
+
+const DOCS = "https://github.com/automatis-tools/agents-can-communicate"
+  + "/blob/main/docs/CLI.md";
+
+export function helpText() {
+  const width = Math.max(...Object.keys(COMMANDS).map(name => name.length)) + 4;
+  const lines = ["acc - several agents in one workspace, none of them in charge", ""];
+  for (const { heading, commands } of describeCommands()) {
+    lines.push(heading);
+    for (const { name, summary } of commands) {
+      lines.push(`  ${`acc ${name}`.padEnd(width)}  ${summary}`);
+    }
+    lines.push("");
+  }
+  // A URL rather than a path: only `docs/CAPABILITIES.md` is packed, so a
+  // reference to `docs/CLI.md` would name a file the installed package does not
+  // have. The test alongside holds this to the repository the manifest names.
+  lines.push("Every command takes --json for machine output and --cwd to choose the workspace.",
+    `Full reference: ${DOCS}`);
+  return lines.join("\n");
+}

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

@@ -0,0 +1,10 @@
+// Composition root: discovery, runtime locations, and the CLI surface.
+export { main } from "./main.mjs";
+export { COMMANDS, parseArgs } from "./args.mjs";
+// Exported so a test can hold every adapter to where it plans to write and
+// which binary decides it runs at all.
+export { ALL_ADAPTERS, clientContext } from "./install-command.mjs";
+export { discoverWorkspace } from "./workspace-discovery.mjs";
+export { createGitProbe, hermeticEnv } from "./git-probe.mjs";
+export { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
+export { platformPaths } from "./platform-paths.mjs";