agents-can-communicate 0.1.18 → 0.2.0

package/README.md

@@ -4,101 +4,109 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
 
-**Give the agent sessions you already opened a shared room — and stop being the wire
-between them.**
+ACC connects independently opened AI sessions so they can discover, ask, answer, acknowledge, and hand off without becoming one managed agent team.
 
-ACC is a local-first coordination layer for independent AI coding sessions on one repo.
-They see who else is here, claim the files they touch, message each other directly, and
-hand work across — while each keeps its own client, checkout, permissions, and human. It
-runs entirely on your machine, on Node's standard library with **zero runtime
-dependencies**, and your transcripts never leave the client.
+It is a local-first communication layer for sessions you already run. Each session keeps
+its own client, model, checkout, permissions, context, and human direction. ACC supplies a
+shared room with presence, intent, narrow file claims, durable conversation threads, and
+truthful per-recipient receipts. It does not launch, steer, supervise, or terminate agents.
 
-## The wall is you
+The project uses Node's standard library with **zero runtime dependencies**. Coordination
+state stays in platform app data outside the repository, and ACC never collects raw
+transcripts.
 
-One session refactors and is about to remove a field called `item.drive`. Another, in a
-file you're not looking at, still reads it. Neither terminal knows the other exists — so
-either you carry the warning across by hand, or it ships broken.
+## Stop relaying between windows
 
-**Without ACC**, every warning, question, and handoff between sessions stops at you and
-starts again from you. **With ACC**, the sessions carry them to each other: the second
-agent sees the claim, gets the measured impact as a message, and the change lands in one
-piece. You go back to directing.
+One session finds that removing `item.drive` will break another area. A second session is
+working there, but neither client knows the other exists. Without ACC, the warning stops at
+you: copy it to the other window, copy the answer back, and repeat for every question.
+
+With ACC, the first session sends an attributed question. The second retrieves it, replies
+in the same thread, and thereby acknowledges the original. The first retrieves the answer.
+The message is durable throughout; neither model gains authority over the other.
 
 ```mermaid
-flowchart TB
-  Y["You — set direction"]
-  A["session A"]
-  B["session B"]
-  C["session C"]
-  R["ACC shared room<br/>presence · claims · messages · handoffs"]
-  Y --> A
-  Y --> B
-  Y --> C
-  A <--> R
-  B <--> R
-  C <--> R
+flowchart LR
+  A["session A — independently opened"] <--> R["ACC room<br/>presence · messages · receipts · claims"]
+  B["session B — independently opened"] <--> R
+  U["You — direction and authority"] --> A
+  U --> B
 ```
 
+The product's canonical activation event is simple: a second independently opened session
+completes a useful acknowledged interaction without the human copying peer message content.
+
 ## Install
 
-Two commands, once per macOS or Linux machine where your clients run:
+On macOS or Linux with Node 24 or newer:
 
 ```bash
 npm install -g agents-can-communicate
 acc install
 ```
 
-`acc install` wires ACC into the clients you have — Codex, Claude Code, Gemini CLI, Grok,
-Kimi Code — and names everything it changed. **Restart the client afterwards** (hooks load
-at startup); Codex also needs you to trust the plugin. Then just open a session in a
-project and it joins that project's room by itself; open a second and they coordinate.
-`acc doctor` shows what's active, `acc update --apply` keeps it current, `acc uninstall`
-removes only what ACC wrote.
+Restart the clients whose hooks were installed; Codex also requires trusting the plugin.
+Then open two sessions in the same repository or plain directory as usual. They remain
+independent and join the same ACC workspace. Use `acc doctor` to see exact versions,
+installation health, and delivery downgrades.
 
-Coordination data lives in the platform app-data directory (`~/Library/Application
-Support/acc`, `~/.local/share/acc`; override with `ACC_DATA_HOME`), never in your repo.
-Every worktree of a repo shares one room; a plain folder works the same.
+Runtime state lives in `~/Library/Application Support/acc` on macOS or the XDG data
+directory on Linux. `ACC_DATA_HOME` can override it, but ACC refuses a location inside a
+workspace. Git is optional; worktrees of one repository share awareness.
 
