agents-can-communicate 0.1.0

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

@@ -0,0 +1,334 @@
+import { AccError, EXIT, SCHEMA_VERSION, advanceDelivery, createId, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { ensureMaterialised } from "./materialisation.mjs";
+import { assertKnownParticipants } from "./participants.mjs";
+import { writeTask } from "./tasks.mjs";
+
+const receiptId = (messageId, recipient) => `${messageId}--${recipient}`;
+
+// Peer content is data, never authority. Messages carry attribution and a
+// typed intent; nothing in a body can change policy or promote a proposal.
+export function createCommunicationService(ports, sessions, claims) {
+  const { store, clock, ids } = ports;
+
+  async function requireOpenSession(input, action) {
+    const existing = await sessions.locateSession(input.sessionId, input.workspaceId);
+    if (existing === null || existing.record.state !== "open"
+      || existing.record.generation !== input.generation) {
+      throw new AccError(EXIT.CONFLICT, `cannot ${action} from this session generation`,
+        { sessionId: input.sessionId });
+    }
+    return existing.record;
+  }
+
+  async function sendMessage(input) {
+    const session = await requireOpenSession(input, "send a message");
+    const workspaceId = session.workspaceId;
+    await ensureMaterialised(ports, { workspaceId, descriptor: input.descriptor,
+      reason: "durable_object" });
+    const now = clock.now();
+    const messageId = createId("message");
+    const recipients = input.toParticipantIds ?? [];
+    if (recipients.length === 0) {
+      throw new AccError(EXIT.USAGE, "a message needs at least one recipient", { messageId });
+    }
+    const record = validateRecord("message", {
+      schemaVersion: SCHEMA_VERSION,
+      messageId,
+      workspaceId,
+      fromSessionId: session.sessionId,
+      fromParticipantId: session.participantId,
+      toParticipantIds: recipients,
+      type: input.type,
+      subject: input.subject,
+      body: input.body,
+      priority: input.priority ?? "normal",
+      workstreamId: input.workstreamId ?? null,
+      taskId: input.taskId ?? null,
+      inReplyTo: input.inReplyTo ?? null,
+      requiresAck: input.requiresAck === true,
+      artifacts: input.artifacts ?? [],
+      sentAt: now,
+    });
+    // After the record is validated, so a body carrying control characters is
+    // refused for what it is rather than for who it was addressed to.
+    await assertKnownParticipants(store, workspaceId, recipients);
+
+    await store.transaction(async tx => {
+      tx.put("message", messageId, record);
+      // One receipt per recipient: a receipt from one recipient can never move
+      // another recipient's state.
+      for (const recipient of recipients) {
+        tx.put("receipt", receiptId(messageId, recipient), validateRecord("receipt", {
+          schemaVersion: SCHEMA_VERSION,
+          messageId,
+          workspaceId,
+          recipientParticipantId: recipient,
+          state: "queued",
+          updatedAt: now,
+        }));
+      }
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: session.sessionId, type: "message.sent", occurredAt: now,
+        payload: { messageId, type: record.type, recipients } });
+    }, { kinds: ["message", "receipt"] });
+    return record;
+  }
+
+  async function markDelivery(input) {
+    const session = await requireOpenSession(input, "update delivery");
+    // Your own receipt, unless you say otherwise and mean it. A session
+    // advancing another participant's receipt would be reporting that someone
+    // else had read something.
+    const recipient = input.recipientParticipantId ?? session.participantId;
+    if (recipient !== session.participantId) {
+      throw new AccError(EXIT.CONFLICT, "a session can only mark its own receipt",
+        { recipient, participantId: session.participantId });
+    }
+    const now = clock.now();
+    let record = null;
+    await store.transaction(async tx => {
+      const id = receiptId(input.messageId, recipient);
+      const existing = tx.get("receipt", id);
+      if (existing === null) {
+        throw new AccError(EXIT.DATA, "no receipt exists for that recipient", { id });
+      }
+      // Monotonic by construction: the protocol state machine refuses to move
+      // backwards, so an acknowledgement can never be downgraded to seen.
+      record = { ...existing, state: advanceDelivery(existing.state, input.state),
+        updatedAt: now };
+      tx.put("receipt", id, record, tx.generationOf("receipt", id));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: existing.workspaceId, actorSessionId: session.sessionId,
+        type: `message.${record.state}`, occurredAt: now,
+        payload: { messageId: input.messageId,
+          recipientParticipantId: recipient } });
+    }, { kinds: ["receipt"] });
+    return record;
+  }
+
+  async function recordDecision(input) {
+    const session = await requireOpenSession(input, "record a decision");
+    const workspaceId = session.workspaceId;
+    await ensureMaterialised(ports, { workspaceId, reason: "durable_object" });
+    // A peer proposal never becomes a human-authority decision on its own.
+    if (input.authority === "human" && input.humanConfirmed !== true) {
+      throw new AccError(EXIT.CONFLICT,
+        "human authority requires an explicit human confirmation", { authority: "human" });
+    }
+    const now = clock.now();
+    const decisionId = createId("decision");
+    const record = validateRecord("decision", {
+      schemaVersion: SCHEMA_VERSION,
+      decisionId,
+      workspaceId,
+      workstreamId: input.workstreamId ?? null,
+      title: input.title,
+      outcome: input.outcome,
+      authority: input.authority,
+      decidedBy: input.decidedBy ?? [session.participantId],
+      evidence: input.evidence ?? [],
+      supersedes: input.supersedes ?? null,
+      decidedAt: now,
+    });
+    await store.transaction(async tx => {
+      if (record.supersedes !== null && tx.get("decision", record.supersedes) === null) {
+        throw new AccError(EXIT.DATA, "the superseded decision does not exist",
+          { supersedes: record.supersedes });
+      }
+      tx.put("decision", decisionId, record);
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: session.sessionId, type: "decision.recorded", occurredAt: now,
+        payload: { decisionId, authority: record.authority } });
+    }, { kinds: ["decision"] });
+    return record;
+  }
+
+  /**
+   * Produce a handoff and release what this session owned. The semantic summary
+   * is written while the model is still active; session end only closes
+   * lifecycle ownership.
+   */
+  /**
+   * What the successor needs, in the order they need it: what this was for, how
+   * far it got, what is left, and what is in the way.
+   */
+  function describeHandoff(record) {
+    const section = (label, items) => (items.length === 0
+      ? [] : [`${label}:`, ...items.map(item => `- ${item}`)]);
+    return [
+      // The goal is the subject; repeating it here costs a line of everyone's
+      // turn to say the same thing twice.
+      record.status,
+      ...section("done", record.completed),
+      // Not "left": the status line above already uses that word for how far
+      // this got, and the two meanings sat one line apart.
+      ...section("still to do", record.remaining),
+      ...section("in the way", record.blockers),
+      ...section("released", record.claimsToRelease),
+    ].join("\n");
+  }
+
+  async function finishSession(input) {
+    const session = await requireOpenSession(input, "finish");
+    const workspaceId = session.workspaceId;
+    await ensureMaterialised(ports, { workspaceId, reason: "durable_object" });
+    const now = clock.now();
+    const handoffId = createId("handoff");
+    const owned = (await store.snapshot(workspaceId, { kinds: ["claim"] })).claims
+      .filter(claim => claim.ownerSessionId === session.sessionId);
+    const successor = input.toParticipantId ?? null;
+    // The same rule as addressing anything else: handing your work to a name
+    // nobody has is a typo, and the summary is the last thing this session will
+    // ever say.
+    if (successor !== null) await assertKnownParticipants(store, workspaceId, [successor]);
+    const record = validateRecord("handoff", {
+      schemaVersion: SCHEMA_VERSION,
+      handoffId,
+      workspaceId,
+      fromSessionId: session.sessionId,
+      toParticipantId: successor,
+      goal: input.goal,
+      status: input.status ?? "partial",
+      completed: input.completed ?? [],
+      remaining: input.remaining ?? [],
+      blockers: input.blockers ?? [],
+      claimsToRelease: owned.map(claim => claim.resource),
+      verification: input.verification ?? [],
+      artifacts: input.artifacts ?? [],
+      createdAt: now,
+    });
+
+    await store.transaction(async tx => {
+      tx.put("handoff", handoffId, record);
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: session.sessionId, type: "handoff.created", occurredAt: now,
+        payload: { handoffId, released: record.claimsToRelease } });
+    }, { kinds: ["handoff"] });
+
+    // A handoff nobody is told about is a note to the store. Written, durable,
+    // and reaching the agent it names through nothing at all: not their turn,
+    // not their attention, not `acc status` - only a full snapshot they would
+    // have to scan for their own name. The message type for this has been in the
+    // schema all along, and this is the half that was never built.
+    if (successor !== null) {
+      await sendMessage({
+        sessionId: session.sessionId, generation: input.generation,
+        toParticipantIds: [successor], type: "handoff",
+        subject: `handing over: ${record.goal}`,
+        body: describeHandoff(record),
+        descriptor: input.descriptor,
+      });
+    }
+
+    for (const claim of owned) {
+      await claims.releaseClaim({ claimId: claim.claimId, sessionId: session.sessionId,
+        generation: session.generation, workspaceId });
+    }
+    return record;
+  }
+
+  /**
+   * Messages addressed to this participant that nothing has shown a model yet.
+   *
+   * `queued` is where `sendMessage` leaves a receipt. Anything further along has
+   * already been put in front of the recipient, and delivery states only move
+   * forward - so re-injecting would misreport what happened rather than repeat
+   * harmlessly.
+   *
+   * A session never receives its own message back. Another session of the same
+   * participant does, because it is a different reader.
+   */
+  async function pendingMessages(input = {}) {
+    const participantId = input.participantId;
+    if (typeof participantId !== "string" || participantId === "") return [];
+    const workspaceId = input.workspaceId ?? store.workspaceId;
+    // Messages and receipts are the two unbounded kinds and this read needs
+    // both. Nothing else, though, and it runs in front of every turn.
+    const snapshot = await store.snapshot(workspaceId,
+      { kinds: ["message", "receipt"] });
+    const waiting = new Set((snapshot.receipts ?? [])
+      .filter(receipt => receipt.recipientParticipantId === participantId
+        && (receipt.state === "queued" || receipt.state === "recorded"))
+      .map(receipt => receipt.messageId));
+    return (snapshot.messages ?? [])
+      .filter(message => waiting.has(message.messageId)
+        && message.fromSessionId !== input.exceptSessionId)
+      // Oldest first, and the id breaks ties so two messages sent in the same
+      // millisecond still project in a stable order.
+      .sort((left, right) => left.sentAt.localeCompare(right.sentAt)
+        || left.messageId.localeCompare(right.messageId));
+  }
+
+  /**
+   * Ask another agent to do something.
+   *
+   * One write, because the two halves are useless apart. A task addressed to
+   * someone who was never told about it is work nobody knows exists, and a
+   * message describing work that was never recorded is a request with nothing
+   * to point at.
+   *
+   * The recipient learns about it twice over, and both paths already existed:
+   * the task raises a `task_unblocked` attention item for the participant it
+   * names, and the message reaches their turn as quoted peer text.
+   */
+  async function requestWork(input) {
+    const session = await requireOpenSession(input, "request work");
+    const workspaceId = session.workspaceId;
+    const recipient = input.toParticipantId;
+    if (typeof recipient !== "string" || recipient === "") {
+      throw new AccError(EXIT.USAGE, "a request needs a recipient participant");
+    }
+    await ensureMaterialised(ports, { workspaceId, descriptor: input.descriptor,
+      reason: "durable_object" });
+    await assertKnownParticipants(store, workspaceId, [recipient]);
+    const now = clock.now();
+    const messageId = createId("message");
+    let task = null;
+    let message = null;
+
+    await store.transaction(async tx => {
+      task = writeTask(tx, { session, workspaceId, now, ids,
+        input: { ...input, assigneeParticipantId: recipient,
+          requestedByParticipantId: session.participantId } });
+      message = validateRecord("message", {
+        schemaVersion: SCHEMA_VERSION,
+        messageId,
+        workspaceId,
+        fromSessionId: session.sessionId,
+        fromParticipantId: session.participantId,
+        toParticipantIds: [recipient],
+        type: "work_request",
+        subject: input.title,
+        body: input.detail ?? input.title,
+        priority: input.priority ?? "normal",
+        workstreamId: task.workstreamId,
+        taskId: task.taskId,
+        inReplyTo: input.inReplyTo ?? null,
+        // A request is a question, so the sender is entitled to know whether it
+        // was taken up. Silence and refusal are different answers.
+        requiresAck: true,
+        artifacts: input.artifacts ?? [],
+        sentAt: now,
+      });
+      tx.put("message", messageId, message);
+      tx.put("receipt", receiptId(messageId, recipient), validateRecord("receipt", {
+        schemaVersion: SCHEMA_VERSION,
+        messageId,
+        workspaceId,
+        recipientParticipantId: recipient,
+        state: "queued",
+        updatedAt: now,
+      }));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: session.sessionId, type: "work.requested", occurredAt: now,
+        payload: { taskId: task.taskId, messageId, recipient } });
+    // `writeTask` runs on this handle, so what it reads is read here.
+    }, { kinds: ["message", "receipt", "session", "task", "workstream"] });
+    return { task, message };
+  }
+
+  return { sendMessage, markDelivery, pendingMessages, requestWork, recordDecision,
+    finishSession };
+}

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

