agents-can-communicate 0.1.0

package/node_modules/@agents-can-communicate/core/src/ports.mjs

@@ -0,0 +1,56 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+/**
+ * @typedef {{ now(): string }} Clock
+ * @typedef {{ next(kind: string): string }} IdSource
+ * @typedef {{ get(kind: string, id: string): object | null,
+ *   generationOf(kind: string, id: string): string | null,
+ *   list(kind: string, predicate?: (record: object) => boolean): object[],
+ *   put(kind: string, id: string, record: object, expectedGeneration?: string | null): string,
+ *   append(event: object): object }} CoordinationTransaction
+ * @typedef {{ transaction(callback: (tx: CoordinationTransaction) => unknown): Promise<unknown>,
+ *   eventsSince(workspaceId: string, cursor: string | null, limit: number): Promise<object>,
+ *   snapshot(workspaceId: string): Promise<object> }} CoordinationStore
+ */
+
+const REQUIRED = Object.freeze({
+  store: ["transaction", "eventsSince", "snapshot"],
+  clock: ["now"],
+  ids: ["next"],
+});
+
+// Ephemeral records - presence and Intent before a workspace has materialised -
+// are storage too, so they hang off the store rather than becoming a fourth
+// port. They are deliberately outside transactions: they append no events and
+// vanish with their session.
+const EPHEMERAL = ["get", "put", "delete", "list"];
+
+// Ports are validated at construction rather than at first use. A core that
+// silently falls back to ambient time or randomness produces tests that pass
+// for the wrong reason and races that only appear on someone else's machine.
+export function assertPorts(ports) {
+  for (const [name, methods] of Object.entries(REQUIRED)) {
+    const port = ports[name];
+    if (port === null || typeof port !== "object") {
+      throw new AccError(EXIT.USAGE, `the ${name} port is required`, { port: name });
+    }
+    for (const method of methods) {
+      if (typeof port[method] !== "function") {
+        throw new AccError(EXIT.USAGE, `the ${name} port must implement ${method}()`,
+          { port: name, method });
+      }
+    }
+  }
+  const ephemeral = ports.store.ephemeral;
+  if (ephemeral === null || typeof ephemeral !== "object") {
+    throw new AccError(EXIT.USAGE, "the store port must expose an ephemeral area",
+      { port: "store" });
+  }
+  for (const method of EPHEMERAL) {
+    if (typeof ephemeral[method] !== "function") {
+      throw new AccError(EXIT.USAGE, `the store ephemeral area must implement ${method}()`,
+        { port: "store.ephemeral", method });
+    }
+  }
+  return ports;
+}

package/node_modules/@agents-can-communicate/core/src/service.mjs

@@ -0,0 +1,44 @@
+import { createClaimService } from "./claims.mjs";
+import { createCommunicationService } from "./communication.mjs";
+import { createIntentService } from "./intents.mjs";
+import { assertPorts } from "./ports.mjs";
+import { createSessionService } from "./sessions.mjs";
+import { createGuardStateService, createStatusService } from "./status.mjs";
+import { createSyncService } from "./sync.mjs";
+import { createTaskService } from "./tasks.mjs";
+import { createWorkstreamService } from "./workstreams.mjs";
+
+/**
+ * Composition root for the domain services. Everything time- or
+ * randomness-dependent arrives through a port, so behaviour is reproducible and
+ * no module reaches for a global.
+ *
+ * @param {{ store: object, clock: object, ids: object, policies?: object }} ports
+ */
+export function createCoordinationService({ store, clock, ids, policies = {} }) {
+  const ports = assertPorts({ store, clock, ids });
+  const sessions = createSessionService(ports);
+  const intents = createIntentService(ports, sessions);
+  const workstreams = createWorkstreamService(ports, sessions);
+  const tasks = createTaskService(ports, workstreams);
+  const claims = createClaimService(ports, sessions);
+  const communication = createCommunicationService(ports, sessions, claims);
+  const sync = createSyncService(ports, sessions);
+  const status = createStatusService(ports, sessions);
+  const guardState = createGuardStateService(ports);
+  return Object.freeze({
+    store,
+    clock,
+    ids,
+    policies: Object.freeze({ ...policies }),
+    ...sessions,
+    ...intents,
+    ...workstreams,
+    ...tasks,
+    ...claims,
+    ...communication,
+    ...sync,
+    ...status,
+    guardState,
+  });
+}

package/node_modules/@agents-can-communicate/core/src/sessions.mjs

