agents-can-communicate 0.1.0

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

@@ -0,0 +1,107 @@
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
+import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
+import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
+import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
+import { applyPlan, detectInstallation, planInstallation }
+  from "@agents-can-communicate/installer";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { platformPaths } from "./platform-paths.mjs";
+
+// Where each client keeps its own configuration. All of it derives from one
+// home, so a test - or an operator with a second account - can point the whole
+// installation somewhere else in one move.
+// Each client keeps its own directory under the user's home, and an adapter
+// pointed at the home itself writes beside them rather than inside them. That
+// install reports success and the client never reads a byte of it.
+export const clientContext = home => ({
+  home,
+  configDir: path.join(home, ".claude"),
+  agentsHome: home,
+  codexHome: path.join(home, ".codex"),
+  kimiHome: path.join(home, ".kimi-code"),
+});
+
+export const ALL_ADAPTERS = () => [createClaudeCodeAdapter(), createCodexAdapter(),
+  createGeminiCliAdapter(), createKimiAdapter()];
+
+function selectAdapters(requested) {
+  const all = ALL_ADAPTERS();
+  if (requested === undefined) return all;
+  const wanted = Array.isArray(requested) ? requested : [requested];
+  const known = new Map(all.map(adapter => [adapter.id, adapter]));
+  return wanted.map(id => {
+    const adapter = known.get(id);
+    if (adapter === undefined) {
+      throw new AccError(EXIT.USAGE, `unknown adapter: ${id}`,
+        { adapter: id, known: [...known.keys()] });
+    }
+    return adapter;
+  });
+}
+
+/**
+ * `acc install`, `acc install --dry-run`, and `acc uninstall`.
+ *
+ * Detection, planning and application are three separate steps on purpose:
+ * detection only reads, the plan is deterministic JSON that says exactly what
+ * would change, and application is the only step that writes. `--dry-run` shows
+ * the plan and stops - so what an operator approves is the same object that is
+ * then carried out, not a description of it produced somewhere else.
+ */
+/**
+ * What the command says it did.
+ *
+ * `installed 0 adapter(s)` was the whole report whether four clients were
+ * absent, one refused, or nothing was asked for. The reasons existed - the plan
+ * carries one per skipped adapter and the result one per failure - and only
+ * `--json` ever showed them.
+ */
+export function describeOutcome({ action, acted, failed = [], skipped = [] }) {
+  return [`${action}ed ${acted} adapter(s)`
+    + (failed.length > 0 ? `; ${failed.length} failed` : ""),
+  ...skipped.map(entry => `  skip ${entry.adapterId}: ${entry.reason}`),
+  ...failed.map(entry => `  ${entry.adapterId}: ${entry.error}`)].join("\n");
+}
+
+/**
+ * A failed adapter ends the command.
+ *
+ * It used to be counted in a line that began with a success and exit 0, which is
+ * what a malformed `~/.claude/settings.json` produced: the adapter refused,
+ * correctly, and the script that ran the installer was told it had worked.
+ */
+export function failureOf({ action, acted, failed = [] }) {
+  if (failed.length === 0) return null;
+  return new AccError(EXIT.DATA,
+    describeOutcome({ action, acted, failed }), { failed });
+}
+
+export async function runInstallCommand({ options, runtime, action = "install" }) {
+  const adapters = selectAdapters(options.adapter);
+  const home = options.home ?? runtime.env?.HOME ?? homedir();
+  const context = clientContext(home);
+  const { data: dataHome } = platformPaths({ platform: runtime.platform,
+    env: runtime.env ?? {} });
+
+  const detected = await detectInstallation({ adapters, context });
+  const plan = planInstallation({ adapters, detected, context, action });
+
+  const dryRun = options.dryRun === true;
+  const result = await applyPlan({ plan, adapters, context, dataHome, dryRun });
+
+  const acted = result.operations.filter(operation => operation.applied).length;
+  if (dryRun) {
+    return { data: { ...result, plan, dataHome },
+      text: [`would ${action}:`, ...plan.operations.flatMap(operation => operation.summary),
+        ...plan.skipped.map(entry => `skip ${entry.adapterId}: ${entry.reason}`)].join("\n") };
+  }
+
+  return { data: { ...result, plan, dataHome },
+    text: describeOutcome({ action, acted, failed: result.failed,
+      skipped: plan.skipped }),
+    error: failureOf({ action, acted, failed: result.failed }) };
+}

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