@@ -0,0 +1,7 @@
+// Domain services over injected ports. No vendor, Git, or project knowledge.
+export { createCoordinationService } from "./service.mjs";
+export { assertPorts } from "./ports.mjs";
+export { classifySessionPresence } from "./sessions.mjs";
+export { ATTENTION_PRIORITY, computeAttention } from "./sync.mjs";
+export { overlaps } from "./claims.mjs";
+export { wouldCycle } from "./tasks.mjs";

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

@@ -0,0 +1,75 @@
+import { AccError, EXIT, SCHEMA_VERSION, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { isMaterialised } from "./materialisation.mjs";
+
+// Intent answers "what is this session doing now?". It is awareness, not
+// authorisation: an edit intent never substitutes for a claim, which is why
+// resourceHints are advisory strings rather than reservations.
+export function createIntentService(ports, sessions) {
+  const { store, clock, ids } = ports;
+
+  async function requireOwner(sessionId, workspaceId, generation) {
+    const existing = await sessions.locateSession(sessionId, workspaceId);
+    if (existing === null) {
+      throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
+    }
+    if (existing.record.generation !== generation) {
+      throw new AccError(EXIT.CONFLICT, "intent belongs to a replaced session generation",
+        { sessionId, expected: generation, actual: existing.record.generation });
+    }
+    if (existing.record.state !== "open") {
+      throw new AccError(EXIT.CONFLICT, "a closed session cannot publish intent", { sessionId });
+    }
+    return existing;
+  }
+
+  async function setIntent(input) {
+    const owner = await requireOwner(input.sessionId, input.workspaceId, input.generation);
+    const workspaceId = owner.record.workspaceId;
+    const now = clock.now();
+    const intent = validateRecord("intent", {
+      schemaVersion: SCHEMA_VERSION,
+      sessionId: input.sessionId,
+      workspaceId,
+      summary: input.summary,
+      mode: input.mode,
+      resourceHints: input.resourceHints ?? [],
+      workstreamId: input.workstreamId ?? null,
+      state: input.state ?? "active",
+      updatedAt: now,
+    });
+
+    if (!await isMaterialised(store, workspaceId)) {
+      await store.ephemeral.put("intent", input.sessionId, intent);
+      return intent;
+    }
+    await store.transaction(async tx => {
+      tx.put("intent", input.sessionId, intent, tx.generationOf("intent", input.sessionId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: input.sessionId, type: "intent.published", occurredAt: now,
+        payload: { mode: intent.mode, state: intent.state } });
+    }, { kinds: ["intent"] });
+    return intent;
+  }
+
+  async function clearIntent(input) {
+    const owner = await requireOwner(input.sessionId, input.workspaceId, input.generation);
+    const workspaceId = owner.record.workspaceId;
+    if (!await isMaterialised(store, workspaceId)) {
+      await store.ephemeral.delete("intent", input.sessionId);
+      return;
+    }
+    const now = clock.now();
+    await store.transaction(async tx => {
+      const current = tx.get("intent", input.sessionId);
+      if (current === null) return;
+      tx.put("intent", input.sessionId, { ...current, state: "done", updatedAt: now },
+        tx.generationOf("intent", input.sessionId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: input.sessionId, type: "intent.cleared", occurredAt: now, payload: {} });
+    }, { kinds: ["intent"] });
+  }
+
+  return { setIntent, clearIntent };
+}

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

@@ -0,0 +1,86 @@
+import { SCHEMA_VERSION } from "@agents-can-communicate/protocol";
+
+// Lazy workspace materialisation. Attachment is
+// universal; durable state is not created merely because a session opened
+// somewhere. A lone session writes ephemeral presence and Intent only. The
+// workspace materialises exactly once - at the second live session or the first
+// durable object - and whatever exists ephemerally at that moment is recorded
+// durably in the same transaction.
+//
+// Ephemeral and durable records share one shape, so materialisation is a copy
+// rather than a translation. A translation step is where the two views drift.
+
+const EPHEMERAL_KINDS = Object.freeze([
+  { kind: "participant", key: "participantId", event: null },
+  { kind: "session", key: "sessionId", event: "session.opened" },
+  { kind: "intent", key: "sessionId", event: "intent.published" },
+]);
+
+export async function isMaterialised(store, workspaceId) {
+  // One record answers this, and it is asked before every durable write.
+  return (await store.snapshot(workspaceId, { kinds: ["workspace"] })).workspace !== null;
+}
+
+export async function materialise({ store, clock, ids }, { workspaceId, descriptor, reason }) {
+  const now = clock.now();
+  const staged = [];
+  for (const entry of EPHEMERAL_KINDS) {
+    staged.push({ ...entry, records: await store.ephemeral.list(entry.kind) });
+  }
+  const actorSessionId = staged.find(entry => entry.kind === "session")?.records.at(-1)?.sessionId
+    ?? "session_bootstrap";
+
+  await store.transaction(async tx => {
+    // Asked again inside the lock. `ensureMaterialised` asks before taking it,
+    // which is a check-then-act across processes: agents starting together in a
+    // workspace neither had opened - the ordinary way two agents start - all saw
+    // "not materialised", and every one but the first was refused with
+    // `workspace ... changed under this transaction` and could not attach.
+    const already = tx.get("workspace", workspaceId) !== null;
+    if (!already) {
+      tx.put("workspace", workspaceId, {
+        schemaVersion: SCHEMA_VERSION,
+        workspaceId,
+        displayName: descriptor?.displayName ?? workspaceId,
+        source: descriptor?.source ?? "directory",
+        roots: descriptor?.roots ?? [],
+        createdAt: now,
+      });
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId, type: "workspace.materialised", occurredAt: now,
+        payload: { reason } });
+    }
+
+    for (const entry of staged) {
+      for (const record of entry.records) {
+        // Whoever got here first may have promoted this record already, and
+        // promoting is a copy: the ephemeral and durable shapes are the same,
+        // so the one already there is the one this would write.
+        if (tx.get(entry.kind, record[entry.key]) !== null) continue;
+        tx.put(entry.kind, record[entry.key], record);
+        if (entry.event === null) continue;
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+          actorSessionId: record.sessionId, type: entry.event, occurredAt: now,
+          payload: { sessionId: record.sessionId } });
+      }
+    }
+  // The promoted kinds are named by the loop above, not written literally in
+  // the body, so they are derived rather than repeated: a new ephemeral kind
+  // added to that list is read here without anyone remembering to say so.
+  }, { kinds: ["workspace", ...EPHEMERAL_KINDS.map(entry => entry.kind)] });
+
+  // The ephemeral copies are retired only after the durable transaction
+  // committed, so a crash in between leaves a recoverable duplicate rather than
+  // a hole.
+  for (const entry of staged) {
+    for (const record of entry.records) {
+      await store.ephemeral.delete(entry.kind, record[entry.key]);
+    }
+  }
+}
+
+export async function ensureMaterialised(ports, { workspaceId, descriptor, reason }) {
+  if (await isMaterialised(ports.store, workspaceId)) return true;
+  await materialise(ports, { workspaceId, descriptor, reason });
+  return true;
+}

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