-## What the room holds
+## The communication loop
 
-| | |
-|---|---|
-| **presence** | who's live, their client and branch, and what each intends — one `acc status`. |
-| **claims** | the files each session is touching; on guardable clients a clashing edit is refused and the owner named. |
-| **messages** | questions, decisions, notes — attributed, delivered on the recipient's next turn, and data they weigh rather than orders. |
-| **requests & handoffs** | work addressed to a participant, so it waits across restarts and carries the answer back. |
+```bash
+# Session A publishes awareness and reserves only what it will edit.
+acc work --summary "changing the item schema" --mode edit --hint 'file:src/item.mjs'
+acc claim --resource 'file:src/item.mjs' --reason "changing the item schema"
 
-A targeted `acc inbox` survives context compaction, and `acc reply` answers and
-acknowledges in one operation. A session alone in a repo pays nothing — no banner, no
-protocol, nothing left behind.
+# Session A asks a participant named by `acc status`.
+acc message --to models --type question --subject "item.drive" \
+  --body "Can your code stop reading item.drive before I remove it?"
 
-## Everyday controls
+# Session B reads and answers the exact message.
+acc inbox --message message_x
+acc reply --message message_x --body "Yes. Commit abc123 removes the final read."
 
-The installed guidance teaches your agents to claim, ask, request, and hand off on their
-own. These give you a direct view when you want one:
+# Either session records a handoff while context is still available.
+acc finish --goal "remove item.drive" --status complete \
+  --completed "schema and reader updated" --remaining "none"
+```
 
-| Command | For |
-|---|---|
-| `acc status` | who's here, what they claim, and the room's protection level |
-| `acc inbox` | recover an addressed message without a workspace dump |
-| `acc reply` | answer and acknowledge in one operation |
-| `acc doctor` | confirm which client integrations are active and current |
-| `acc update --apply` | install the latest release and refresh integrations |
-| `acc uninstall` | remove ACC's integrations — settings you changed stay yours |
+Messages commit before any delivery attempt. `queued`, `offered`, `retrieved`, and
+`acknowledged` describe different observable facts: an offer is not a read, retrieval is
+not proof of model attention, and a reply resolves communication rather than proving a
+requested task finished.
 
-## Documentation
+Durable inbox recovery is the baseline for every client. Certified next-turn injection can
+reduce the polling, but only for the exact client version and platform captured by the
+adapter. Native live push is opt-in and would also require a current reachable binding;
+**no shipped adapter currently has passing live-push certification**. The failed Codex
+0.152.0 and Claude Code 2.1.252 captures are shipped as evidence, so ACC reports fallback
+instead of claiming realtime delivery.
+
+## What ACC owns
 
-Start at the **[documentation map](docs/index.md)** — it lays out a path for whatever
-brought you here: [why ACC](docs/WHY_ACC.md) and [concepts](docs/CONCEPTS.md) to evaluate
-it, [getting started](docs/GETTING_STARTED.md) to run it, the [CLI](docs/CLI.md) /
-[protocol](docs/PROTOCOL.md) / [capabilities](docs/CAPABILITIES.md) reference, and
-[adapter authoring](docs/ADAPTER_AUTHORING.md) to extend it. New to the vocabulary? The
-[glossary](docs/GLOSSARY.md) defines every term in one line.
+| ACC owns | ACC does not own |
+|---|---|
+| participant and session presence | process or model lifecycle |
+| current intent and resource claims | prompts, permissions, or token budgets |
+| messages, threads, replies, acknowledgements | work queues or execution state |
+| delivery evidence and visible fallback | raw transcripts or shared model memory |
 