@@ -0,0 +1,344 @@
+import { AccError, CONFIG_FILENAME, EXIT, failure, ok }
+  from "@agents-can-communicate/protocol";
+import { createCoordinationService } from "@agents-can-communicate/core";
+import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
+
+import { parseArgs, positiveNumber } from "./args.mjs";
+
+// A usage error names what is missing rather than failing deeper in a service
+// with the argument already half-applied.
+const usage = message => new AccError(EXIT.USAGE, message);
+import { describeCommands, helpText } from "./help.mjs";
+import { runConfigCommand } from "./config-command.mjs";
+import { runInstallCommand } from "./install-command.mjs";
+import { runDoctor } from "./doctor-command.mjs";
+import { createGitProbe } from "./git-probe.mjs";
+import { canonicalClaim } from "./claim-spelling.mjs";
+import { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
+import { resolveOwner } from "./session-owner.mjs";
+import { discoverWorkspace } from "./workspace-discovery.mjs";
+
+const DEFAULT_CADENCE_MS = 30_000;
+
+async function openContext(options, runtime) {
+  const descriptor = await discoverWorkspace({
+    cwd: options.cwd ?? runtime.cwd,
+    env: runtime.env,
+    gitProbe: runtime.gitProbe ?? createGitProbe(),
+    explicitConfig: options.workspace,
+  });
+  const paths = runtimePaths({
+    dataHome: runtime.dataHome ?? platformDataHome({ platform: runtime.platform,
+      env: runtime.env }),
+    workspaceId: descriptor.id,
+    workspaceRoots: descriptor.roots,
+  });
+  const store = await openFilesystemStore({ root: paths.root, clock: runtime.clock,
+    ids: runtime.ids, workspaceId: descriptor.id });
+  return { descriptor, paths,
+    service: createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids }) };
+}
+
+const human = value => (typeof value === "string" ? value : JSON.stringify(value, null, 2));
+
+const HANDLERS = Object.freeze({
+  attach: async ({ options, context }) => {
+    const session = await context.service.openSession({
+      workspaceId: context.descriptor.id,
+      participantId: options.participant,
+      displayName: options.participant,
+      harness: options.harness ?? "cli",
+      parentSessionId: options.parent ?? null,
+      heartbeatCadenceMs: options.cadence
+        ? positiveNumber(options.cadence, "cadence") : DEFAULT_CADENCE_MS,
+      sessionId: options.session,
+      descriptor: context.descriptor,
+    });
+    // The adapter needs both to prove ownership later, so both are printed.
+    return { data: { sessionId: session.sessionId, generation: session.generation },
+      text: `${session.sessionId} ${session.generation}` };
+  },
+
+  heartbeat: async ({ options, context }) => {
+    const session = await context.service.heartbeatSession({ sessionId: options.session,
+      generation: options.generation });
+    return { data: { heartbeatAt: session.heartbeatAt }, text: session.heartbeatAt };
+  },
+
+  detach: async ({ options, context }) => {
+    const session = await context.service.closeSession({ sessionId: options.session,
+      generation: options.generation });
+    return { data: { sessionId: session.sessionId, state: session.state },
+      text: `closed ${session.sessionId}` };
+  },
+
+  sync: async ({ options, context }) => {
+    const result = await context.service.sync({ sessionId: options.session,
+      cursor: options.cursor ?? null, scope: options.scope,
+      limit: options.limit ? positiveNumber(options.limit, "limit") : undefined });
+    // Solo zero-overhead: nothing to say means nothing printed, not a banner.
+    const text = result.solo ? "" : `${result.attention.length} attention; `
+      + `${result.roster.length} session(s); cursor ${result.cursor}`;
+    return { data: result, text };
+  },
+
+  work: async ({ options, context }) => {
+    // Saying nothing and saying "I have stopped" are different. Without this an
+    // intent stayed on the roster until the session closed, so peers read a
+    // finished piece of work as still in progress.
+    if (options.clear === true) {
+      const cleared = await context.service.clearIntent({ sessionId: options.session,
+        generation: options.generation });
+      return { data: cleared, text: "intent cleared" };
+    }
+    if (options.summary === undefined) throw usage("work requires --summary");
+    const intent = await context.service.setIntent({ sessionId: options.session,
+      generation: options.generation, summary: options.summary, mode: options.mode ?? "edit",
+      state: options.state, workstreamId: options.workstream ?? null,
+      resourceHints: options.hint ?? [] });
+    return { data: intent, text: `intent: ${intent.summary}` };
+  },
+
+  claim: async ({ options, context }) => {
+    const claim = await context.service.acquireClaim({ sessionId: options.session,
+      generation: options.generation,
+      resource: await canonicalClaim(options.resource, context.descriptor),
+      mode: options.mode ?? "exclusive", enforcement: options.enforcement ?? "advisory",
+      reason: options.reason ?? "unspecified",
+      leaseSeconds: options.lease ? positiveNumber(options.lease, "lease") : undefined,
+      descriptor: context.descriptor });
+    return { data: claim, text: `claimed ${claim.resource}` };
+  },
+
+  release: async ({ options, context }) => {
+    const request = { claimId: options.claim, sessionId: options.session,
+      generation: options.generation, authority: options.authority, reason: options.reason };
+    if (options.authority === undefined) await context.service.releaseClaim(request);
+    else await context.service.forceReleaseClaim(request);
+    return { data: { claimId: options.claim }, text: `released ${options.claim}` };
+  },
+
+  message: async ({ options, context }) => {
+    const message = await context.service.sendMessage({ sessionId: options.session,
+      generation: options.generation, toParticipantIds: options.to ?? [],
+      type: options.type ?? "note", subject: options.subject, body: options.body,
+      priority: options.priority, workstreamId: options.workstream ?? null,
+      requiresAck: options.requiresAck === true, descriptor: context.descriptor });
+    return { data: message, text: `sent ${message.messageId}` };
+  },
+
+  /**
+   * Ask another agent to do something. One call, one write.
+   *
+   * The recipient hears about it twice by design: the task raises an attention
+   * item for the participant it names, and the message reaches their turn as
+   * quoted peer text explaining why.
+   */
+  request: async ({ options, context }) => {
+    const { task, message } = await context.service.requestWork({
+      sessionId: options.session, generation: options.generation,
+      toParticipantId: options.to, title: options.title, detail: options.detail,
+      workstreamId: options.workstream, priority: options.priority,
+      dependsOn: options.dependsOn ?? [], descriptor: context.descriptor });
+    return { data: { task, message },
+      text: `requested ${task.taskId} of ${options.to}` };
+  },
+
+  ack: async ({ options, context }) => {
+    const receipt = await context.service.markDelivery({ sessionId: options.session,
+      generation: options.generation, messageId: options.message,
+      state: options.state ?? "acknowledged" });
+    return { data: receipt, text: `${receipt.messageId} ${receipt.state}` };
+  },
+
+  /**
+   * What was settled, and on whose authority.
+   *
+   * `--human` is the caller stating that a person actually decided this. The
+   * core refuses `--authority human` without it, because a peer proposal
+   * becoming a human decision on its own is the one way this record could
+   * launder an agent's opinion into a ruling.
+   */
+  decide: async ({ options, context }) => {
+    const decision = await context.service.recordDecision({
+      sessionId: options.session, generation: options.generation,
+      title: options.title, outcome: options.outcome,
+      authority: options.authority ?? "workstream",
+      workstreamId: options.workstream ?? null,
+      decidedBy: options.decidedBy,
+      supersedes: options.supersedes ?? null,
+      humanConfirmed: options.human === true,
+      descriptor: context.descriptor });
+    return { data: decision,
+      text: `${decision.decisionId} ${decision.authority}: ${decision.title}` };
+  },
+
+  workstream: async ({ options, context }) => {
+    const owner = { sessionId: options.session, generation: options.generation };
+    // Taking the coordination of one and creating one are the same noun, so
+    // they stay one command rather than two the model has to choose between -
+    // the same shape `acc task` already has.
+    if (options.take === true || options.release === true) {
+      if (options.workstream === undefined) {
+        throw usage(`workstream --${options.take === true ? "take" : "release"} `
+          + "requires --workstream");
+      }
+      const acted = options.take === true
+        ? await context.service.acquireCoordinator({ ...owner,
+          workstreamId: options.workstream })
+        : await context.service.releaseCoordinator({ ...owner,
+          workstreamId: options.workstream });
+      return { data: acted,
+        text: `${acted.workstreamId} ${options.take === true ? "coordinated" : "released"}` };
+    }
+    if (options.title === undefined) throw usage("workstream requires --title");
+    if (options.objective === undefined) throw usage("workstream requires --objective");
+    const workstream = await context.service.createWorkstream({ ...owner,
+      title: options.title, objective: options.objective,
+      descriptor: context.descriptor });
+    return { data: workstream, text: `${workstream.workstreamId} ${workstream.state}` };
+  },
+
+  task: async ({ options, context }) => {
+    const owner = { sessionId: options.session, generation: options.generation };
+    // Taking work and moving it along are the same noun as creating it, so they
+    // stay one command rather than three the model has to choose between.
+    if (options.take === true) {
+      if (options.task === undefined) throw usage("task --take requires --task");
+      const taken = await context.service.claimTask({ ...owner, taskId: options.task,
+        force: options.force === true });
+      return { data: taken, text: `${taken.taskId} ${taken.state}` };
+    }
+    if (options.decline === true) {
+      if (options.task === undefined) throw usage("task --decline requires --task");
+      const refused = await context.service.declineTask({ ...owner,
+        taskId: options.task, reason: options.reason });
+      return { data: refused, text: `${refused.taskId} declined` };
+    }
+    if (options.state !== undefined) {
+      if (options.task === undefined) throw usage("task --state requires --task");
+      const moved = await context.service.transitionTask({ ...owner,
+        taskId: options.task, state: options.state });
+      return { data: moved, text: `${moved.taskId} ${moved.state}` };
+    }
+    if (options.title === undefined) throw usage("task requires --title");
+    const task = await context.service.createTask({ ...owner,
+      workstreamId: options.workstream, title: options.title, detail: options.detail,
+      assigneeParticipantId: options.assignee, taskId: options.task,
+      dependsOn: options.dependsOn ?? [], descriptor: context.descriptor });
+    return { data: task, text: `${task.taskId} ${task.state}` };
+  },
+
+  finish: async ({ options, context }) => {
+    const handoff = await context.service.finishSession({ sessionId: options.session,
+      generation: options.generation, goal: options.goal, status: options.status,
+      toParticipantId: options.to ?? null, completed: options.completed ?? [],
+      remaining: options.remaining ?? [], blockers: options.blocker ?? [] });
+    return { data: handoff, text: `handoff ${handoff.handoffId}` };
+  },
+
+  status: async ({ options, context }) => {
+    const status = await context.service.collectStatus({
+      participantId: options.participant, all: options.all === true });
+    const text = `${status.counts.live} live; ${status.counts.claims} claim(s); `
+      + `protection ${status.protection}`;
+    return { data: status, text };
+  },
+
+  config: async ({ options, runtime }) => {
+    const result = await runConfigCommand({ subcommand: options.subcommand,
+      cwd: options.cwd ?? runtime.cwd,
+      // A pipe is not a person. Without a TTY there is nobody to answer, so the
+      // command demands --yes rather than hanging or assuming consent.
+      interactive: runtime.stdout?.isTTY === true,
+      yes: options.yes === true,
+      confirm: runtime.confirm ?? (async () => false),
+      force: options.force === true,
+      // Opened lazily and only by `init`: `config validate` has to work on a
+      // workspace discovery cannot open, which is what a reader runs it to
+      // find out.
+      probeWorkspace: () => openContext(options, runtime),
+      ids: runtime.ids });
+    if (result.subcommand === "validate") {
+      return { data: result, text: result.present
+        ? `${result.file} is valid` : `no ${CONFIG_FILENAME}; defaults apply` };
+    }
+    return { data: result,
+      text: result.written ? `wrote ${result.file}` : `not written: ${result.file}` };
+  },
+
+  install: async ({ options, runtime }) =>
+    runInstallCommand({ options, runtime, action: "install" }),
+
+  uninstall: async ({ options, runtime }) =>
+    runInstallCommand({ options, runtime, action: "uninstall" }),
+
+  doctor: async ({ options, context, runtime }) => runDoctor({ options, context, runtime }),
+
+  help: async () => ({ data: { commands: describeCommands() }, text: helpText() }),
+
+  version: async ({ runtime }) => {
+    // Read by the composition root from the package manifest: `bin/` sits at
+    // the same depth in the published package as it does in this tree, which is
+    // not true of anything under `packages/`. A version typed into the source
+    // would be one more place the next bump has to reach, and the kind that
+    // goes stale without failing.
+    if (typeof runtime.version !== "function") {
+      throw new AccError(EXIT.DATA, "this build was assembled without a version to report");
+    }
+    const version = await runtime.version();
+    return { data: { version }, text: version };
+  },
+});
+
+/**
+ * @returns {Promise<number>} the process exit code
+ */
+const NO_WORKSPACE = Object.freeze(["config", "install", "uninstall", "help", "version"]);
+
+export async function main(argv, runtime) {
+  const write = (stream, text) => new Promise((resolve, reject) =>
+    stream.write(text, error => (error ? reject(error) : resolve())));
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+    // `config` is the one command that must work on a workspace ACC cannot
+    // open. Discovery validates the config too, so a broken one would fail
+    // there first and `acc config validate` - the command a user runs to find
+    // out what is wrong - would never reach its own report.
+    // These work on a machine, not a workspace. `config` must run even when
+    // discovery cannot open the workspace - that is what a user is trying to
+    // find out - install touches client configuration rather than ACC state,
+    // and `help` has to answer in a directory that is no workspace at all.
+    const context = NO_WORKSPACE.includes(parsed.command)
+      ? null
+      : await openContext(parsed.options, runtime);
+    // Which session is calling is answered once, here, rather than by each
+    // handler: every one of them needs the same pair, and a handler that forgot
+    // to ask would be an operation an agent cannot reach.
+    const options = context === null ? parsed.options
+      : await resolveOwner({ command: parsed.command, options: parsed.options,
+        context, env: runtime.env });
+    const { data, text, error: outcome } = await HANDLERS[parsed.command](
+      { options, context, runtime });
+    // A handler may have done real work and still failed: `acc install` writes
+    // for the clients it could and reports the one it could not. The data is
+    // printed either way, and the command still fails.
+    if (outcome != null) throw Object.assign(outcome, { details: { ...outcome.details, ...data } });
+    // Machine mode writes exactly one JSON object to stdout and nothing else.
+    if (parsed.options.json === true) await write(runtime.stdout, `${JSON.stringify(ok(data))}\n`);
+    else if (text !== "") await write(runtime.stdout, `${human(text)}\n`);
+    return EXIT.OK;
+  } catch (error) {
+    const code = error instanceof AccError ? error.code : EXIT.DATA;
+    // A usage error happens before the parse completes, so machine mode has to
+    // be recognised from the raw argv. Otherwise the one caller that cannot
+    // read prose - an adapter - gets prose exactly when it made a mistake.
+    if (parsed?.options?.json === true || argv.includes("--json")) {
+      await write(runtime.stdout, `${JSON.stringify(failure(error))}\n`);
+    } else {
+      await write(runtime.stderr, `${error.message}\n`);
+    }
+    return code;
+  }
+}

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