@@ -0,0 +1,95 @@
+import { SCHEMA_VERSION, advanceDelivery, createId, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+const receiptId = (messageId, recipient) => `${messageId}--${recipient}`;
+
+/**
+ * Tell whoever asked for a task what became of it.
+ *
+ * A request is a question, so it deserves an answer: taken up, declined, or
+ * finished. Before this the task recorded who it was for and not who was
+ * waiting, so nothing could be said back and the asker had to poll and diff
+ * task states to find out.
+ *
+ * It is a message rather than an attention rule on purpose. Messages carry
+ * delivery state, so the answer is put in front of the asker exactly once
+ * instead of repeating in every turn until they act on it.
+ *
+ * Written into the caller's transaction: an accepted task whose acceptance was
+ * never sent is the same silence this exists to remove.
+ */
+export function writeWorkResponse(tx, { task, actor, workspaceId, now, ids, outcome,
+  reason = null }) {
+  const asker = task.requestedByParticipantId;
+  // Nobody asked, or the asker is doing it themselves - there is no one to tell.
+  if (asker === null || asker === undefined || asker === actor.participantId) return null;
+
+  const messageId = createId("message");
+  // The subject already carries the outcome and the title. The body says who
+  // and which task, so the asker can follow it up without going and looking.
+  const head = `${outcome} by ${actor.participantId} (task ${task.taskId})`;
+  const body = reason === null ? head : `${head}\n\n${reason}`;
+  const record = validateRecord("message", {
+    schemaVersion: SCHEMA_VERSION,
+    messageId,
+    workspaceId,
+    fromSessionId: actor.sessionId,
+    fromParticipantId: actor.participantId,
+    toParticipantIds: [asker],
+    type: "work_response",
+    subject: `${outcome}: ${task.title}`,
+    body,
+    priority: "normal",
+    workstreamId: task.workstreamId,
+    taskId: task.taskId,
+    inReplyTo: null,
+    // The asker is being told, not asked. Requiring an acknowledgement here
+    // would leave every finished request sitting in someone's attention list.
+    requiresAck: false,
+    artifacts: [],
+    sentAt: now,
+  });
+  tx.put("message", messageId, record);
+  tx.put("receipt", receiptId(messageId, asker), validateRecord("receipt", {
+    schemaVersion: SCHEMA_VERSION,
+    messageId,
+    workspaceId,
+    recipientParticipantId: asker,
+    state: "queued",
+    updatedAt: now,
+  }));
+  tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+    actorSessionId: actor.sessionId, type: `work.${outcome}`, occurredAt: now,
+    payload: { taskId: task.taskId, messageId, asker } });
+  return record;
+}
+
+/**
+ * Close the request a task came from, once it has been answered.
+ *
+ * `acc request` marks its message as needing an acknowledgement, which raises a
+ * `direct_request` attention item for the recipient. Finishing the work did not
+ * clear it, and nothing else could: the operation existed in the core and was
+ * reachable from no surface. So every completed request left a line repeating in
+ * the doer's turn for good.
+ *
+ * Doing the work is the acknowledgement. An explicit `acc ack` exists for
+ * messages that are not tied to a task.
+ */
+export function closeRequestReceipt(tx, { task, actor, now, ids }) {
+  for (const message of tx.list("message")) {
+    if (message.taskId !== task.taskId || message.type !== "work_request") continue;
+    if (!message.toParticipantIds.includes(actor.participantId)) continue;
+    const id = `${message.messageId}--${actor.participantId}`;
+    const existing = tx.get("receipt", id);
+    if (existing === null || existing.state === "acknowledged") continue;
+    const record = { ...existing, state: advanceDelivery(existing.state, "acknowledged"),
+      updatedAt: now };
+    tx.put("receipt", id, record, tx.generationOf("receipt", id));
+    tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+      workspaceId: existing.workspaceId, actorSessionId: actor.sessionId,
+      type: "message.acknowledged", occurredAt: now,
+      payload: { messageId: message.messageId,
+        recipientParticipantId: actor.participantId } });
+  }
+}

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