@@ -0,0 +1,190 @@
+import { AccError, EXIT, SCHEMA_VERSION, assertPortableId, createId, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { ensureMaterialised, isMaterialised, materialise } from "./materialisation.mjs";
+import { writeWorkResponse } from "./notify.mjs";
+
+// A hook-only adapter heartbeats only when its harness gives it a turn, so the
+// staleness window is a multiple of the cadence the session itself declared
+// rather than one global constant (docs/ARCHITECTURE.md, presence freshness).
+const STALE_CADENCE_MULTIPLE = 3;
+
+/**
+ * @returns {"online" | "stale" | "offline"}
+ */
+export function classifySessionPresence(session, now, probe = () => true) {
+  if (session.state === "closed") return "offline";
+  if (!probe(session)) return "offline";
+  const age = Date.parse(now) - Date.parse(session.heartbeatAt);
+  return age <= session.heartbeatCadenceMs * STALE_CADENCE_MULTIPLE ? "online" : "stale";
+}
+
+const sessionRecord = (input, now, generation) => validateRecord("session", {
+  schemaVersion: SCHEMA_VERSION,
+  sessionId: input.sessionId,
+  participantId: input.participantId,
+  workspaceId: input.workspaceId,
+  generation,
+  harness: input.harness,
+  state: "open",
+  parentSessionId: input.parentSessionId ?? null,
+  checkoutRoot: input.checkoutRoot ?? null,
+  branch: input.branch ?? null,
+  // Both default to the weaker reading. A session that declares nothing is a
+  // session nothing intercepts - an MCP client, or a CLI user - and claiming
+  // otherwise would promise enforcement that is not there.
+  enforcement: input.enforcement ?? "advisory",
+  lifecycle: input.lifecycle ?? "manual",
+  heartbeatCadenceMs: input.heartbeatCadenceMs,
+  startedAt: now,
+  heartbeatAt: now,
+});
+
+const participantRecord = (input, now) => validateRecord("participant", {
+  schemaVersion: SCHEMA_VERSION,
+  participantId: input.participantId,
+  workspaceId: input.workspaceId,
+  displayName: input.displayName ?? input.participantId,
+  kind: input.participantKind ?? "agent",
+  createdAt: now,
+});
+
+export function createSessionService(ports) {
+  const { store, clock, ids } = ports;
+  const workspaceOf = input => input.workspaceId ?? store.workspaceId;
+
+  async function locate(sessionId, workspaceId) {
+    const ephemeral = await store.ephemeral.get("session", sessionId);
+    if (ephemeral !== null) return { record: ephemeral, durable: false };
+    const resolved = workspaceId ?? store.workspaceId;
+    if (resolved === undefined) return null;
+    const durable = (await store.snapshot(resolved, { kinds: ["session"] })).sessions
+      .find(session => session.sessionId === sessionId) ?? null;
+    return durable === null ? null : { record: durable, durable: true };
+  }
+
+  function assertReplaceable(existing, probe) {
+    if (existing.record.state === "closed") return;
+    // Presence staleness alone never replaces ownership: an idle-but-open
+    // session may resume at any moment. Only a liveness probe reporting the
+    // owner gone permits a replacement generation.
+    if (probe === undefined || probe(existing.record)) {
+      throw new AccError(EXIT.CONFLICT, "the session id is already live",
+        { sessionId: existing.record.sessionId });
+    }
+  }
+
+  function assertGeneration(existing, generation, action) {
+    if (existing.record.generation !== generation) {
+      throw new AccError(EXIT.CONFLICT, `cannot ${action} a replaced session generation`,
+        { sessionId: existing.record.sessionId, expected: generation,
+          actual: existing.record.generation });
+    }
+  }
+
+  async function openSession(input) {
+    const workspaceId = workspaceOf(input);
+    assertPortableId(workspaceId, "workspace id");
+    assertPortableId(input.participantId, "participant id");
+    const sessionId = input.sessionId ?? createId("session");
+    const existing = await locate(sessionId, workspaceId);
+    if (existing !== null) assertReplaceable(existing, input.probe);
+
+    const now = clock.now();
+    const session = sessionRecord({ ...input, workspaceId, sessionId }, now,
+      ids.next("generation"));
+    const participant = participantRecord({ ...input, workspaceId }, now);
+
+    if (await isMaterialised(store, workspaceId)) {
+      await store.transaction(async tx => {
+        const replaced = tx.get("session", sessionId)?.generation ?? null;
+        if (tx.get("participant", participant.participantId) === null) {
+          tx.put("participant", participant.participantId, participant);
+        }
+        tx.put("session", sessionId, session, tx.generationOf("session", sessionId));
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+          actorSessionId: sessionId, type: "session.opened", occurredAt: now,
+          payload: { replaced } });
+      }, { kinds: ["participant", "session"] });
+      return session;
+    }
+
+    await store.ephemeral.put("participant", participant.participantId, participant);
+    await store.ephemeral.put("session", sessionId, session);
+    // The approved trigger is the SECOND live session, not the first: a lone
+    // session must be able to open and close without leaving a trace.
+    const live = (await store.ephemeral.list("session")).filter(item => item.state === "open");
+    if (live.length > 1) {
+      await materialise(ports, { workspaceId, descriptor: input.descriptor,
+        reason: "second_live_session" });
+    }
+    return session;
+  }
+
+  async function heartbeatSession({ sessionId, workspaceId, generation }) {
+    const existing = await locate(sessionId, workspaceId);
+    if (existing === null) throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
+    assertGeneration(existing, generation, "heartbeat");
+    const beaten = { ...existing.record, heartbeatAt: clock.now() };
+
+    // Heartbeats never append to the semantic event feed: only open, close, and
+    // presence transitions surface through cursor sync (spec section 6.4).
+    if (!existing.durable) {
+      await store.ephemeral.put("session", sessionId, beaten);
+      return beaten;
+    }
+    await store.transaction(async tx =>
+      tx.put("session", sessionId, beaten, tx.generationOf("session", sessionId)),
+    { kinds: ["session"] });
+    return beaten;
+  }
+
+  async function closeSession({ sessionId, workspaceId, generation }) {
+    const existing = await locate(sessionId, workspaceId);
+    if (existing === null) throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
+    assertGeneration(existing, generation, "close");
+    const now = clock.now();
+    const closed = { ...existing.record, state: "closed", heartbeatAt: now };
+
+    if (!existing.durable) {
+      // An ephemeral-only workspace vanishes with its sessions: nothing durable
+      // was written, so nothing has to be cleaned up later.
+      await store.ephemeral.delete("session", sessionId);
+      await store.ephemeral.delete("intent", sessionId);
+      return closed;
+    }
+
+    await store.transaction(async tx => {
+      tx.put("session", sessionId, closed, tx.generationOf("session", sessionId));
+      // Work in progress goes back on the table. A task held by a session that
+      // has gone stayed `in_progress` forever, nobody else could take it, and
+      // whoever asked for it was never told - a request handed to an agent that
+      // closed its terminal simply vanished.
+      for (const task of tx.list("task")) {
+        if (task.assigneeSessionId !== sessionId) continue;
+        if (task.state === "done") continue;
+        const released = { ...task, assigneeSessionId: null, state: "pending" };
+        tx.put("task", task.taskId, released, tx.generationOf("task", task.taskId));
+        writeWorkResponse(tx, { task, actor: closed, workspaceId: closed.workspaceId,
+          now, ids, outcome: "released",
+          reason: "the session working on this closed before finishing it" });
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+          workspaceId: closed.workspaceId, actorSessionId: sessionId,
+          type: "task.released", occurredAt: now, payload: { taskId: task.taskId } });
+      }
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: closed.workspaceId, actorSessionId: sessionId, type: "session.closed",
+        occurredAt: now, payload: {} });
+    // `writeWorkResponse` tells whoever asked, on this same handle.
+    }, { kinds: ["message", "receipt", "session", "task"] });
+    return closed;
+  }
+
+  return {
+    openSession,
+    heartbeatSession,
+    closeSession,
+    locateSession: locate,
+    ensureMaterialised: options => ensureMaterialised(ports, options),
+  };
+}

