agents-can-communicate 0.1.17 → 0.2.0

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

@@ -4,6 +4,7 @@ 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 { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
 import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
 import { applyPlan, detectInstallation, loadOwnership, planInstallation }
   from "@agents-can-communicate/installer";
@@ -23,6 +24,7 @@ export const clientContext = (home, stateRoot) => ({
   agentsHome: home,
   codexHome: path.join(home, ".codex"),
   kimiHome: path.join(home, ".kimi-code"),
+  grokHome: path.join(home, ".grok"),
   // Where ACC keeps its own state, for the client that has to be told. Codex
   // sandboxes the commands a model runs to the workspace, and ACC's state is
   // outside every workspace on purpose - so an agent there could read the
@@ -32,7 +34,7 @@ export const clientContext = (home, stateRoot) => ({
 });
 
 export const ALL_ADAPTERS = () => [createClaudeCodeAdapter(), createCodexAdapter(),
-  createGeminiCliAdapter(), createKimiAdapter()];
+  createGeminiCliAdapter(), createGrokAdapter(), createKimiAdapter()];
 
 /**
  * How long to wait for a client to say its version.
@@ -108,6 +110,8 @@ export function describeChanges(operation, home) {
   }
   return [
     ...(operation.removed ?? []).map(file => `  removed ${shorten(file, home)}`),
+    ...(operation.removedDirectories ?? [])
+      .map(file => `  removed ${shorten(file, home)}`),
     ...edited,
     ...(operation.kept ?? [])
       .map(file => `  kept    ${shorten(file, home)} - changed since ACC wrote it`),
@@ -120,6 +124,9 @@ export function describeOutcome({ action, acted, failed = [], skipped = [],
     + (failed.length > 0 ? `; ${failed.length} failed` : ""),
   ...operations.filter(operation => operation.applied)
     .flatMap(operation => describeChanges(operation, home)),
+  ...operations.filter(operation => operation.applied
+    && typeof operation.deliveryDiagnostic === "string")
+    .map(operation => `  ${operation.deliveryDiagnostic}`),
   ...skipped.map(entry => `  skip ${entry.adapterId}: ${entry.reason}`),
   ...failed.map(entry => `  ${entry.adapterId}: ${entry.error}`),
   // Said once, where it is needed: the reader has just been shown a list of
@@ -163,7 +170,8 @@ export function failureOf({ action, acted, failed = [] }) {
 export function actedOn(result) {
   return result.operations.filter(operation => operation.applied
     && (result.action === "install"
-      || (operation.removed?.length ?? 0) + (operation.changes?.length ?? 0) > 0)).length;
+      || (operation.removed?.length ?? 0) + (operation.removedDirectories?.length ?? 0)
+        + (operation.changes?.length ?? 0) > 0)).length;
 }
 
 export async function runInstallCommand({ options, runtime, action = "install" }) {
@@ -198,7 +206,8 @@ export async function runInstallCommand({ options, runtime, action = "install" }
     ? []
     : (Array.isArray(options.adapter) ? options.adapter : [options.adapter]);
   const plan = planInstallation({ adapters, detected, context, action, recorded,
-    accVersion, allowDowngrade: options.downgrade === true, requested });
+    accVersion, allowDowngrade: options.downgrade === true, requested,
+    delivery: options.delivery ?? "off" });
   const result = await applyPlan({ plan, adapters, context, dataHome, dryRun, accVersion });
 
   const acted = actedOn(result);

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

@@ -1,4 +1,9 @@
-import { AccError, CONFIG_FILENAME, EXIT, failure, ok }
+// Kept cohesive above 300 lines because this is the single CLI composition boundary: every
+// handler shares one owner-resolution, result, and error contract with `main`. Splitting the
+// dispatch table would either duplicate that contract or expose storage/runtime context solely
+// to pass it across a module boundary, making command behavior harder to audit as one surface.
+import { AccError, CONFIG_FILENAME, EXIT, GENERIC_MESSAGE_KINDS, VALID_OBLIGATIONS,
+  failure, ok }
   from "@agents-can-communicate/protocol";
 import { createCoordinationService } from "@agents-can-communicate/core";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
@@ -80,8 +85,11 @@ async function locateContext(options, runtime) {
 async function withService({ descriptor, paths }, runtime) {
   const store = await openFilesystemStore({ root: paths.root, clock: runtime.clock,
     ids: runtime.ids, workspaceId: descriptor.id });
+  const service = createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids });
   return { descriptor, paths,
-    service: createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids }) };
+    service,
+    deliveryRouter: typeof runtime.createDeliveryRouter === "function"
+      ? runtime.createDeliveryRouter({ service, clock: runtime.clock }) : null };
 }
 
 async function openContext(options, runtime) {
@@ -107,6 +115,49 @@ async function openDiagnosticContext(options, runtime) {
 
 const human = value => (typeof value === "string" ? value : JSON.stringify(value, null, 2));
 
+const clientMessageId = (options, context) =>
+  options.clientMessageId ?? context.service.ids.next("client");
+
+function obligationFor(kind, explicit, addressed) {
+  if (!GENERIC_MESSAGE_KINDS.includes(kind)) {
+    const command = kind === "answer" ? "reply" : kind === "handoff" ? "finish" : "message";
+    throw usage(kind === "answer" || kind === "handoff"
+      ? `${kind} messages require acc ${command}` : `unknown message type: ${kind}`);
+  }
+  const obligation = explicit ?? VALID_OBLIGATIONS[kind][0];
+  if (!VALID_OBLIGATIONS[kind].includes(obligation)
+    || (!addressed && obligation !== "none")) {
+    throw usage(`message obligation ${obligation} is invalid for ${kind}`);
+  }
+  return obligation;
+}
+
+function recordedText(message, delivery) {
+  const diagnostics = delivery.map(item => item.outcome === "offered"
+    ? `live offered to ${item.recipientParticipantId} via ${item.transport}`
+    : item.outcome === "queued"
+      ? `live offer unavailable (${item.errorCode ?? "durable_fallback"})`
+      : `delivery already ${item.outcome}`);
+  return [`recorded ${message.messageId}`, ...diagnostics].join("; ");
+}
+
+export async function recordAndOffer({ record, router, selectMessage = value => value }) {
+  const recorded = await record();
+  const message = selectMessage(recorded);
+  if (router === null || router === undefined
+    || !Array.isArray(message?.toParticipantIds) || message.toParticipantIds.length === 0) {
+    return { recorded, delivery: [] };
+  }
+  try {
+    return { recorded, delivery: await router.offer(message) };
+  } catch {
+    return { recorded, delivery: message.toParticipantIds.map(recipientParticipantId => ({
+      recipientParticipantId, outcome: "queued", transport: "durable",
+      errorCode: "transport_error",
+    })) };
+  }
+}
+
 /** How many are here, and how many only look it. */
 export function describePresence({ live = 0, stale = 0 } = {}) {
   if (live === 0) return "0 live";
@@ -168,8 +219,7 @@ const HANDLERS = Object.freeze({
     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 ?? [] });
+      state: options.state, resourceHints: options.hint ?? [] });
     return { data: intent, text: `intent: ${intent.summary}` };
   },
 