-See it run: [three workstreams](examples/three-workstreams.md) · [research in a plain
-folder](examples/non-git-research.md). Contributing starts with [AGENTS.md](AGENTS.md).
+A peer message is untrusted input, never system authority. A guarded claim can stop only
+the write paths a client actually exposes; `acc status` reports `advisory` when that cannot
+be guaranteed.
+
+## Documentation
 
-## Requirements & license
+Start with [Getting started](docs/GETTING_STARTED.md), then use the
+[documentation map](docs/index.md). The exact surfaces are in the [CLI](docs/CLI.md),
+[MCP](docs/MCP.md), [Protocol](docs/PROTOCOL.md), and
+[Capabilities](docs/CAPABILITIES.md) references. Adapter evidence lives beside each
+adapter in its `COMPATIBILITY.md` and `certification.json`.
 
-Node 24+, macOS or Linux, Git optional. MIT — use it, fork it, keep it
-([LICENSE](LICENSE)).
+Contributing starts with the repository's
+[AGENTS.md](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md).
+Node 24+, Git optional, MIT licensed.

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security policy
+
+## Reporting
+
+Report privately via [GitHub security advisories](https://github.com/automatis-tools/agents-can-communicate/security/advisories/new).
+
+Please do not open a public issue first.
+
+Include: what you ran, what happened, what you expected, and the client and
+version. A reproduction against a throwaway `ACC_DATA_HOME` is ideal.
+
+## Scope
+
+| In scope | Out of scope |
+|---|---|
+| Peer text escaping its quoted block | An attacker who already has write access to your data home |
+| Any path escaping the managed root | A model choosing to obey persuasive peer text |
+| Uninstall deleting files ACC did not write | Vulnerabilities in Codex, Claude Code, Gemini, Grok, or Kimi themselves |
+| ACC writing into a repository | Denial of service by a trusted peer |
+| Session impersonation across MCP | |
+
+Reasoning behind each: [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md).
+
+## Supported versions
+
+Pre-1.0: the latest release only.
+
+## What we will do
+
+Acknowledge, reproduce, and tell you whether it is in scope. If it is, the fix
+ships with a test in `tests/security/` so it cannot come back quietly.

package/bin/acc-hook.mjs

@@ -6,6 +6,8 @@
 // someone's session stops working. Unknown adapter, malformed payload, broken
 // store, missing binding - all of them end in "allow, exit 0".
 import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 import { createId } from "@agents-can-communicate/protocol";
 import { runHook } from "@agents-can-communicate/hook-runner";
@@ -36,20 +38,100 @@ const readStdin = () => new Promise(resolve => {
   return undefined;
 });
 
-const [adapterId] = process.argv.slice(2);
+export const writeOutput = (stream, output, { deadlineAt } = {}) => {
+  if (output === "") return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      if (error === undefined || error === null) resolve();
+      else reject(error);
+    };
+    if (deadlineAt !== undefined) {
+      const remaining = deadlineAt - Date.now();
+      if (remaining <= 0) {
+        finish(new Error("hook budget exhausted before stdout write"));
+        return;
+      }
+      timer = setTimeout(() => finish(
+        new Error("hook budget exhausted waiting for stdout callback")), remaining);
+    }
+    try {
+      stream.write(output, finish);
+    } catch (error) {
+      finish(error);
+    }
+  });
+};
+
+const DIAGNOSTIC_BYTES = 512;
+
+function boundedDiagnostic(label, error) {
+  const detail = String(error?.message ?? error).replace(/[\u0000-\u001f\u007f]/g, " ");
+  let line = `acc: ${label}: ${detail}`;
+  while (Buffer.byteLength(`${line}\n`, "utf8") > DIAGNOSTIC_BYTES && line.length > 0) {
+    line = line.slice(0, -1);
+  }
+  return `${line}\n`;
+}
 
