agents-can-communicate 0.1.18 → 0.2.0

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.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));
+}

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

@@ -0,0 +1,276 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+
+import { AccError, EXIT, SCHEMA_VERSION, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { projectReleasedClaim, reconstructFinishRetry } from "./finish-retries.mjs";
+import { ensureMaterialised } from "./materialisation.mjs";
+
+export const receiptId = (messageId, participantId) => `receipt_${createHash("sha256")
+  .update(JSON.stringify([messageId, participantId])).digest("base64url")}`;
+
+const logicalContent = message => ({
+  toParticipantIds: message.toParticipantIds,
+  kind: message.kind,
+  obligation: message.obligation,
+  subject: message.subject,
+  body: message.body,
+  inReplyTo: message.inReplyTo,
+  artifacts: message.artifacts,
+  handoff: message.handoff,
+});
+
+const normalizedContent = input => logicalContent({
+  toParticipantIds: input.toParticipantIds ?? [],
+  kind: input.kind,
+  obligation: input.obligation,
+  subject: input.subject,
+  body: input.body,
+  inReplyTo: input.inReplyTo ?? null,
+  artifacts: input.artifacts ?? [],
+  handoff: input.handoff ?? null,
+});
+
+function existingMessage(tx, session, input) {
+  const existing = tx.list("message", message =>
+    message.workspaceId === session.workspaceId
+    && message.fromParticipantId === session.participantId
+    && message.clientMessageId === input.clientMessageId).at(0);
+  if (existing !== undefined
+    && !isDeepStrictEqual(logicalContent(existing), normalizedContent(input))) {
+    throw new AccError(EXIT.CONFLICT,
+      "clientMessageId was already used with different message content",
+      { clientMessageId: input.clientMessageId, messageId: existing.messageId });
+  }
+  return existing;
+}
+
+function assertCurrentSession(tx, session, action) {
+  const current = tx.get("session", session.sessionId);
+  if (current === null || current.state !== "open"
+    || current.generation !== session.generation) {
+    throw new AccError(EXIT.CONFLICT, `cannot ${action} from this session generation`,
+      { sessionId: session.sessionId });
+  }
+}
+
+function addressedRecipients(tx, message, session) {
+  if (message.toParticipantIds.length === 0) {
+    return [...new Set(tx.list("session", item => item.state === "open"
+      && item.participantId !== session.participantId)
+      .map(item => item.participantId))].sort();
+  }
+  const unique = [...new Set(message.toParticipantIds)];
+  if (unique.length !== message.toParticipantIds.length) {
+    throw new AccError(EXIT.USAGE, "a participant may be addressed only once", {});
+  }
+  const known = new Set(tx.list("participant").map(item => item.participantId));
+  const strangers = unique.filter(participantId => !known.has(participantId));
+  if (strangers.length > 0) {
+    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() });
+  }
+  return unique;
+}
+
+function threadFor(tx, messageId, inReplyTo) {
+  if (inReplyTo === null) return messageId;
+  const parent = tx.get("message", inReplyTo);
+  if (parent === null) {
+    throw new AccError(EXIT.DATA, "the message being replied to does not exist",
+      { inReplyTo });
+  }
+  return parent.threadId;
+}
+
+export function recordMessageInTransaction({ tx, session, input, now, messageId, ids,
+  action = "send a message" }) {
+  assertCurrentSession(tx, session, action);
+  const existing = existingMessage(tx, session, input);
+  if (existing !== undefined) {
+    return { message: existing, recipientParticipantIds: [], created: false };
+  }
+
+  const inReplyTo = input.inReplyTo ?? null;
+  const message = validateRecord("message", {
+    schemaVersion: SCHEMA_VERSION,
+    messageId,
+    threadId: threadFor(tx, messageId, inReplyTo),
+    clientMessageId: input.clientMessageId,
+    workspaceId: session.workspaceId,
+    fromParticipantId: session.participantId,
+    fromSessionId: session.sessionId,
+    toParticipantIds: input.toParticipantIds ?? [],
+    kind: input.kind,
+    obligation: input.obligation,
+    subject: input.subject,
+    body: input.body,
+    inReplyTo,
+    artifacts: input.artifacts ?? [],
+    handoff: input.handoff ?? null,
+    sentAt: now,
+  });
+  const recipientParticipantIds = addressedRecipients(tx, message, session);
+  tx.put("message", messageId, message);
+  for (const participantId of recipientParticipantIds) {
+    tx.put("receipt", receiptId(messageId, participantId), validateRecord("receipt", {
+      schemaVersion: SCHEMA_VERSION,
+      messageId,
+      workspaceId: session.workspaceId,
+      recipientParticipantId: participantId,
+      state: "queued",
+      updatedAt: now,
+    }));
+  }
+  tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+    workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+    type: "message.recorded", occurredAt: now,
+    payload: { messageId, threadId: message.threadId, recipientParticipantIds } });
+  return { message, recipientParticipantIds, created: true };
+}
+
+function handoffBody(goal, handoff) {
+  const section = (label, items) => items.length === 0
+    ? [] : [`${label}:`, ...items.map(item => `- ${item}`)];
+  return [goal, handoff.status,
+    ...section("completed", handoff.completed),
+    ...section("remaining", handoff.remaining),
+    ...section("blockers", handoff.blockers)].join("\n");
+}
+
+export function createConversationService(ports, sessions) {
+  const { store, clock, ids } = ports;
+
+  async function requireSession(input, action, { open = true } = {}) {
+    const located = await sessions.locateSession(input.sessionId, input.workspaceId);
+    if (located === null || located.record.generation !== input.generation
+      || (open && located.record.state !== "open")) {
+      throw new AccError(EXIT.CONFLICT, `cannot ${action} from this session generation`,
+        { sessionId: input.sessionId });
+    }
+    return located.record;
+  }
+
+  async function sendMessage(input) {
+    const session = await requireSession(input, "send a message");
+    await ensureMaterialised(ports, { workspaceId: session.workspaceId,
+      descriptor: input.descriptor, reason: "durable_object" });
+    return store.transaction(tx => recordMessageInTransaction({ tx, session, input,
+      now: clock.now(), messageId: ids.next("message"), ids }).message,
+    { kinds: ["participant", "session", "message", "receipt"] });
+  }
+
+  async function finishSession(input) {
+    const located = await sessions.locateSession(input.sessionId, input.workspaceId);
+    if (located === null || located.record.generation !== input.generation) {
+      throw new AccError(EXIT.CONFLICT, "cannot finish from this session generation",
+        { sessionId: input.sessionId });
+    }
+    const session = located.record;
+    await ensureMaterialised(ports, { workspaceId: session.workspaceId,
+      descriptor: input.descriptor, reason: "durable_object" });
+    const handoff = {
+      status: input.status ?? "partial",
+      completed: input.completed ?? [],
+      remaining: input.remaining ?? [],
+      blockers: input.blockers ?? [],
+      verification: input.verification ?? [],
+    };
+    const messageInput = {
+      clientMessageId: input.clientMessageId,
+      toParticipantIds: input.toParticipantId === undefined ? [] : [input.toParticipantId],
+      kind: "handoff",
+      obligation: input.toParticipantId === undefined ? "none" : "acknowledge",
+      subject: input.goal,
+      body: handoffBody(input.goal, handoff),
+      inReplyTo: null,
+      artifacts: input.artifacts ?? [],
+      handoff,
+    };
+    const now = clock.now();
+    const outcome = await store.transaction(tx => {
+      const current = tx.get("session", session.sessionId);
+      if (current === null || current.generation !== session.generation) {
+        throw new AccError(EXIT.CONFLICT, "cannot finish from this session generation",
+          { sessionId: session.sessionId });
+      }
+      const existing = existingMessage(tx, session, messageInput);
+      if (existing !== undefined) {
+        if (existing.fromSessionId !== session.sessionId) {
+          throw new AccError(EXIT.CONFLICT,
+            "clientMessageId belongs to a different finish generation",
+            { clientMessageId: input.clientMessageId, messageId: existing.messageId });
+        }
+        return { retry: true, message: existing, session: current };
+      }
+      if (current.state !== "open") {
+        throw new AccError(EXIT.CONFLICT, "cannot finish from this session generation",
+          { sessionId: session.sessionId });
+      }
+      const releasedClaims = tx.list("claim",
+        claim => claim.ownerSessionId === session.sessionId);
+      const recorded = recordMessageInTransaction({ tx, session, now,
+        messageId: ids.next("message"), ids, action: "finish",
+        input: messageInput });
+      for (const claim of releasedClaims) {
+        tx.remove("claim", claim.claimId, tx.generationOf("claim", claim.claimId));
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+          workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+          type: "claim.released", occurredAt: now,
+          payload: { claimId: claim.claimId, authority: null, reason: null,
+            replacedGeneration: claim.generation } });
+      }
+      const closed = { ...current, state: "closed", heartbeatAt: now };
+      tx.put("session", session.sessionId, closed,
+        tx.generationOf("session", session.sessionId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+        type: "session.closed", occurredAt: now,
+        payload: { cause: "finish", messageId: recorded.message.messageId,
+          sessionGeneration: session.generation,
+          releasedClaimIds: releasedClaims.map(claim => claim.claimId) } });
+      return { retry: false, message: recorded.message,
+        releasedClaims: releasedClaims.map(projectReleasedClaim), session: closed };
+    }, { kinds: ["participant", "session", "claim", "message", "receipt"] });
+    if (!outcome.retry) {
+      return { message: outcome.message, releasedClaims: outcome.releasedClaims,
+        session: outcome.session };
+    }
+    const releasedClaims = await reconstructFinishRetry({ store,
+      workspaceId: session.workspaceId, session: outcome.session, message: outcome.message });
+    return { message: outcome.message, releasedClaims, session: outcome.session };
+  }
+
+  async function pendingMessages(input = {}) {
+    return (await nextTurnDelivery(input)).queuedMessages;
+  }
+
+  async function nextTurnDelivery(input = {}) {
+    if (typeof input.participantId !== "string" || input.participantId === "") {
+      return { queuedMessages: [], liveOfferedMessageIds: [], roomMessageIds: [] };
+    }
+    const snapshot = await store.snapshot(input.workspaceId ?? store.workspaceId,
+      { kinds: ["message", "receipt"] });
+    const receiptByMessage = new Map(snapshot.receipts
+      .filter(item => item.recipientParticipantId === input.participantId)
+      .map(item => [item.messageId, item]));
+    const eligible = snapshot.messages.filter(message => receiptByMessage.has(message.messageId)
+      && message.fromSessionId !== input.exceptSessionId)
+      .sort((left, right) => left.sentAt.localeCompare(right.sentAt)
+        || left.messageId.localeCompare(right.messageId));
+    return {
+      queuedMessages: eligible.filter(message =>
+        receiptByMessage.get(message.messageId).state === "queued"),
+      liveOfferedMessageIds: eligible.filter(message => message.toParticipantIds.length > 0
+        && receiptByMessage.get(message.messageId).state === "offered")
+        .map(message => message.messageId),
+      roomMessageIds: eligible.filter(message => message.toParticipantIds.length === 0)
+        .map(message => message.messageId),
+    };
+  }
+
+  return { sendMessage, finishSession, pendingMessages, nextTurnDelivery };
+}