agents-can-communicate 0.1.0

package/node_modules/@agents-can-communicate/adapter-kimi/src/hooks.mjs

@@ -0,0 +1,125 @@
+import { normalizedEvent } from "@agents-can-communicate/adapter-sdk";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+// Not read from documentation and not guessed: this client validates its config
+// with a strict schema, and rejecting an empty hook entry makes it name every
+// accepted event. See COMPATIBILITY.md for the transcript.
+export const KIMI_HOOK_EVENTS = Object.freeze(["PreToolUse", "PostToolUse",
+  "PostToolUseFailure", "PermissionRequest", "PermissionResult", "UserPromptSubmit",
+  "UserPromptQueued", "TurnStarted", "Stop", "StopFailure", "Interrupt", "SessionStart",
+  "SessionEnd", "SessionHeartbeat", "SubagentStart", "SubagentStop", "TaskStarted",
+  "PreCompact", "PostCompact", "Notification"]);
+
+// The tools this client actually names. Codex calls its editor apply_patch, and
+// a matcher borrowed across harnesses guards nothing at all, so these were read
+// out of a real request rather than assumed from the family resemblance.
+export const KIMI_EDIT_TOOLS = Object.freeze(["Write", "Edit"]);
+export const KIMI_SHELL_TOOLS = Object.freeze(["Bash"]);
+
+const KIND_BY_EVENT = Object.freeze({
+  SessionStart: "sessionStart",
+  SessionEnd: "sessionEnd",
+  SessionHeartbeat: "heartbeat",
+  UserPromptSubmit: "beforeTurn",
+  PreToolUse: "beforeTool",
+  PostToolUse: "afterTool",
+  PostToolUseFailure: "afterTool",
+  Stop: "turnEnd",
+  StopFailure: "turnEnd",
+  SubagentStart: "childStart",
+  SubagentStop: "childEnd",
+});
+
+/**
+ * Normalise a Kimi Code hook payload.
+ *
+ * A whitelist, not a filter. `TurnStarted` carries the raw prompt, and
+ * `UserPromptSubmit` carries it as content blocks; `PostToolUse` carries the
+ * tool's output and `PostToolUseFailure` the error text. This client hands
+ * conversation content to hooks directly, so keeping it out is a property of
+ * this function rather than an absence of opportunity.
+ */
+export function normalizeKimiHook(payload) {
+  const event = payload?.hook_event_name;
+  if (typeof event !== "string" || !KIMI_HOOK_EVENTS.includes(event)) {
+    throw new AccError(EXIT.DATA, "unrecognised Kimi Code hook event",
+      { event: event ?? null });
+  }
+  if (typeof payload.session_id !== "string" || typeof payload.cwd !== "string") {
+    throw new AccError(EXIT.DATA, "hook payload has no session id or working directory",
+      { event, received: Object.keys(payload) });
+  }
+  const tool = typeof payload.tool_name === "string" ? payload.tool_name : null;
+  return normalizedEvent({
+    kind: KIND_BY_EVENT[event] ?? "other",
+    sessionId: payload.session_id,
+    cwd: payload.cwd,
+    // Only SessionStart carries it; every other event leaves it null rather
+    // than inheriting a stale value.
+    model: typeof payload.model === "string" ? payload.model : null,
+    // No subagent was observed running, so there is no field to map yet and
+    // nothing is invented from timing.
+    parentSessionId: null,
+    tool,
+    targets: writeTargets(tool, payload.tool_input),
+  });
+}
+
+/**
+ * The paths a tool call would write.
+ *
+ * Both editing tools take `path` - confirmed from their declared schemas, where
+ * `Write` requires `path` and `content` and `Edit` requires `path`,
+ * `old_string` and `new_string`. Nothing else is read: the contents and the
+ * replacement strings are conversation content and stay out.
+ *
+ * `Bash` declares nothing. A command can write anywhere, and a path guessed out
+ * of one would give a guard that blocks work it holds no claim over while
+ * missing writes it does.
+ */
+function writeTargets(tool, input) {
+  if (!KIMI_EDIT_TOOLS.includes(tool)) return [];
+  const path = input?.path;
+  return typeof path === "string" && path !== "" ? [path] : [];
+}
+
+/**
+ * Deny a tool call in the one shape this client acts on.
+ *
+ * Five candidate shapes were run against a real session. Only two stopped the
+ * tool: exit code 2, and this structured reply. `{"decision":"block"}`,
+ * `{"permission":"deny"}` and exit code 1 all looked plausible and let the write
+ * through. This one is preferred over exit 2 because the reason survives: it
+ * reaches the model as the failed call's `error.message`.
+ */
+export function denyResponse(reason) {
+  return { hookSpecificOutput: { hookEventName: "PreToolUse",
+    permissionDecision: "deny", permissionDecisionReason: reason } };
+}
+
+export function allowResponse() {
+  return {};
+}
+
+/**
+ * Context for the next turn, as this client delivers it.
+ *
+ * Unlike Claude Code, this client does not unwrap `additionalContext`: it wraps
+ * a hook's entire stdout in `<hook_result hook_event="...">` and shows the model
+ * whatever that was. Emitting the JSON envelope here would put the envelope
+ * itself into the conversation, so the injection is plain text.
+ */
+export function injectResponse(context) {
+  return context === "" ? null : context;
+}
+
+// How a denial and an injection reach this client. Both were measured; they use
+// different mechanisms, and neither matches all three of the other adapters.
+export function denyOutcome(reason) {
+  return { stdout: `${JSON.stringify(denyResponse(reason))}\n`, stderr: "", exitCode: 0 };
+}
+
+export function injectOutcome(context) {
+  const rendered = injectResponse(context);
+  return { stdout: rendered === null ? "" : `${rendered}\n`, stderr: "", exitCode: 0 };
+}