@@ -194,122 +244,72 @@ const HANDLERS = Object.freeze({
   },
 
   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}` };
+    const kind = options.type ?? "note";
+    const toParticipantIds = options.to ?? [];
+    const routed = await recordAndOffer({ router: context.deliveryRouter, record: () =>
+      context.service.sendMessage({ sessionId: options.session,
+      generation: options.generation, clientMessageId: clientMessageId(options, context),
+      toParticipantIds, kind,
+      obligation: obligationFor(kind, options.obligation, toParticipantIds.length > 0),
+      subject: options.subject, body: options.body, descriptor: context.descriptor }) });
+    const message = routed.recorded;
+    return { data: { message, delivery: routed.delivery },
+      text: recordedText(message, routed.delivery) };
   },
 
-  /**
-   * 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}` };
+  inbox: async ({ options, context }) => {
+    const messages = await context.service.readInbox({ sessionId: options.session,
+      generation: options.generation, messageId: options.message });
+    return { data: messages, text: messages.length === 0
+      ? "inbox empty" : JSON.stringify(messages, null, 2) };
   },
 
-  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}` };
+  reply: async ({ options, context }) => {
+    const routed = await recordAndOffer({ router: context.deliveryRouter,
+      selectMessage: value => value.reply, record: () => context.service.replyToMessage({
+      sessionId: options.session,
+      generation: options.generation, messageId: options.message, body: options.body,
+      subject: options.subject, clientMessageId: clientMessageId(options, context) }) });
+    const result = routed.recorded;
+    return { data: { message: result.reply, delivery: routed.delivery },
+      text: recordedText(result.reply, routed.delivery) };
   },
 
-  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}` };
+  request: async ({ options, context }) => {
+    const routed = await recordAndOffer({ router: context.deliveryRouter, record: () =>
+      context.service.sendMessage({
+      sessionId: options.session,
+      generation: options.generation,
+      clientMessageId: clientMessageId(options, context),
+      toParticipantIds: [options.to],
+      kind: "request",
+      obligation: "reply",
+      subject: options.title,
+      body: options.detail ?? options.title,
+      descriptor: context.descriptor,
+    }) });
+    const message = routed.recorded;
+    return { data: { message, delivery: routed.delivery },
+      text: recordedText(message, routed.delivery) };
   },
 