-let payload = null;
+function tryWrite(stream, output) {
+  if (output === "") return;
+  try {
+    stream.write(output, () => {});
+  } catch {
+    // A broken diagnostic stream must not turn a failed-open hook into a crash.
+  }
+}
+
+export async function completeHookOutput(result,
+  { stdout = process.stdout, stderr = process.stderr } = {}) {
+  try {
+    await writeOutput(stdout, result.stdout ?? "", { deadlineAt: result.deadlineAt });
+  } catch (error) {
+    tryWrite(stderr, boundedDiagnostic("stdout write failed", error));
+    return { exitCode: 0, wroteStdout: false, committedOffers: false };
+  }
+
+  let committedOffers = true;
+  try {
+    await result.commitOffers?.();
+  } catch (error) {
+    committedOffers = false;
+    tryWrite(stderr, boundedDiagnostic("offer commit failed", error));
+  }
+  if (result.stderr) tryWrite(stderr, `${result.stderr}\n`);
+  return { exitCode: 0, wroteStdout: true, committedOffers };
+}
+
+async function main() {
+  const [adapterId] = process.argv.slice(2);
+
+  let payload = null;
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = null;
+  }
+
+  const result = await runHook({ adapterId, payload, adapters,
+    runtime: { clock: { now: () => new Date().toISOString() },
+      ids: { next: kind => createId(kind, randomBytes) } },
+    env: process.env });
+
+  const completed = await completeHookOutput(result);
+  process.exitCode = result.exitCode ?? completed.exitCode;
+}
+
+let isMain = false;
 try {
-  payload = JSON.parse(await readStdin());
+  isMain = process.argv[1] !== undefined
+    && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
 } catch {
-  payload = null;
+  isMain = false;
 }
 
-const result = await runHook({ adapterId, payload, adapters,
-  runtime: { clock: { now: () => new Date().toISOString() },
-    ids: { next: kind => createId(kind, randomBytes) } },
-  env: process.env });
-
-if (result.stdout !== "") process.stdout.write(result.stdout);
-if (result.stderr) process.stderr.write(`${result.stderr}\n`);
-process.exitCode = result.exitCode ?? 0;
+if (isMain) await main();

package/bin/acc-mcp.mjs

@@ -3,8 +3,9 @@ import { randomBytes } from "node:crypto";
 
 import { EXIT, createId } from "@agents-can-communicate/protocol";
 import { createCoordinationService } from "@agents-can-communicate/core";