package/node_modules/@agents-can-communicate/adapter-kimi/src/install.mjs

@@ -0,0 +1,216 @@
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { fileURLToPath } from "node:url";
+
+import { assertRunner, bakeSkillCommand, blankText, defaultRunner, removeIfEmpty,
+  removeInstalledTree, runnerExists, writeForeignJson }
+  from "@agents-can-communicate/adapter-sdk";
+
+const bundle = fileURLToPath(new URL("../plugin", import.meta.url));
+const PLUGIN_NAME = "agents-can-communicate";
+
+// The block markers are the whole ownership story. This client keeps its hooks
+// in the user's TOML config, and ACC ships without dependencies, so parsing and
+// re-emitting that 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";
+
+// Seconds, not milliseconds. A hook that sleeps 3s dies under `timeout = 1`,
+// which is how this was settled; copying another harness's `10000` would have
+// let a hung hook stall a turn for the better part of three hours.
+const TIMEOUT_SECONDS = 10;
+
+// Only events observed firing get wired. Guard events carry the matcher, which
+// was proven to select: "NoSuchTool" never fired, "Write|Edit|Bash" fired twice.
+const WIRING = Object.freeze([
+  { event: "SessionStart", kind: "sessionStart" },
+  { event: "UserPromptSubmit", kind: "beforeTurn" },
+  { event: "SessionHeartbeat", kind: "heartbeat" },
+  { event: "PreToolUse", kind: "beforeTool", matcher: "Write|Edit|Bash" },
+  { event: "Stop", kind: "turnEnd" },
+]);
+
+const configPath = home => path.join(home, "config.toml");
+const pluginPath = home => path.join(home, "plugins", "managed", PLUGIN_NAME);
+const registryPath = home => path.join(home, "plugins", "installed.json");
+
+// This client's config has no variable to stand in for an install directory -
+// unlike the plugin manifests of the other three, which expand a plugin root -
+// so the runner is written in as an absolute path at install time. Codex taught
+// this the hard way: a relative hook command fails silently, hook after hook.
+
+// TOML basic strings take backslash escapes. A path is user-controlled input
+// here, so it is escaped rather than trusted to be boring.
+const tomlString = value => `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+async function readText(file, fallback) {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+/**
+ * Read a client's own JSON, and say which file when it will not parse.
+ *
+ * A malformed config is the user's to fix, and the message they get has to name
+ * it. `Unexpected end of JSON input` arrived with no path attached, from an
+ * install that touches four clients' homes, and left them to guess which.
+ */
+async function readJson(file, fallback) {
+  const source = await readText(file, null);
+  if (source === null) return fallback;
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    throw new AccError(EXIT.DATA, `${file} is not valid JSON: ${error.message}`,
+      { file, cause: error.message });
+  }
+}
+
+/**
+ * Remove ACC's region and nothing else.
+ *
+ * Written to survive a config that has no block, several blocks, or a block the
+ * user has half-deleted: an unterminated marker consumes to end of file rather
+ * than leaving stray `[[hooks]]` entries that would fail the client's schema
+ * and lock the user out of their own tool.
+ */
+export function stripBlock(source) {
+  const lines = source.split("\n");
+  const kept = [];
+  let inside = false;
+  for (const line of lines) {
+    if (line.trimEnd() === BEGIN) { inside = true; continue; }
+    if (inside) {
+      if (line.trimEnd() === END) inside = false;
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+export function renderBlock(runner, node = process.execPath) {
+  const entries = WIRING.map(({ event, kind, matcher }) => {
+    // Both paths are shell-quoted inside the TOML string: a hook runs through a
+    // shell, and a space in either path would otherwise split the command.
+    // The interpreter is named outright rather than left to PATH, which a hook's
+    // environment does not reliably carry.
+    const command = `${tomlString(node)} ${tomlString(runner)} kimi ${kind}`;
+    const lines = ["[[hooks]]", `event = ${tomlString(event)}`,
+      `command = ${tomlString(command)}`];
+    if (matcher !== undefined) lines.push(`matcher = ${tomlString(matcher)}`);
+    lines.push(`timeout = ${TIMEOUT_SECONDS}`);
+    return lines.join("\n");
+  });
+  return [BEGIN, ...entries, END].join("\n");
+}
+
+const registerPlugin = (registry, root) => {
+  const plugins = (registry.plugins ?? []).filter(entry => entry.id !== PLUGIN_NAME);
+  return { ...registry, version: registry.version ?? 1,
+    plugins: [...plugins, { id: PLUGIN_NAME, root, source: "local", enabled: true }] };
+};
+
+export async function installKimiPlugin({ home, runner = defaultRunner(), node }) {
+  // A hook whose command does not exist fails silently, on every event, for as
+  // long as it stays installed: the client reports nothing and ACC simply never
+  // sees a session. Writing that entry and hoping is worse than refusing.
+  await assertRunner(runner);
+  // Read before writing: a registry that will not parse must be found before a
+  // plugin tree is laid down that nothing will then be able to remove.
+  const registered = await readJson(registryPath(home), { version: 1, plugins: [] });
+
+  const target = pluginPath(home);
+  await rm(target, { recursive: true, force: true });
+  await cp(bundle, target, { recursive: true });
+  // The skill ships with a placeholder where the command belongs: `acc` is
+  // not on PATH everywhere, and an agent that cannot run it improvises.
+  await bakeSkillCommand({ root: target, node });
+
+  const file = configPath(home);
+  const existing = await readText(file, "");
+  const withoutOurs = stripBlock(existing);
+  // A block appended at top level closes whatever table preceded it, so the
+  // user's last section cannot swallow our entries.
+  const separator = withoutOurs === "" || withoutOurs.endsWith("\n") ? "" : "\n";
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${withoutOurs}${separator}${renderBlock(runner, node)}\n`);
+
+  const registry = registryPath(home);
+  await mkdir(path.dirname(registry), { recursive: true });
+  await writeForeignJson(registry, registerPlugin(registered, target),
+    { readFile, writeFile, mkdir });
+
+  return { ok: true, changes: [target, file, registry], diagnostics: [] };
+}
+
+export async function uninstallKimiPlugin({ home, keep = [] }) {
+  const file = configPath(home);
+  const existing = await readText(file, null);
+  const changes = [];
+  if (existing !== null) {
+    const stripped = stripBlock(existing);
+    if (stripped !== existing) changes.push(file);
+    await writeFile(file, stripped);
+  }
+
+  const registry = registryPath(home);
+  const loaded = await readJson(registry, null);
+  if (loaded !== null) {
+    const plugins = (loaded.plugins ?? []).filter(entry => entry.id !== PLUGIN_NAME);
+    if (plugins.length !== (loaded.plugins ?? []).length) changes.push(registry);
+    // The registry exists because a plugin was installed. Leaving an empty one
+    // behind is litter in a home that had no such file - measured after an
+    // uninstall that was otherwise clean. An empty registry and an absent one
+    // mean the same thing to this client.
+    if (plugins.length > 0) {
+      await writeForeignJson(registry, { ...loaded, plugins },
+        { readFile, writeFile, mkdir });
+    } else {
+      await rm(registry, { force: true });
+    }
+  }
+
+  // Blank and absent are the same to this client, so there is nothing to lose
+  // by removing a config that holds nothing - and no record of who created it is
+  // needed, unlike a JSON settings file where `{}` can be the user's own.
+  await removeIfEmpty(configPath(home), { readFile, rm, isEmpty: blankText });
+
+  await removeInstalledTree(pluginPath(home), keep);
+  return { ok: true, changes, diagnostics: [] };
+}
+
+export async function detectKimi({ home, runner = defaultRunner() }) {
+  const source = await readText(configPath(home), "");
+  const installed = source.includes(BEGIN);
+  const registry = await readJson(registryPath(home), null);
+  const registered = (registry?.plugins ?? []).some(entry => entry.id === PLUGIN_NAME);
+  return { ok: true, changes: [], diagnostics: [
+    installed ? "acc hooks registered in config.toml" : "acc hooks not registered",
+    registered ? "acc plugin registered" : "acc plugin not registered",
+    await runnerExists(runner)
+      ? `hook runner present at ${runner}`
+      : `hook runner MISSING at ${runner}; every hook would fail silently`,
+  ] };
+}
+
+/**
+ * The paths an install would write, without writing them. Same helpers as the
+ * install, so a dry run cannot drift from what actually happens.
+ */
+export function planKimiInstall({ home }) {
+  return [
+    { path: pluginPath(home), kind: "tree" },
+    { path: configPath(home), kind: "merge" },
+    { path: registryPath(home), kind: "merge" },
+  ];
+}