@@ -0,0 +1,109 @@
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+// Resolution is a pure function of platform and environment, so the Windows and
+// Linux answers are testable from a machine that is neither. Reading
+// process.platform inside would mean two of the three branches are only ever
+// exercised by whoever happens to run them.
+const AREAS = Object.freeze(["data", "config", "cache"]);
+
+const OVERRIDE = Object.freeze({
+  data: "ACC_DATA_HOME",
+  config: "ACC_CONFIG_HOME",
+  cache: "ACC_CACHE_HOME",
+});
+
+const XDG = Object.freeze({
+  data: "XDG_DATA_HOME",
+  config: "XDG_CONFIG_HOME",
+  cache: "XDG_CACHE_HOME",
+});
+
+// An exported-but-empty variable is the normal shape of "unset" in a shell
+// script. Treating it as a path puts runtime state at the filesystem root.
+const set = value => typeof value === "string" && value.length > 0;
+
+const usage = (message, details) => {
+  throw new AccError(EXIT.USAGE, message, details);
+};
+
+function windowsPaths(env) {
+  if (!set(env.APPDATA)) {
+    usage("cannot resolve the Windows application data directory");
+  }
+  return {
+    data: env.APPDATA,
+    config: env.APPDATA,
+    // Roaming is the honest fallback: a cache that roams is wasteful, not wrong.
+    cache: set(env.LOCALAPPDATA) ? env.LOCALAPPDATA : env.APPDATA,
+  };
+}
+
+function requireHome(env) {
+  if (!set(env.HOME)) usage("cannot resolve the user home directory");
+  return env;
+}
+
+function macosPaths(env) {
+  const support = path.join(env.HOME, "Library", "Application Support");
+  // XDG variables are deliberately ignored here. They are common on a machine
+  // that also runs Linux tooling, and letting one relocate macOS state would
+  // move a user's sessions the day they install something unrelated.
+  return { data: support, config: support,
+    cache: path.join(env.HOME, "Library", "Caches") };
+}
+
+function xdgPaths(env) {
+  const fallback = { data: path.join(env.HOME, ".local", "share"),
+    config: path.join(env.HOME, ".config"), cache: path.join(env.HOME, ".cache") };
+  return Object.fromEntries(AREAS.map(area =>
+    [area, set(env[XDG[area]]) ? env[XDG[area]] : fallback[area]]));
+}
+
+/**
+ * Where ACC keeps state, configuration, and cache on this platform.
+ *
+ * None of it is ever inside a workspace. A checkout can be deleted, cloned, or
+ * synced to another machine without carrying presence, locks, or messages with
+ * it - and "just put it in a dotfile next to the project" is the exact
+ * regression this exists to prevent, which is why passing `workspaceRoots`
+ * makes it an error rather than a convention.
+ */
+export function platformPaths({ platform = process.platform, env = process.env,
+  workspaceRoots = [] } = {}) {
+  // Windows paths are not absolute to a posix `path`, so the check has to use
+  // the same flavour the platform does.
+  const flavour = platform === "win32" ? path.win32 : path.posix;
+
+  const overridden = Object.fromEntries(AREAS
+    .filter(area => set(env[OVERRIDE[area]]))
+    .map(area => [area, env[OVERRIDE[area]]]));
+
+  // The platform is only consulted for what was not named outright, so a fully
+  // overridden environment never has to satisfy that platform's own
+  // prerequisites - which is what makes a test fixture for one platform
+  // runnable on another.
+  const missing = AREAS.filter(area => overridden[area] === undefined);
+  const base = missing.length === 0 ? {}
+    : platform === "win32" ? windowsPaths(env)
+      : platform === "darwin" ? macosPaths(requireHome(env))
+        : xdgPaths(requireHome(env));
+
+  const resolved = Object.fromEntries(AREAS.map(area =>
+    [area, overridden[area] ?? base[area]]));
+
+  for (const [area, location] of Object.entries(resolved)) {
+    if (!flavour.isAbsolute(location)) {
+      usage(`the ${area} location must be an absolute path`, { area, location });
+    }
+    for (const root of workspaceRoots) {
+      const relative = flavour.relative(root, location);
+      if (relative === ""
+        || (!flavour.isAbsolute(relative) && !relative.startsWith(".."))) {
+        usage(`${area} state must not live inside the workspace`, { area, location, root });
+      }
+    }
+  }
+  return Object.freeze(resolved);
+}

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

