agents-can-communicate 0.1.18 → 0.3.0

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

@@ -14,7 +14,7 @@ import { COMMANDS } from "./args.mjs";
 const GROUPS = Object.freeze([
   ["Set up", ["install", "uninstall", "doctor", "config"]],
   ["In a session", ["status", "sync", "work", "claim", "release", "inbox", "reply",
-    "ack", "message", "request", "task", "workstream", "decide", "finish"]],
+    "ack", "message", "request", "finish"]],
   ["Driven by adapters, not by people", ["attach", "heartbeat", "detach"]],
   ["About acc", ["help", "version", "update"]],
 ]);
@@ -33,10 +33,7 @@ const SUMMARY = Object.freeze({
   message: "send a typed message to named participants",
   inbox: "read only unresolved messages addressed to this participant",
   reply: "reply to one message and acknowledge it in the same operation",
-  request: "ask another agent to do something: the work and the why, in one call",
-  task: "create work, --take it, or move its --state along",
-  workstream: "group related work, and steer it with --take / --release",
-  decide: "record what was settled, so the next session does not reopen it",
+  request: "ask another agent to do something in a reply-required message",
   finish: "write the handoff and release what this session held",
   attach: "open a session; an adapter calls this, not a person",
   heartbeat: "say the session is still alive",

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

@@ -6,7 +6,8 @@ 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 }
+import { LIVE_POLICIES, applyPlan, describeActivation, detectInstallation, livePolicyOf,
+  loadOwnership, planInstallation, rcFileFor, shellOf, shimDirFor }
   from "@agents-can-communicate/installer";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
@@ -18,13 +19,18 @@ import { platformPaths } from "./platform-paths.mjs";
 // Each client keeps its own directory under the user's home, and an adapter
 // pointed at the home itself writes beside them rather than inside them. That
 // install reports success and the client never reads a byte of it.
-export const clientContext = (home, stateRoot) => ({
+export const clientContext = (home, stateRoot, { shell = null, env = {} } = {}) => ({
   home,
   configDir: path.join(home, ".claude"),
   agentsHome: home,
   codexHome: path.join(home, ".codex"),
   kimiHome: path.join(home, ".kimi-code"),
   grokHome: path.join(home, ".grok"),
+  // The user's login shell and PATH, for the optional native shell bootstrap:
+  // which rc file could carry an ACC PATH block and which real executable a
+  // shim would exec. Detection reads them; nothing here writes.
+  shell,
+  env,
   // 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
@@ -108,9 +114,20 @@ export function describeChanges(operation, home) {
     return [...artifacts.filter(artifact => artifact.kind !== "merge")
       .map(artifact => `  created ${shorten(artifact.path, home)}`), ...edited];
   }
+  // An uninstall's merge edits come from the plan - every file ACC has ever
+  // written into - while everything else on this list is decided by the run.
+  // Printed unconditionally, a second uninstall told the operator it had edited
+  // six of their configuration files whose bytes it had not touched. `changes`
+  // is what the adapter actually took out, and is already what the packed
+  // verifier calls a no-op, so the report now follows the same definition. It
+  // is still the plan's list rather than a per-file one: this says whether
+  // anything was edited, not which of several files it was.
+  const editedIfAnything = (operation.changes ?? []).length === 0 ? [] : edited;
   return [
     ...(operation.removed ?? []).map(file => `  removed ${shorten(file, home)}`),
-    ...edited,
+    ...(operation.removedDirectories ?? [])
+      .map(file => `  removed ${shorten(file, home)}`),
+    ...editedIfAnything,
     ...(operation.kept ?? [])
       .map(file => `  kept    ${shorten(file, home)} - changed since ACC wrote it`),
   ];
@@ -122,6 +139,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
@@ -165,7 +185,76 @@ 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;
+}
+
+const isInteractive = runtime => typeof runtime.isInteractive === "function"
+  && runtime.isInteractive() === true;
+
+// One default-No question per eligible client, asked only after detection has
+// finished and only when a person is at both ends of the terminal. It names
+// the client, the mechanism, and the files or service it would touch, and says
+// when the choice takes effect.
+function questionFor(entry, context) {
+  const activation = { livePolicy: "actionable", shell: context.shell,
+    rcFile: rcFileFor(context.home, context.shell), shimDir: shimDirFor(context.stateRoot),
+    mechanisms: entry.nativeDelivery.activationPlan.mechanisms };
+  return [`Enable native live delivery for ${entry.displayName} ${entry.version}?`,
+    ...describeActivation(activation).map(line => `  ${line}`),
+    "  applies to newly started sessions; a new PATH block needs a new or reloaded shell"]
+    .join("\n");
+}
+
+/**
+ * Which live policy each selected client gets.
+ *
+ * An explicit --delivery applies uniformly and never prompts. Otherwise a
+ * recorded opt-in is kept as it was consented to, a fresh or never-activated
+ * client is off unless a person answers yes here, and a dry run or a
+ * non-interactive stdin/stdout makes no interactive choice at all.
+ */
+export async function decideDelivery({ options, detected, recorded, runtime, dryRun, context }) {
+  const explicit = options.delivery;
+  if (explicit !== undefined && !LIVE_POLICIES.includes(explicit)) {
+    throw new AccError(EXIT.USAGE, `unknown delivery policy: ${explicit}`, { delivery: explicit });
+  }
+  const recordedById = new Map(recorded.map(install => [install.adapterId, install]));
+  const deliveryByAdapter = {};
+  const asked = [];
+  let withheld = 0;
+  for (const entry of detected) {
+    const eligible = entry.nativeDelivery?.state === "eligible";
+    const previous = livePolicyOf(recordedById.get(entry.adapterId));
+    if (explicit !== undefined) {
+      deliveryByAdapter[entry.adapterId] = explicit;
+    } else if (previous !== "off") {
+      deliveryByAdapter[entry.adapterId] = previous;
+    } else if (!eligible || dryRun || !isInteractive(runtime)) {
+      deliveryByAdapter[entry.adapterId] = "off";
+      if (eligible) withheld += 1;
+    } else {
+      const yes = await runtime.confirm(questionFor(entry, context),
+        { input: runtime.input, output: runtime.output }) === true;
+      deliveryByAdapter[entry.adapterId] = yes ? "actionable" : "off";
+      asked.push(entry.adapterId);
+    }
+  }
+  const notes = explicit === undefined && dryRun && withheld > 0
+    ? ["interactive choices were not made: this preview keeps native delivery off for "
+      + `${withheld} eligible client(s) without a recorded opt-in`]
+    : [];
+  return { deliveryByAdapter, asked, notes };
+}
+
+// Said once, after the first PATH block is written: a running shell and a
+// running client know nothing about it.
+function reloadAdvice(operations) {
+  const appended = operations.filter(operation => operation.appendedRcBlock === true);
+  if (appended.length === 0) return [];
+  const rc = appended[0].nativeActivation?.rcFile ?? "your shell rc file";
+  return ["", `native delivery is wired for new sessions: open a new terminal (or reload ${rc}), `
+    + "then start the client normally; a session already running keeps durable delivery"];
 }
 
 export async function runInstallCommand({ options, runtime, action = "install" }) {
@@ -173,7 +262,8 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   const home = options.home ?? runtime.env?.HOME ?? homedir();
   const { data: dataHome } = platformPaths({ platform: runtime.platform,
     env: runtime.env ?? {} });
-  const context = clientContext(home, path.join(dataHome, "acc"));
+  const context = clientContext(home, path.join(dataHome, "acc"),
+    { shell: shellOf(runtime.env), env: runtime.env ?? {} });
 
   const detected = await detectInstallation({ adapters, context,
     probeTimeoutMs: probeTimeout(runtime.env) });
@@ -199,19 +289,28 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   const requested = options.adapter === undefined
     ? []
     : (Array.isArray(options.adapter) ? options.adapter : [options.adapter]);
+  // Decided only after detection, from the operator's explicit answer, the
+  // recorded consent, or a default of off; never from inference.
+  const decided = action === "install"
+    ? await decideDelivery({ options, detected, recorded, runtime, dryRun, context })
+    : { deliveryByAdapter: {}, asked: [], notes: [] };
   const plan = planInstallation({ adapters, detected, context, action, recorded,
-    accVersion, allowDowngrade: options.downgrade === true, requested });
+    accVersion, allowDowngrade: options.downgrade === true, requested,
+    deliveryByAdapter: decided.deliveryByAdapter });
   const result = await applyPlan({ plan, adapters, context, dataHome, dryRun, accVersion });
 
   const acted = actedOn(result);
   if (dryRun) {
-    return { data: { ...result, plan, dataHome },
+    return { data: { ...result, plan, dataHome, deliveryByAdapter: decided.deliveryByAdapter },
       text: [`would ${action}:`, ...plan.operations.flatMap(operation => operation.summary),
-        ...plan.skipped.map(entry => `skip ${entry.adapterId}: ${entry.reason}`)].join("\n") };
+        ...plan.skipped.map(entry => `skip ${entry.adapterId}: ${entry.reason}`),
+        ...decided.notes].join("\n") };
   }
 
-  return { data: { ...result, plan, dataHome },
-    text: describeOutcome({ action, acted, failed: result.failed,
-      skipped: plan.skipped, operations: result.operations, home }),
-    error: failureOf({ action, acted, failed: result.failed }) };
+  return { data: { ...result, plan, dataHome, deliveryByAdapter: decided.deliveryByAdapter,
+    asked: decided.asked },
+  text: [describeOutcome({ action, acted, failed: result.failed,
+    skipped: plan.skipped, operations: result.operations, home }),
+  ...reloadAdvice(result.operations)].join("\n"),
+  error: failureOf({ action, acted, failed: result.failed }) };
 }

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

@@ -1,6 +1,11 @@
-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, noteNudge } from "@agents-can-communicate/core";
+import { createCoordinationService } from "@agents-can-communicate/core";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
 
 import { parseArgs, positiveNumber } from "./args.mjs";
