agents-can-communicate 0.3.1 → 0.4.1

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

@@ -2,6 +2,8 @@ import { AccError, EXIT, SCHEMA_VERSION, advanceReceipt }
   from "@agents-can-communicate/protocol";
 
 import { receiptId, recordMessageInTransaction } from "./conversations.mjs";
+import { messagePage, messageSummary } from "./message-pages.mjs";
+import { decisionView, isCurrentDecision } from "./decision-state.mjs";
 
 const listable = (message, receipt) => receipt.state === "queued" || receipt.state === "offered"
   || (receipt.state === "retrieved" && message.obligation !== "none");
@@ -9,14 +11,19 @@ const listable = (message, receipt) => receipt.state === "queued" || receipt.sta
 export function createInboxService(ports, sessions) {
   const { store, clock, ids } = ports;
 
-  async function requireOpen(input, action) {
-    const located = await sessions.locateSession(input.sessionId, input.workspaceId);
-    if (located === null || located.record.state !== "open"
-      || located.record.generation !== input.generation) {
+  async function requireOpen(input, action, tx) {
+    // A solo inbox may have no durable session yet. Inside a transaction the
+    // same writer lock also protects this ephemeral read from replacement.
+    const current = tx === undefined
+      ? (await sessions.locateSession(input.sessionId, input.workspaceId))?.record
+      : tx.get("session", input.sessionId)
+        ?? await store.ephemeral.get("session", input.sessionId);
+    if (current == null || current.state !== "open"
+      || current.generation !== input.generation) {
       throw new AccError(EXIT.CONFLICT, `cannot ${action} from this session generation`,
         { sessionId: input.sessionId });
     }
-    return located.record;
+    return current;
   }
 
   function requireOwnedReceipt(tx, session, messageId) {
@@ -46,19 +53,38 @@ export function createInboxService(ports, sessions) {
     return { message: owned.message, receipt };
   }
 
+  async function listInbox(input) {
+    const session = await requireOpen(input, "list the inbox");
+    return store.transaction(async tx => {
+      await requireOpen(input, "list the inbox", tx);
+      const receipts = new Map(tx.list("receipt", receipt =>
+        receipt.recipientParticipantId === session.participantId)
+        .map(receipt => [receipt.messageId, receipt]));
+      const all = tx.list("message"), view = decisionView(all);
+      const messages = all.filter(message => receipts.has(message.messageId)).map(view);
+      return messagePage(messages, input, {
+        include: message => isCurrentDecision(message) && listable(message, receipts.get(message.messageId)),
+        project: message => ({ message: messageSummary(message),
+          receipt: receipts.get(message.messageId) }),
+      });
+    }, { kinds: ["session", "message", "receipt"] });
+  }
+
   async function readInbox(input) {
     const session = await requireOpen(input, "read the inbox");
     const now = clock.now();
-    return store.transaction(tx => {
-      const messages = new Map(tx.list("message").map(item => [item.messageId, item]));
+    return store.transaction(async tx => {
+      await requireOpen(input, "read the inbox", tx);
+      const all = tx.list("message"), view = decisionView(all);
+      const messages = new Map(all.map(item => [item.messageId, view(item)]));
       let selected = tx.list("receipt", receipt =>
         receipt.recipientParticipantId === session.participantId)
         .filter(receipt => messages.has(receipt.messageId));
       if (input.messageId === undefined) {
-        selected = selected.filter(receipt => listable(messages.get(receipt.messageId), receipt));
+        selected = selected.filter(receipt => listable(messages.get(receipt.messageId), receipt)
+          && isCurrentDecision(messages.get(receipt.messageId)));
       } else {
-        selected = selected.filter(receipt => receipt.messageId === input.messageId
-          && receipt.state !== "acknowledged");
+        selected = selected.filter(receipt => receipt.messageId === input.messageId);
         if (selected.length === 0) {
           throw new AccError(EXIT.CONFLICT,
             "that message is not recoverable by this participant",
@@ -70,17 +96,22 @@ export function createInboxService(ports, sessions) {
         const b = messages.get(right.messageId);
         return a.sentAt.localeCompare(b.sentAt) || a.messageId.localeCompare(b.messageId);
       });
-      return selected.map(receipt => advanceOwned(tx, session, receipt.messageId,
-        "retrieved", now));
-    }, { kinds: ["message", "receipt"] });
+      // An exact read can inspect a resolved message. Inspection must neither
+      // move its receipt backward nor refresh its timestamp or emit an event.
+      return selected.map(receipt => receipt.state === "acknowledged"
+        ? { message: messages.get(receipt.messageId), receipt }
+        : { ...advanceOwned(tx, session, receipt.messageId, "retrieved", now),
+          message: messages.get(receipt.messageId) });
+    }, { kinds: ["session", "message", "receipt"] });
   }
 
   async function acknowledgeMessage(input) {
     const session = await requireOpen(input, "acknowledge a message");
     const now = clock.now();
-    return store.transaction(tx => advanceOwned(tx, session, input.messageId,
-      "acknowledged", now).receipt,
-    { kinds: ["message", "receipt"] });
+    return store.transaction(async tx => {
+      await requireOpen(input, "acknowledge a message", tx);
+      return advanceOwned(tx, session, input.messageId, "acknowledged", now).receipt;
+    }, { kinds: ["session", "message", "receipt"] });
   }
 
   async function replyToMessage(input) {
@@ -114,5 +145,5 @@ export function createInboxService(ports, sessions) {
     }, { kinds: ["participant", "session", "message", "receipt"] });
   }
 
-  return { readInbox, replyToMessage, acknowledgeMessage };
+  return { listInbox, readInbox, replyToMessage, acknowledgeMessage };
 }

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

@@ -9,24 +9,26 @@ import { isMaterialised } from "./materialisation.mjs";
 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) {
+  async function requireOwner(sessionId, workspaceId, generation, tx) {
+    const current = tx === undefined
+      ? (await sessions.locateSession(sessionId, workspaceId))?.record
+      : tx.get("session", sessionId);
+    if (current == null) {
       throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
     }
-    if (existing.record.generation !== generation) {
+    if (current.generation !== generation) {
       throw new AccError(EXIT.CONFLICT, "intent belongs to a replaced session generation",
-        { sessionId, expected: generation, actual: existing.record.generation });
+        { sessionId, expected: generation, actual: current.generation });
     }
-    if (existing.record.state !== "open") {
+    if (current.state !== "open") {
       throw new AccError(EXIT.CONFLICT, "a closed session cannot publish intent", { sessionId });
     }
-    return existing;
+    return current;
   }
 
   async function setIntent(input) {
     const owner = await requireOwner(input.sessionId, input.workspaceId, input.generation);
-    const workspaceId = owner.record.workspaceId;
+    const workspaceId = owner.workspaceId;
     const now = clock.now();
     const intent = validateRecord("intent", {
       schemaVersion: SCHEMA_VERSION,
@@ -40,34 +42,52 @@ export function createIntentService(ports, sessions) {
     });
 
     if (!await isMaterialised(store, workspaceId)) {
-      await store.ephemeral.put("intent", input.sessionId, intent);
-      return intent;
+      const written = await store.ephemeral.update("intent", input.sessionId, async () => {
+        // Promotion may have won since the branch above. Never publish a new
+        // ephemeral copy that durable readers cannot see or cleanup could erase.
+        if (await isMaterialised(store, workspaceId)) return null;
+        await requireOwner(input.sessionId, workspaceId, input.generation);
+        return intent;
+      });
+      if (written !== null) return written;
     }
     await store.transaction(async tx => {
+      await requireOwner(input.sessionId, workspaceId, input.generation, 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"] });
+    }, { kinds: ["session", "intent"] });
     return intent;
   }
 
   async function clearIntent(input) {
     const owner = await requireOwner(input.sessionId, input.workspaceId, input.generation);
-    const workspaceId = owner.record.workspaceId;
+    const workspaceId = owner.workspaceId;
     if (!await isMaterialised(store, workspaceId)) {
-      await store.ephemeral.delete("intent", input.sessionId);
-      return;
+      let cleared = false;
+      await store.ephemeral.delete("intent", input.sessionId, async () => {
+        if (await isMaterialised(store, workspaceId)) return false;
+        await requireOwner(input.sessionId, workspaceId, input.generation);
+        cleared = true;
+        return true;
+      });
+      if (cleared) return;
+      // A missing intent bypasses the delete guard. A close may have removed
+      // it, or promotion may have moved it to durable storage while we waited.
+      await requireOwner(input.sessionId, workspaceId, input.generation);
+      if (!await isMaterialised(store, workspaceId)) return;
     }
     const now = clock.now();
     await store.transaction(async tx => {
+      await requireOwner(input.sessionId, workspaceId, input.generation, 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"] });
+    }, { kinds: ["session", "intent"] });
   }
 
   return { setIntent, clearIntent };

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

@@ -24,13 +24,15 @@ export async function isMaterialised(store, workspaceId) {
 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 => {
+    // Ephemeral writers use this same mutex. Reading before taking it could
+    // resurrect a closed owner or replace an intent with an older snapshot.
+    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";
     // 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

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

@@ -0,0 +1,75 @@
+import { AccError, EXIT, MESSAGE_KINDS, assertPortableId }
+  from "@agents-can-communicate/protocol";
+
+const DEFAULT_LIMIT = 20;
+const PAGE_BYTES = 12_000;
+const usage = message => { throw new AccError(EXIT.USAGE, message); };
+const newestFirst = (a, b) => b.sentAt.localeCompare(a.sentAt)
+  || b.messageId.localeCompare(a.messageId);
+
+export function assertMessageId(value, label = "message id") {
+  try { assertPortableId(value, label); }
+  catch { usage(`${label} must be a complete message id returned by ACC`); }
+}
+
+function shortSubject(subject) {
+  if (Buffer.byteLength(subject) <= 160) return subject;
+  let text = "";
+  for (const character of subject) {
+    if (Buffer.byteLength(text + character + "…") > 160) break;
+    text += character;
+  }
+  return `${text}…`;
+}
+
+export function messageSummary(message) {
+  // An allowlist keeps artifacts, handoff details, and future peer payload
+  // fields out of discovery. A summary is not a retrieved message body.
+  return {
+    messageId: message.messageId, threadId: message.threadId,
+    fromParticipantId: message.fromParticipantId, fromSessionId: message.fromSessionId,
+    kind: message.kind, obligation: message.obligation,
+    subject: shortSubject(message.subject), sentAt: message.sentAt,
+    inReplyTo: message.inReplyTo, bodyBytes: Buffer.byteLength(message.body),
+    artifactCount: message.artifacts.length, trust: "untrusted peer content",
+    ...(message.decisionStatus === undefined ? {} : { decisionStatus: message.decisionStatus }),
+  };
+}
+
+export function messagePage(messages, input, { include = () => true,
+  project = messageSummary, metadata = {} } = {}) {
+  const limit = input.limit === undefined ? DEFAULT_LIMIT : input.limit;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+    usage("message list limit must be an integer from 1 to 500");
+  }
+  if (input.kind !== undefined && !MESSAGE_KINDS.includes(input.kind)) {
+    usage(`message type is one of ${MESSAGE_KINDS.join(", ")}`);
+  }
+  let anchor = null;
+  if (input.cursor != null) {
+    assertMessageId(input.cursor, "message cursor");
+    anchor = messages.find(message => message.messageId === input.cursor);
+    if (anchor === undefined || (input.kind !== undefined && anchor.kind !== input.kind)) {
+      usage("message cursor is not in this message list; start again without a cursor");
+    }
+  }
+  // Resolve the anchor before filtering pending state. Reading or resolving
+  // that message between pages must not shift the next page as an offset would.
+  const selected = messages.filter(message => include(message)
+    && (input.kind === undefined || message.kind === input.kind)
+    && (anchor === null || newestFirst(message, anchor) > 0)).sort(newestFirst);
+  const items = [];
+  for (const message of selected.slice(0, limit)) {
+    const item = project(message);
+    // Reserve a complete continuation id even when count, rather than bytes,
+    // eventually ends the page. Never slice a summary or a recovery id in half.
+    const candidate = { ...metadata, items: [...items, item], nextCursor: message.messageId };
+    if (Buffer.byteLength(JSON.stringify(candidate, null, 2)) > PAGE_BYTES) break;
+    items.push(item);
+  }
+  if (selected.length > 0 && items.length === 0) {
+    throw new AccError(EXIT.DATA, "one message summary exceeds the page budget");
+  }
+  return { ...metadata, items, nextCursor: items.length < selected.length
+    ? selected[items.length - 1].messageId : null };
+}

package/node_modules/@agents-can-communicate/core/src/next-turn-delivery.mjs

@@ -0,0 +1,31 @@
+export async function nextTurnDelivery(store, input = {}) {
+  if (typeof input.participantId !== "string" || input.participantId === "") {
+    return { queuedMessages: [], liveOfferedMessageIds: [], reminderMessageIds: [],
+      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.map(decisionView(snapshot.messages))
+    .filter(message => isCurrentDecision(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),
+    // A missing body is not evidence of delivery: a degraded adapter may have
+    // withheld it. Only this recipient's durable receipt permits a reminder.
+    reminderMessageIds: eligible.filter(message => message.obligation !== "none"
+      && ["offered", "retrieved"].includes(receiptByMessage.get(message.messageId).state))
+      .map(message => message.messageId),
+    roomMessageIds: eligible.filter(message => message.toParticipantIds.length === 0)
+      .map(message => message.messageId),
+  };
+}
+import { decisionView, isCurrentDecision } from "./decision-state.mjs";

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

@@ -0,0 +1,128 @@
+import { AccError, EXIT, SCHEMA_VERSION, assertPortableId, createId, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { isMaterialised, materialise } from "./materialisation.mjs";
+
+const sessionRecord = (input, now, generation) => validateRecord("session", {
+  schemaVersion: SCHEMA_VERSION,
+  sessionId: input.sessionId,
+  participantId: input.participantId,
+  workspaceId: input.workspaceId,
+  generation,
+  harness: input.harness,
+  state: "open",
+  parentSessionId: input.parentSessionId ?? null,
+  checkoutRoot: input.checkoutRoot ?? null,
+  branch: input.branch ?? null,
+  pid: input.pid ?? null,
+  // Both default to the weaker reading. A session that declares nothing is a
+  // session nothing intercepts - an MCP client, or a CLI user - and claiming
+  // otherwise would promise enforcement that is not there.
+  enforcement: input.enforcement ?? "advisory",
+  lifecycle: input.lifecycle ?? "manual",
+  heartbeatCadenceMs: input.heartbeatCadenceMs,
+  startedAt: now,
+  heartbeatAt: now,
+});
+
+const participantRecord = (input, now) => validateRecord("participant", {
+  schemaVersion: SCHEMA_VERSION,
+  participantId: input.participantId,
+  workspaceId: input.workspaceId,
+  displayName: input.displayName ?? input.participantId,
+  kind: input.participantKind ?? "agent",
+  createdAt: now,
+});
+
+// Opening owns acquisition in both stores. Lifecycle updates remain in sessions.mjs.
+export function createSessionOpener(ports, locate) {
+  const { store, clock, ids, pidIsAlive } = ports;
+
+  function assertReplaceable(existing, probe) {
+    if (existing.record.state === "closed") return;
+    // Presence staleness alone never replaces ownership: an idle-but-open
+    // session may resume at any moment, and a wrong "gone" verdict there
+    // self-corrects the moment that session next takes a turn. A wrong
+    // replacement does not self-correct - it takes the generation, and the
+    // original session's own heartbeats fail with CONFLICT from then on. So
+    // only a pid confirmed dead is authority to replace; "we cannot tell" -
+    // a session with no recorded pid - is never enough, however long the
+    // silence.
+    const live = probe ?? (record => (record.pid ?? null) === null
+      || pidIsAlive(record.pid));
+    if (live(existing.record)) {
+      throw new AccError(EXIT.CONFLICT, "the session id is already live",
+        { sessionId: existing.record.sessionId });
+    }
+  }
+
+  async function openSession(input) {
+    const workspaceId = input.workspaceId ?? store.workspaceId;
+    assertPortableId(workspaceId, "workspace id");
+    if (store.workspaceId !== undefined && workspaceId !== store.workspaceId) {
+      throw new AccError(EXIT.CONFLICT, "cannot open a session in a different workspace",
+        { workspaceId, storeWorkspaceId: store.workspaceId });
+    }
+    assertPortableId(input.participantId, "participant id");
+    const sessionId = input.sessionId ?? createId("session");
+    // A caller may persist a fresh owner pair before creation. Such a reserved
+    // generation is insert-only: it must never replace an existing session.
+    const assertAvailable = current => {
+      if (current === null) return;
+      if (input.generation !== undefined) {
+        throw new AccError(EXIT.CONFLICT, "a reserved generation requires a new session id",
+          { sessionId });
+      }
+      assertReplaceable({ record: current }, input.probe);
+    };
+    const existing = await locate(sessionId, workspaceId);
+    assertAvailable(existing?.record ?? null);
+
+    const now = clock.now();
+    const session = sessionRecord({ ...input, workspaceId, sessionId }, now,
+      input.generation === undefined ? ids.next("generation") : input.generation);
+    const participant = participantRecord({ ...input, workspaceId }, now);
+
+    const openDurable = async () => {
+      await store.transaction(async tx => {
+        const current = tx.get("session", sessionId);
+        assertAvailable(current);
+        const replaced = current?.generation ?? null;
+        if (tx.get("participant", participant.participantId) === null) {
+          tx.put("participant", participant.participantId, participant);
+        }
+        tx.put("session", sessionId, session, tx.generationOf("session", sessionId));
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+          actorSessionId: sessionId, type: "session.opened", occurredAt: now,
+          payload: { replaced } });
+      }, { kinds: ["participant", "session"] });
+      return session;
+    };
+    if (await isMaterialised(store, workspaceId)) return openDurable();
+
+    // Preparing a participant must not rename one that already exists, or
+    // recreate an ephemeral copy after promotion has taken ownership.
+    await store.ephemeral.update("participant", participant.participantId, async current =>
+      await isMaterialised(store, workspaceId) ? null : current ?? participant);
+    const opened = await store.ephemeral.update("session", sessionId, async current => {
+      // Check even when no copy remains: promotion may have retired it while
+      // this opener waited. Only the durable transaction may acquire that id now.
+      if (await isMaterialised(store, workspaceId)) return null;
+      assertAvailable(current);
+      return session;
+    });
+    if (opened === null) return openDurable();
+    // The approved trigger is the SECOND live session, not the first: a lone
+    // session must be able to open and close without leaving a trace.
+    const live = (await store.ephemeral.list("session")).filter(item => item.state === "open");
+    // Another opener may have promoted us after acquisition; completing the
+    // idempotent pass also retires any copies that are still pending cleanup.
+    if (live.length > 1 || await isMaterialised(store, workspaceId)) {
+      await materialise(ports, { workspaceId, descriptor: input.descriptor,
+        reason: "second_live_session" });
+    }
+    return session;
+  }
+
+  return openSession;
+}