package/node_modules/@agents-can-communicate/core/src/status.mjs

@@ -0,0 +1,132 @@
+import { classifySessionPresence } from "./sessions.mjs";
+import { computeAttention } from "./sync.mjs";
+
+/**
+ * Protection level, reported from what is actually enforceable.
+ *
+ * A guarded claim only protects anything if every live session can be stopped
+ * from writing through it. One MCP client with no hooks, or one harness whose
+ * model edits through the shell, and the claim is advice - so the workspace is
+ * advisory however the claims were written. Reporting "guarded" there would
+ * promise enforcement that demonstrably is not present.
+ */
+function protectionOf(claims, live) {
+  if (claims.length === 0) return "none";
+  const enforceable = live.every(item => item.session.enforcement === "guarded");
+  if (!enforceable) return "advisory";
+  return claims.every(claim => claim.enforcement === "guarded") ? "guarded" : "advisory";
+}
+
+/**
+ * The two things the write guard has to know, and nothing else.
+ *
+ * `collectStatus` answers a person's question and reads the whole store to do
+ * it. The guard asks a much smaller one - who holds a live claim, and what is
+ * that owner called - in front of *every file an agent writes*. Reading
+ * everything there made the cost grow with the number of messages the workspace
+ * had ever carried: measured at about 1.4ms per stored record, so a workspace
+ * with a few thousand crosses the hook's five-second budget, after which it
+ * fails open and the write goes through unguarded.
+ *
+ * Sessions and claims are bounded by what is live. Messages, receipts, tasks and
+ * events are not bounded by anything, and none of them decides whether a write
+ * is allowed.
+ */
+export function createGuardStateService(ports) {
+  const { store, clock } = ports;
+
+  return async function guardState(input = {}) {
+    const workspaceId = input.workspaceId ?? store.workspaceId;
+    const now = clock.now();
+    const snapshot = await store.snapshot(workspaceId, { kinds: ["workspace", "session", "claim"] });
+    const sessions = snapshot.workspace !== null
+      ? snapshot.sessions
+      : await store.ephemeral.list("session");
+
+    return {
+      claims: snapshot.claims
+        .filter(claim => Date.parse(claim.expiresAt) > Date.parse(now)),
+      participants: sessions.map(session => ({
+        sessionId: session.sessionId,
+        participantId: session.participantId,
+        // So the guard can tell whether this session has looked alive recently
+        // without a second read. Bounded like the rest of what it asks for.
+        heartbeatAt: session.heartbeatAt,
+      })),
+    };
+  };
+}
+
+export function createStatusService(ports, sessions) {
+  const { store, clock } = ports;
+
+  async function collectStatus(input = {}) {
+    const workspaceId = input.workspaceId ?? store.workspaceId;
+    const now = clock.now();
+    const snapshot = await store.snapshot(workspaceId);
+
+    // A workspace that has not materialised still has a truthful status: its
+    // sessions and intents live in the ephemeral area.
+    const durable = snapshot.workspace !== null;
+    const sessionRecords = durable
+      ? snapshot.sessions
+      : await store.ephemeral.list("session");
+    const intents = durable ? snapshot.intents : await store.ephemeral.list("intent");
+    const live = sessionRecords
+      .map(session => ({ session, presence: classifySessionPresence(session, now) }))
+      .filter(item => item.presence !== "offline");
+    const claims = snapshot.claims
+      .filter(claim => Date.parse(claim.expiresAt) > Date.parse(now));
+
+    return {
+      workspaceId,
+      materialised: durable,
+      protection: protectionOf(claims, live),
+      // Who is here, unless the caller asks for everyone who ever was. A closed
+      // session is never removed - a message is attributed to its sender, and
+      // the roster is where "which worktree was that agent in" is answered - so
+      // after a month of work this listed sixty entries for one live session.
+      // `acc status --all` is how the worktree-cleanup question is asked.
+      participants: sessionRecords
+        .filter(session => input.all === true
+          || classifySessionPresence(session, now) !== "offline")
+        .map(session => ({
+        sessionId: session.sessionId,
+        participantId: session.participantId,
+        harness: session.harness,
+        parentSessionId: session.parentSessionId,
+        checkoutRoot: session.checkoutRoot ?? null,
+        branch: session.branch ?? null,
+        enforcement: session.enforcement ?? "advisory",
+        lifecycle: session.lifecycle ?? "manual",
+        presence: classifySessionPresence(session, now),
+        intent: intents.find(intent => intent.sessionId === session.sessionId)?.summary ?? null,
+      })),
+      workstreams: snapshot.workstreams.map(workstream => ({
+        workstreamId: workstream.workstreamId,
+        title: workstream.title,
+        state: workstream.state,
+        coordinatorSessionId: workstream.coordinatorSessionId,
+      })),
+      claims: claims.map(claim => ({
+        claimId: claim.claimId,
+        resource: claim.resource,
+        mode: claim.mode,
+        enforcement: claim.enforcement,
+        ownerSessionId: claim.ownerSessionId,
+        expiresAt: claim.expiresAt,
+      })),
+      attention: computeAttention(snapshot, { session: null,
+        participantId: input.participantId, now }),
+      counts: {
+        live: live.length,
+        stale: live.filter(item => item.presence === "stale").length,
+        claims: claims.length,
+        tasks: snapshot.tasks.length,
+        messages: snapshot.messages.length,
+      },
+    };
+  }
+
+  return { collectStatus, locateSession: sessions.locateSession };
+}