@@ -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,18 +244,17 @@ 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 });
-    // A note that reads like it wants a reply was sent with no ack obligation
-    // and no standing reminder; say so once, without blocking the send. Carried
-    // in `data` so an adapter reading `--json` sees it, and appended to `text`
-    // for a person - the send already succeeded either way.
-    const advice = noteNudge(message);
-    return { data: advice ? { ...message, advice } : message,
-      text: advice ? `sent ${message.messageId}\n${advice}` : `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) };
   },
 
   inbox: async ({ options, context }) => {
@@ -216,121 +265,51 @@ const HANDLERS = Object.freeze({
   },
 
   reply: async ({ options, context }) => {
-    const result = await context.service.replyToMessage({ sessionId: options.session,
+    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, type: options.type, priority: options.priority });
-    return { data: result,
-      text: `replied ${result.reply.messageId}; acknowledged ${options.message}` };
+      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) };
   },
 
-  /**
-   * 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}` };
+    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) };
   },
 
   ack: async ({ options, context }) => {
-    const receipt = await context.service.markDelivery({ sessionId: options.session,
-      generation: options.generation, messageId: options.message,
-      state: options.state ?? "acknowledged" });
+    const receipt = await context.service.acknowledgeMessage({ sessionId: options.session,
+      generation: options.generation, messageId: options.message });
     return { data: receipt, text: `${receipt.messageId} ${receipt.state}` };
   },
 