-  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}` };
+  ack: async ({ options, context }) => {
+    const receipt = await context.service.acknowledgeMessage({ sessionId: options.session,
+      generation: options.generation, messageId: options.message });
+    return { data: receipt, text: `${receipt.messageId} ${receipt.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}` };
+    const routed = await recordAndOffer({ router: context.deliveryRouter,
+      selectMessage: value => value.message, record: () => context.service.finishSession({
+      sessionId: options.session,
+      generation: options.generation, clientMessageId: clientMessageId(options, context),
+      goal: options.goal, status: options.status,
+      toParticipantId: options.to, completed: options.completed ?? [],
+      remaining: options.remaining ?? [], blockers: options.blocker ?? [] }) });
+    const handoff = routed.recorded;
+    return { data: { message: handoff.message, delivery: routed.delivery },
+      text: recordedText(handoff.message, routed.delivery) };
   },
 
   status: async ({ options, context }) => {

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

@@ -20,7 +20,7 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
  * answers that from something the caller demonstrably has.
  */
 const NEEDS_OWNER = Object.freeze(new Set(["work", "claim", "release", "message",
-  "request", "ack", "workstream", "task", "finish", "decide"]));
+  "inbox", "reply", "request", "ack", "workstream", "task", "finish", "decide"]));
 
 /**
  * Reads that are answers about *you*.

package/node_modules/@agents-can-communicate/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -0,0 +1,106 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { overlaps } from "./claims.mjs";
+import { classifySessionPresence } from "./sessions.mjs";
+
+export const ATTENTION_PRIORITY = Object.freeze({
+  reply_required: 1,
+  acknowledgement_required: 2,
+  recipient_unavailable: 3,
+  claim_conflict: 4,
+  claim_contended: 5,
+  claim_expired: 6,
+});
+
+function obligationItems(snapshot, participantId) {
+  const messages = new Map((snapshot.messages ?? []).map(item => [item.messageId, item]));
+  return (snapshot.receipts ?? []).flatMap(receipt => {
+    if (receipt.recipientParticipantId !== participantId
+      || receipt.state === "acknowledged") return [];
+    const message = messages.get(receipt.messageId);
+    const kind = message?.obligation === "reply" ? "reply_required"
+      : message?.obligation === "acknowledge" ? "acknowledgement_required" : null;
+    const action = kind === "reply_required" ? "a reply" : "acknowledgement";
+    return kind === null ? [] : [{ kind, priority: ATTENTION_PRIORITY[kind],
+      sourceId: message.messageId,
+      summary: `message ${message.messageId} from ${message.fromParticipantId} is a `
+        + `${message.kind} requiring ${action}` }];
+  });
+}
+
+function presenceByParticipant(snapshot, now, pidIsAlive) {
+  const online = new Set();
+  for (const session of snapshot.sessions ?? []) {
+    if (classifySessionPresence(session, now, pidIsAlive) === "online") {
+      online.add(session.participantId);
+    }
+  }
+  return online;
+}
+
+function unavailableRecipients(snapshot, participantId, now, pidIsAlive) {
+  const online = presenceByParticipant(snapshot, now, pidIsAlive);
+  const receipts = snapshot.receipts ?? [];
+  return (snapshot.messages ?? []).flatMap(message => {
+    if (message.fromParticipantId !== participantId || message.toParticipantIds?.length === 0
+      || message.obligation === "none") return [];
+    return receipts.filter(receipt => receipt.messageId === message.messageId
+      && receipt.state !== "acknowledged"
+      && !online.has(receipt.recipientParticipantId))
+      .map(receipt => ({ kind: "recipient_unavailable",
+        priority: ATTENTION_PRIORITY.recipient_unavailable,
+        sourceId: message.messageId,
+        summary: `${message.subject} - ${receipt.recipientParticipantId} is unavailable` }));
+  });
+}
+
+function expiredClaims(snapshot, session, now) {
+  if (session == null) return [];
+  return (snapshot.claims ?? []).filter(claim => claim.ownerSessionId === session.sessionId
+    && Date.parse(claim.expiresAt) <= Date.parse(now))
+    .map(claim => ({ kind: "claim_expired", priority: ATTENTION_PRIORITY.claim_expired,
+      sourceId: claim.claimId,
+      summary: `${claim.resource} - your claim has run out, and peers can write to it` }));
+}
+
+function claimConflicts(snapshot, session, now) {
+  const mine = (snapshot.intents ?? []).find(intent => intent.sessionId === session?.sessionId);
+  if (mine === undefined) return [];
+  return (snapshot.claims ?? []).filter(claim => claim.ownerSessionId !== session.sessionId
+    && Date.parse(claim.expiresAt) > Date.parse(now)
+    && mine.resourceHints.some(hint => overlaps(hint, claim.resource)))
+    .map(claim => ({ kind: "claim_conflict", priority: ATTENTION_PRIORITY.claim_conflict,
+      sourceId: claim.claimId,
+      summary: `${claim.resource} is claimed by ${claim.ownerSessionId}` }));
+}
+
+function claimContended(snapshot, session, now) {
+  if (session == null) return [];
+  const peerIntents = (snapshot.intents ?? [])
+    .filter(intent => intent.sessionId !== session.sessionId);
+  return (snapshot.claims ?? []).filter(claim => claim.ownerSessionId === session.sessionId
+    && Date.parse(claim.expiresAt) > Date.parse(now)).flatMap(claim => {
+    const peer = peerIntents.find(intent => intent.resourceHints
+      .some(hint => overlaps(hint, claim.resource)));
+    if (peer === undefined) return [];
+    const participant = (snapshot.sessions ?? [])
+      .find(item => item.sessionId === peer.sessionId)?.participantId ?? "a peer";
+    return [{ kind: "claim_contended", priority: ATTENTION_PRIORITY.claim_contended,
+      sourceId: claim.claimId,
+      summary: `${claim.resource} - ${participant} means to work on what you hold` }];
+  });
+}
+
+export function computeAttention(snapshot, { session, participantId, now, pidIsAlive }) {
+  if (typeof pidIsAlive !== "function") {
+    throw new AccError(EXIT.USAGE, "computeAttention requires a pidIsAlive probe", {});
+  }
+  return [
+    ...obligationItems(snapshot, participantId),
+    ...unavailableRecipients(snapshot, participantId, now, pidIsAlive),
+    ...claimConflicts(snapshot, session, now),
+    ...claimContended(snapshot, session, now),
+    ...expiredClaims(snapshot, session, now),
+  ].sort((left, right) => left.priority - right.priority
+    || left.sourceId.localeCompare(right.sourceId));
+}