+import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
-import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
+import { ALL_ADAPTERS, createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
   from "@agents-can-communicate/cli";
 import { serve } from "@agents-can-communicate/mcp-server";
 
@@ -40,13 +41,16 @@ const paths = runtimePaths({
 });
 const store = await openFilesystemStore({ root: paths.root, clock, ids,
   workspaceId: descriptor.id });
+const service = createCoordinationService({ store, clock, ids });
+const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
 
 await serve({
   input: process.stdin,
   output: process.stdout,
   log: message => process.stderr.write(`acc-mcp: ${message}\n`),
   context: {
-    service: createCoordinationService({ store, clock, ids }),
+    service,
+    deliveryRouter: createDeliveryRouter({ service, adapters, clock }),
     workspaceId: descriptor.id,
     participantId,
     descriptor,

package/bin/acc.mjs

@@ -3,7 +3,10 @@ import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 
 import { createId } from "@agents-can-communicate/protocol";
-import { askConfirmation, main } from "@agents-can-communicate/cli";
+import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
+import { ALL_ADAPTERS, askConfirmation, main } from "@agents-can-communicate/cli";
+
+const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
 
 // The composition root is the only place allowed to reach for ambient time and
 // randomness; everything below it receives them as ports.
@@ -15,6 +18,8 @@ const runtime = {
   stderr: process.stderr,
   clock: { now: () => new Date().toISOString() },
   ids: { next: kind => createId(kind, randomBytes) },
+  createDeliveryRouter: ({ service, clock }) =>
+    createDeliveryRouter({ service, adapters, clock }),
   // Asked only by `acc config init`, and only when stdout is a terminal. There
   // was no port here at all, so the question went to the fallback that always
   // answers no: in a real terminal the command printed "not written" and never

package/docs/ADAPTER_AUTHORING.md

@@ -0,0 +1,172 @@
+# Writing an adapter
+
+An adapter teaches ACC one client. Nothing else in ACC knows that client exists. This page
+assumes the vocabulary in [Protocol](PROTOCOL.md#identity-hierarchy) — session, participant,
+claim — and points to [Capabilities](CAPABILITIES.md) for what was actually measured per
+client; see the [documentation map](index.md) for where both fit among the rest.
+
+```mermaid
+graph LR
+  H[client hook] --> R[acc-hook runtime]
+  R -->|normalizeHook| E[normalised event]
+  E --> CO[core: attach, claims, sync]
+  CO -->|denyOutcome / injectOutcome| R
+  R --> H
+```
+
+## The manifest
+
+```js
+export function createExampleAdapter() {
+  return defineAdapter({
+    id: "example",                    // portable id
+    displayName: "Example CLI",
+    client: { command: "example", certificationName: "example-cli",
+      versionArgs: ["--version"] },
+    certification,                    // imported package-local certification.json
+    capabilities: { delivery: { nextTurn: true } },
+
+    detect, install, uninstall, doctor,
+    planInstall,                      // what install would write
+    normalizeHook,                    // client payload -> normalised event
+    renderContext,                    // SyncResult -> text
+    renderContextResult,              // text + ids of complete rendered groups
+    denyOutcome, injectOutcome,       // how this client is answered
+  });
+}
+```
+
+`renderContextResult` is required wherever an adapter renders peer messages. It returns
+`{ text, includedMessageIds, includedAttentionIds }`, and the [delivery
+lifecycle](PROTOCOL.md#delivery-lifecycle) advances only from those ids — never by searching
+`text` for one, because peer text is untrusted and can imitate another message's header.
+`projectContextResult()` implements this contract; `projectContext()` remains the text-only
+convenience API for adapters that don't need it. An adapter with only the older
+`renderContext()` gets pending bodies withheld and a visible `acc inbox` degradation warning
+instead: repeating an untracked body every turn would be quieter in code and dishonest about
+what was actually delivered.
+
+`client.command` does double duty. `detect.mjs` uses it as the version-probe binary, and
+presence liveness separately walks the hook's process ancestry for the first ancestor whose
+executable basename matches it, to learn the client's own pid. Declare the binary the client
+actually runs as — `command: "claude"` for a client that really runs as `node` resolves
+nothing, and the failure is silent: the session gets `pid: null` and falls back to reading
+presence by age alone, with nothing telling you why.
+
+## Capabilities
+
+Fourteen booleans in four groups, declared in the manifest's `capabilities` object:
+
+| Group | Entries |
+|---|---|
+| `lifecycle` | `sessionStart` `sessionResume` `sessionEnd` `heartbeat` `childSessions` |
+| `context` | `startupInjection` `beforeTurnInjection` `safePointInjection` |
+| `guards` | `beforeRead` `beforeWrite` `beforeShell` |
+| `delivery` | `nextTurn` `livePush` `replyRoute` |
+
+**False by default. `true` requires a backing method *and* an observed capture.**
+`defineAdapter` enforces the method — declaring `guards.beforeWrite: true` without
+`guardWrite()` is a usage error at construction. It also requires a passing entry in the
+validated `certification.json`; method existence is never evidence. What each shipped
+client was actually observed doing against this list is [Capabilities](CAPABILITIES.md#matrix).
+
+`lifecycle.heartbeat` is deliberately not a flavour of `delivery.nextTurn`. Next-turn
+delivery happens only when the client reaches a normal turn boundary; heartbeat fires on a
+timer even while the session is idle.
+
+### Certification evidence
+
+Every adapter ships `certification.json` and every referenced capture under `fixtures/`.
+Each evidence entry contains `client`, exact `version`, exact `platform`, `observedAt`,
+`capability`, package-relative `fixture`, `idleBehavior`, `busyBehavior`,
+`authorityLevel`, `limitations`, and `result` (`pass` or `fail`). A copied documentation
+example is not a capture. Failed experiments stay in the manifest as `fail`; they explain
+the false value and can never enable it.
+
+`effectiveCapabilities(adapter, { clientVersion, platform })` returns the full boolean
+shape for the installed client. Only an exact passing version/platform match remains true.
+Unreadable, unknown, or mismatched clients degrade every uncertified row to false.
+
+The backing methods for delivery are `renderContextResult()` for `nextTurn`,
+`offerMessage()` for `livePush`, and `routeReply()` for `replyRoute`.
+
+## How far you can get
+
+| Tier | You register | You get | You do not get |
+|---|---|---|---|
+| 0 | nothing — humans run `acc` | durable messages, status, claims | anything automatic |
+| 1 | the MCP server | attach on first call, read, claim, message | guards, session end |
+| 2 | hooks + skill | automatic attach, turn context, write guards, cleanup | realtime |
+| 3 | + realtime surface | delivery receipts, safe-point injection, child sessions | — |
+
+Installed hook wiring may reach tier 2, but the effective capability is still limited to
+an exact certified client/version/platform. No client currently certifies native live push
+or native reply routing.
+
+## normalizeHook
+
+Whitelist, never a filter. Every client hands hooks the prompt, the transcript path, or the
+tool output; none of it may survive.
+
+```js
+return normalizedEvent({
+  kind, sessionId, cwd, model, parentSessionId, tool,
+  targets,   // paths this call would WRITE. For a shell call, pass the command to
+             // shellWriteTargets() — it reads write positions only, never reads.
+});
+```
+
+Refuse an unrecognised payload. Inventing a session attaches the wrong one, or a new one
+every hook, and looks like it is working.
+
+## Response contracts do not port
+
+Measure them. Every client differs, and a wrong shape fails **silently**:
+
+| | deny | inject |
+|---|---|---|
+| Codex | exit 2 + stderr | plain stdout (`developer` message) |
+| Claude Code | `hookSpecificOutput.permissionDecision` | same envelope |
+| Gemini CLI | `{"decision":"block"}` | `hookSpecificOutput` envelope |
+| Grok | `{"decision":"deny","reason"}` (documented; deny not yet captured) | UserPromptSubmit stdout discarded on 1.0.13 |
+| Kimi Code | `hookSpecificOutput.permissionDecision` | plain stdout |
+
+`denyOutcome(reason)` returns `{ stdout, stderr, exitCode }`, so the runtime never has to
+know which client it is talking to. This table is only the shape each shipped adapter
+actually uses; the full experimental grid — every candidate shape tried against every
+client, including which ones are silently ignored — is measured in
+[Capabilities](CAPABILITIES.md#response-contracts-which-do-not-port).
+
+## Install and ownership
+
+```mermaid
+graph TB
+  P[planInstall] -->|artifacts| K{kind}
+  K -->|tree| T[a directory ACC creates<br/>removable if unchanged]
+  K -->|merge| M[a file the user owns<br/>never deleted]
+```
+
+Rules that are not negotiable:
+
+- idempotent — installing twice equals installing once;
+- reversible — uninstall restores the user's file byte for byte;
+- absolute command paths — a hook's environment carries no PATH;
+- honour `keep`: uninstall receives paths the user has since edited.
+
+`planInstall` must use the same path helpers as `install`. A conformance test compares
+them, because a plan that drifts makes `--dry-run` a decoration.
+
+## Conformance
+
+```bash
+node --test tests/conformance/*.test.mjs
+node --test tests/process/hook-wiring.test.mjs
+```
+
+The second one *executes* what your install wrote. Three adapters once shipped a hook
+command that did not exist anywhere; every test was green.
+
+## Record what you learned
+
+One `COMPATIBILITY.md` per adapter: client version, event names, payload fields, the deny
+matrix, and what you could **not** observe. The next person's alternative is guessing.