@@ -0,0 +1,48 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+/**
+ * Everyone this workspace has ever seen.
+ *
+ * Participants are created when a session attaches and are never removed, so
+ * "has been here" is the right test and "is here now" is not: work is addressed
+ * to a participant precisely so it survives their session ending.
+ *
+ * Before anything durable is written the participants live in the ephemeral
+ * area, which is where a workspace with one session keeps everything.
+ */
+export async function knownParticipants(store, workspaceId) {
+  const snapshot = await store.snapshot(workspaceId,
+    { kinds: ["workspace", "participant"] });
+  const durable = snapshot.workspace !== null
+    ? snapshot.participants
+    : await store.ephemeral.list("participant");
+  return new Set(durable.map(participant => participant.participantId));
+}
+
+/**
+ * A recipient nobody has ever been is a typo, and saying "sent" to one is the
+ * worst answer available: `acc message --to physcis` reported success, the
+ * message went nowhere, and the agent that meant `physics` had no way to find
+ * out. `acc request` was worse - it made a task addressed to nobody, and the
+ * requester waited for an agent that does not exist.
+ *
+ * It also bounds the recipient list by construction. Nothing did: one message
+ * naming three thousand participants took 24.8 seconds, wrote three thousand
+ * receipts, and left every session in that workspace paying 5.1 seconds to
+ * attach and take one turn - past the point where a hook gives up and allows
+ * whatever it was guarding.
+ */
+export async function assertKnownParticipants(store, workspaceId, recipients) {
+  const known = await knownParticipants(store, workspaceId);
+  const strangers = [...new Set(recipients)].filter(name => !known.has(name));
+  if (strangers.length === 0) return;
+  // Not a usage error: the command is well formed and the workspace disagrees
+  // with it. Which matters beyond tidiness - the gate that runs every documented
+  // command holds them to being *accepted*, and every example names a peer that
+  // a fresh sandbox has never seen.
+  throw new AccError(EXIT.DATA,
+    `no participant here is called ${strangers.join(", ")}. `
+    + `This workspace has: ${[...known].sort().join(", ") || "nobody else yet"}`,
+    { strangers, known: [...known].sort() });
+}
+