package/node_modules/@agents-can-communicate/adapter-sdk/package.json

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

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

@@ -0,0 +1,101 @@
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
+
+// The capability surface, documented in docs/ADAPTER_AUTHORING.md and measured
+// per client in docs/CAPABILITIES.md. False is the default for every
+// entry: an adapter earns a true value by implementing the method that backs it
+// and by proving it in the conformance suite. Optimistic defaults are how a
+// tool ends up claiming protection it cannot deliver.
+export const CAPABILITY_SHAPE = Object.freeze({
+  lifecycle: ["sessionStart", "sessionResume", "sessionEnd", "heartbeat", "childSessions"],
+  context: ["startupInjection", "beforeTurnInjection", "safePointInjection"],
+  guards: ["beforeRead", "beforeWrite", "beforeShell"],
+  delivery: ["polling", "activeNotification", "wakeDormantSession"],
+  execution: ["launch", "resume", "terminate"],
+});
+
+// Each true capability names the method that has to exist for it to be true.
+const BACKING_METHOD = Object.freeze({
+  "lifecycle.sessionStart": "startSession",
+  "lifecycle.sessionResume": "resumeSession",
+  "lifecycle.sessionEnd": "endSession",
+  // A timer-driven event from the client, distinct from delivery.polling: it
+  // keeps presence fresh while the session is idle, which turn-driven hooks
+  // cannot do.
+  "lifecycle.heartbeat": "heartbeat",
+  "lifecycle.childSessions": "mapChildSession",
+  "context.startupInjection": "renderContext",
+  "context.beforeTurnInjection": "renderContext",
+  "context.safePointInjection": "renderContext",
+  "guards.beforeRead": "guardRead",
+  "guards.beforeWrite": "guardWrite",
+  "guards.beforeShell": "guardShell",
+  "delivery.polling": "poll",
+  "delivery.activeNotification": "notify",
+  "delivery.wakeDormantSession": "wake",
+  "execution.launch": "launch",
+  "execution.resume": "resumeProcess",
+  "execution.terminate": "terminate",
+});
+
+const BASE_METHODS = Object.freeze(["detect", "install", "uninstall", "doctor",
+  "normalizeHook", "renderContext"]);
+
+function usage(message, details = {}) {
+  throw new AccError(EXIT.USAGE, message, details);
+}
+
+export function assertCapabilities(declared = {}, implementation = {}) {
+  const resolved = {};
+  for (const [group, names] of Object.entries(CAPABILITY_SHAPE)) {
+    resolved[group] = Object.fromEntries(names.map(name => [name, false]));
+  }
+  for (const [group, values] of Object.entries(declared)) {
+    if (!Object.hasOwn(CAPABILITY_SHAPE, group)) {
+      usage(`unknown capability group: ${group}`, { group });
+    }
+    for (const [name, value] of Object.entries(values ?? {})) {
+      if (!CAPABILITY_SHAPE[group].includes(name)) {
+        usage(`unknown capability: ${group}.${name}`, { group, name });
+      }
+      if (typeof value !== "boolean") {
+        usage(`capability ${group}.${name} must be a boolean`, { group, name, value });
+      }
+      if (value === true) {
+        const method = BACKING_METHOD[`${group}.${name}`];
+        if (typeof implementation[method] !== "function") {
+          usage(`capability ${group}.${name} requires ${method}()`, { group, name, method });
+        }
+      }
+      resolved[group][name] = value;
+    }
+    Object.freeze(resolved[group]);
+  }
+  for (const group of Object.keys(CAPABILITY_SHAPE)) Object.freeze(resolved[group]);
+  return Object.freeze(resolved);
+}
+
+export function defineAdapter(manifest) {
+  if (typeof manifest?.id !== "string") usage("an adapter must declare an id");
+  assertPortableId(manifest.id, "adapter id");
+  if (typeof manifest.displayName !== "string" || manifest.displayName.trim() === "") {
+    usage("an adapter must declare a displayName", { id: manifest.id });
+  }
+  // Detection spawns this to decide whether the client is on the machine.
+  // Left undeclared it used to fall back to the adapter id, so `claude_code`
+  // and `gemini_cli` probed binaries that do not exist and were reported absent
+  // on every machine - `acc install` silently skipped half its clients.
+  const command = manifest.client?.command;
+  if (typeof command !== "string" || command.trim() === "") {
+    usage("an adapter must declare client.command, the binary its client installs",
+      { id: manifest.id });
+  }
+  for (const method of BASE_METHODS) {
+    if (typeof manifest[method] !== "function") {
+      usage(`an adapter must implement ${method}()`, { id: manifest.id, method });
+    }
+  }
+  return Object.freeze({
+    ...manifest,
+    capabilities: assertCapabilities(manifest.capabilities, manifest),
+  });
+}

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