-  /**
-   * What was settled, and on whose authority.
-   *
-   * `--human` is the caller stating that a person actually decided this. The
-   * core refuses `--authority human` without it, because a peer proposal
-   * becoming a human decision on its own is the one way this record could
-   * launder an agent's opinion into a ruling.
-   */
-  decide: async ({ options, context }) => {
-    const decision = await context.service.recordDecision({
-      sessionId: options.session, generation: options.generation,
-      title: options.title, outcome: options.outcome,
-      authority: options.authority ?? "workstream",
-      workstreamId: options.workstream ?? null,
-      decidedBy: options.decidedBy,
-      supersedes: options.supersedes ?? null,
-      humanConfirmed: options.human === true,
-      descriptor: context.descriptor });
-    return { data: decision,
-      text: `${decision.decisionId} ${decision.authority}: ${decision.title}` };
-  },
-
-  workstream: async ({ options, context }) => {
-    const owner = { sessionId: options.session, generation: options.generation };
-    // Taking the coordination of one and creating one are the same noun, so
-    // they stay one command rather than two the model has to choose between -
-    // the same shape `acc task` already has.
-    if (options.take === true || options.release === true) {
-      if (options.workstream === undefined) {
-        throw usage(`workstream --${options.take === true ? "take" : "release"} `
-          + "requires --workstream");
-      }
-      const acted = options.take === true
-        ? await context.service.acquireCoordinator({ ...owner,
-          workstreamId: options.workstream })
-        : await context.service.releaseCoordinator({ ...owner,
-          workstreamId: options.workstream });
-      return { data: acted,
-        text: `${acted.workstreamId} ${options.take === true ? "coordinated" : "released"}` };
-    }
-    if (options.title === undefined) throw usage("workstream requires --title");
-    if (options.objective === undefined) throw usage("workstream requires --objective");
-    const workstream = await context.service.createWorkstream({ ...owner,
-      title: options.title, objective: options.objective,
-      descriptor: context.descriptor });
-    return { data: workstream, text: `${workstream.workstreamId} ${workstream.state}` };
-  },
-
-  task: async ({ options, context }) => {
-    const owner = { sessionId: options.session, generation: options.generation };
-    // Taking work and moving it along are the same noun as creating it, so they
-    // stay one command rather than three the model has to choose between.
-    if (options.take === true) {
-      if (options.task === undefined) throw usage("task --take requires --task");
-      const taken = await context.service.claimTask({ ...owner, taskId: options.task,
-        force: options.force === true });
-      return { data: taken, text: `${taken.taskId} ${taken.state}` };
-    }
-    if (options.decline === true) {
-      if (options.task === undefined) throw usage("task --decline requires --task");
-      const refused = await context.service.declineTask({ ...owner,
-        taskId: options.task, reason: options.reason });
-      return { data: refused, text: `${refused.taskId} declined` };
-    }
-    if (options.state !== undefined) {
-      if (options.task === undefined) throw usage("task --state requires --task");
-      const moved = await context.service.transitionTask({ ...owner,
-        taskId: options.task, state: options.state });
-      return { data: moved, text: `${moved.taskId} ${moved.state}` };
-    }
-    if (options.title === undefined) throw usage("task requires --title");
-    const task = await context.service.createTask({ ...owner,
-      workstreamId: options.workstream, title: options.title, detail: options.detail,
-      assigneeParticipantId: options.assignee, taskId: options.task,
-      dependsOn: options.dependsOn ?? [], descriptor: context.descriptor });
-    return { data: task, text: `${task.taskId} ${task.state}` };
-  },
-
   finish: async ({ options, context }) => {
-    const handoff = await context.service.finishSession({ sessionId: options.session,
-      generation: options.generation, goal: options.goal, status: options.status,
-      toParticipantId: options.to ?? null, completed: options.completed ?? [],
-      remaining: options.remaining ?? [], blockers: options.blocker ?? [] });
-    return { data: handoff, text: `handoff ${handoff.handoffId}` };
+    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/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.1.18",
+  "version": "0.3.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));
+}