@@ -0,0 +1,58 @@
+import path from "node:path";
+
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
+
+const AREAS = ["protocol", "events", "state", "locks", "ephemeral"];
+
+/**
+ * @typedef {{ root: string, protocol: string, events: string, state: string,
+ *   locks: string, ephemeral: string }} RuntimePaths
+ */
+
+/**
+ * Runtime state lives under the platform's user-data directory, never inside
+ * the workspace. A checkout can be deleted, cloned, or synced to another
+ * machine without carrying presence, locks, or messages with it.
+ */
+export function runtimePaths({ dataHome, workspaceId, workspaceRoots = [] }) {
+  if (typeof dataHome !== "string" || !path.isAbsolute(dataHome)) {
+    throw new AccError(EXIT.USAGE, "the data home must be an absolute path", { dataHome });
+  }
+  assertPortableId(workspaceId, "workspace id");
+  const root = path.join(dataHome, "acc", "workspaces", workspaceId);
+  // Enforced here rather than only asserted in a test, because "just put it in
+  // .agents next to the project" is the exact regression this design exists to
+  // prevent, and it would otherwise look like it works.
+  for (const workspaceRoot of workspaceRoots) {
+    const relative = path.relative(workspaceRoot, root);
+    if (relative === "" || (!path.isAbsolute(relative) && !relative.startsWith(".."))) {
+      throw new AccError(EXIT.USAGE, "runtime state must not live inside the workspace",
+        { root, workspaceRoot });
+    }
+  }
+  return Object.freeze(Object.fromEntries([["root", root],
+    // `ephemeral` holds presence and Intent for workspaces that have not
+    // materialised durable state yet, so it is deliberately a sibling of the
+    // event log rather than a corner of it.
+    ...AREAS.map(area => [area, path.join(root, area)])]));
+}
+
+export function platformDataHome({ platform = process.platform, env = process.env } = {}) {
+  if (typeof env.ACC_DATA_HOME === "string" && env.ACC_DATA_HOME.length > 0) {
+    return env.ACC_DATA_HOME;
+  }
+  if (platform === "win32") {
+    if (typeof env.APPDATA === "string" && env.APPDATA.length > 0) return env.APPDATA;
+    throw new AccError(EXIT.USAGE, "cannot resolve the Windows application data directory");
+  }
+  if (typeof env.XDG_DATA_HOME === "string" && env.XDG_DATA_HOME.length > 0
+    && platform !== "darwin") {
+    return env.XDG_DATA_HOME;
+  }
+  if (typeof env.HOME !== "string" || env.HOME.length === 0) {
+    throw new AccError(EXIT.USAGE, "cannot resolve the user home directory");
+  }
+  return platform === "darwin"
+    ? path.join(env.HOME, "Library", "Application Support")
+    : path.join(env.HOME, ".local", "share");
+}