@@ -0,0 +1,215 @@
+import path from "node:path";
+
+const MARKER = "acc:owned";
+// Ownership of single entries inside a container someone else also writes to.
+// `enabledPlugins` in a Claude Code settings file holds every plugin the user
+// has, so taking the whole key would destroy them - and giving it back on
+// uninstall would destroy them again.
+const ENTRY_MARKER = "acc:ownedEntries";
+// Containers ACC had to create. Recorded separately from whole owned keys:
+// creating one is permission to remove it when it ends up empty, not permission
+// to take whatever the user has put in it since.
+const CREATED_MARKER = "acc:createdContainers";
+// The file itself, as opposed to a container inside it. Recorded at install
+// because uninstall cannot tell afterwards: a settings file holding `{}` looks
+// the same whether ACC made it or the user did, and deleting the user's would
+// be the same overreach as taking a container they had put entries in.
+const CREATED_FILE = "acc:createdFile";
+
+/**
+ * Merge ACC entries into a user's config and record ownership, so uninstall can
+ * remove exactly what ACC added and nothing else.
+ *
+ * The ownership record is what makes uninstall safe: without it the only way to
+ * remove entries is to guess by shape, which is how a tool deletes a user's
+ * unrelated hook that happened to look similar.
+ */
+export function mergeOwnedConfig(existing, additions, { owner = MARKER } = {}) {
+  const merged = { ...existing };
+  const owned = new Set(existing?.[owner] ?? []);
+  for (const [key, value] of Object.entries(additions)) {
+    merged[key] = value;
+    owned.add(key);
+  }
+  merged[owner] = [...owned].sort();
+  return merged;
+}
+
+export function removeOwnedConfig(existing, { owner = MARKER } = {}) {
+  const owned = new Set(existing?.[owner] ?? []);
+  const result = {};
+  for (const [key, value] of Object.entries(existing ?? {})) {
+    // Unrelated keys survive untouched, including keys a user added by hand
+    // under a name ACC also uses elsewhere.
+    if (key !== owner && !owned.has(key)) result[key] = value;
+  }
+  return result;
+}
+
+export function ownedKeys(existing, { owner = MARKER } = {}) {
+  return [...(existing?.[owner] ?? [])];
+}
+
+/**
+ * Add entries inside containers ACC shares with the user.
+ *
+ * Records `[container, key]` pairs, so uninstall removes exactly the entries ACC
+ * added. A container ACC had to create is recorded too, but as a container it may
+ * clean up rather than as a key it owns: an empty one left behind is litter, and
+ * one the user has since put their own entries into is theirs.
+ */
+export function mergeOwnedEntries(existing, additions,
+  { entryOwner = ENTRY_MARKER, createdOwner = CREATED_MARKER, createdFile } = {}) {
+  const merged = { ...existing };
+  if (createdFile === true) merged[CREATED_FILE] = true;
+  const entries = new Map((existing?.[entryOwner] ?? [])
+    .map(pair => [`${pair[0]}\u0000${pair[1]}`, pair]));
+  const created = new Set(existing?.[createdOwner] ?? []);
+
+  for (const [container, values] of Object.entries(additions)) {
+    if (!Object.hasOwn(existing ?? {}, container)) created.add(container);
+    merged[container] = { ...(existing?.[container] ?? {}) };
+    for (const [key, value] of Object.entries(values)) {
+      merged[container][key] = value;
+      entries.set(`${container}\u0000${key}`, [container, key]);
+    }
+  }
+
+  merged[entryOwner] = [...entries.values()]
+    .sort((left, right) => left.join("/").localeCompare(right.join("/")));
+  if (created.size > 0) merged[createdOwner] = [...created].sort();
+  return merged;
+}
+
+/** Remove only the entries ACC recorded adding, leaving every other one. */
+export function removeOwnedEntries(existing,
+  { owner = MARKER, entryOwner = ENTRY_MARKER, createdOwner = CREATED_MARKER } = {}) {
+  const result = { ...(existing ?? {}) };
+  for (const [container, key] of result[entryOwner] ?? []) {
+    if (result[container] === null || typeof result[container] !== "object") continue;
+    const remaining = { ...result[container] };
+    delete remaining[key];
+    result[container] = remaining;
+  }
+  // A container ACC created goes only if nothing is left in it. Taking it
+  // outright would delete entries the user added after the install - the exact
+  // loss that recording ownership per entry exists to prevent.
+  for (const container of result[createdOwner] ?? []) {
+    const value = result[container];
+    if (value !== null && typeof value === "object" && Object.keys(value).length === 0) {
+      delete result[container];
+    }
+  }
+  delete result[entryOwner];
+  delete result[createdOwner];
+  delete result[CREATED_FILE];
+  return removeOwnedConfig(result, { owner });
+}
+
+export function ownedEntries(existing, { entryOwner = ENTRY_MARKER } = {}) {
+  return (existing?.[entryOwner] ?? []).map(pair => [...pair]);
+}
+
+/**
+ * Write JSON back into someone else's file, in that file's own style.
+ *
+ * ACC re-emits what it edits, and re-emitting with a fixed style rewrites bytes
+ * it was not asked to touch. Measured after an install and uninstall that
+ * changed nothing else: three clients' configs came back one byte longer, a
+ * trailing newline appended to files that had none. It is the same defect that
+ * was found once in Claude Code's registries and fixed there by hand - fixed for
+ * two files rather than for the shape, so the other three kept doing it.
+ *
+ * The style is read from the file rather than declared per client: what a client
+ * writes is a fact about the client, and asking the file cannot go stale.
+ * Absent file, absent style: a file ACC creates is its own, and gets the
+ * conventional trailing newline.
+ */
+export function jsonStyleOf(text) {
+  if (typeof text !== "string") return { indent: 2, trailingNewline: true };
+  // The whitespace itself, not a count of it. `JSON.stringify` takes a string
+  // for its indent, so a tab-indented file stays tab-indented; measuring the
+  // length instead turned one tab into one space and reformatted every line of
+  // a file this exists to leave alone. Matched without `\s`, which would span
+  // the blank line before an indented one and report its own newline as indent.
+  const indented = /\n([ \t]+)\S/.exec(text);
+  // A file written on one line was written that way on purpose, and expanding it
+  // is the same unasked-for rewrite as changing its indent.
+  const oneLine = !text.trimEnd().includes("\n");
+  // Ten is what `JSON.stringify` itself honours; more is silently truncated,
+  // and truncating here keeps what is written equal to what was measured.
+  return {
+    indent: oneLine ? 0 : (indented === null ? 2 : indented[1].slice(0, 10)),
+    trailingNewline: text.endsWith("\n"),
+  };
+}
+
+/**
+ * Write a file ACC did not create, keeping the shape of what was there.
+ *
+ * Unchanged content is not rewritten at all, so a second install touches
+ * nothing. A file that does not exist yet is ACC's to create, and gets the
+ * conventional trailing newline.
+ */
+export async function writeForeignJson(file, value, { readFile, writeFile, mkdir }) {
+  const current = await readFile(file, "utf8").catch(() => null);
+  const text = formatJsonAs(value, jsonStyleOf(current));
+  if (current === text) return false;
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, text);
+  return true;
+}
+
+export function formatJsonAs(value, style) {
+  const measured = style?.indent;
+  const indent = typeof measured === "string" && measured !== "" ? measured
+    : (Number.isInteger(measured) && measured >= 0 ? measured : 2);
+  const text = JSON.stringify(value, null, indent);
+  return style?.trailingNewline === false ? text : `${text}\n`;
+}
+
+/**
+ * Remove a file ACC wrote once nothing is left in it.
+ *
+ * The same rule as a container ACC created: what is empty was ACC's alone, and
+ * leaving it is litter in a home that did not have it. Measured after an install
+ * and uninstall in a home that started with nothing - four files left behind,
+ * two of them empty, one a marketplace manifest naming ACC's own marketplace.
+ *
+ * It was already fixed for two registries. The fixture that proved it seeded
+ * every config first, so the branch where ACC creates the file was never taken:
+ * the instance was fixed and the shape was not.
+ */
+export function acccreatedFile(value) {
+  return value?.[CREATED_FILE] === true;
+}
+
+export async function removeIfEmpty(file, { readFile, rm, isEmpty, created = true }) {
+  if (created !== true) return false;
+  const current = await readFile(file, "utf8").catch(() => null);
+  if (current === null) return false;
+  let empty;
+  try {
+    empty = isEmpty(current);
+  } catch {
+    // Unparseable is not empty. A file nobody can read is the user's to fix,
+    // and deleting it would take whatever it was meant to hold.
+    return false;
+  }
+  if (!empty) return false;
+  await rm(file, { force: true });
+  return true;
+}
+
+/** Nothing but whitespace, for the clients whose config is TOML. */
+export const blankText = text => text.trim() === "";
+
+/** An object with no keys, or only the ones named as ACC's own. */
+export const blankJson = (ours = []) => text => {
+  const value = JSON.parse(text);
+  if (value === null || typeof value !== "object") return false;
+  return Object.entries(value)
+    .every(([key, held]) => ours.includes(key)
+      || (Array.isArray(held) ? held.length === 0
+        : held !== null && typeof held === "object" && Object.keys(held).length === 0));
+};