agents-can-communicate 0.1.18 → 0.3.0

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

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

@@ -0,0 +1,131 @@
+import { AccError, EXIT, SCHEMA_VERSION, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+function conflict(sessionId) {
+  return new AccError(EXIT.CONFLICT,
+    "cannot publish a delivery binding for anything but this open session generation",
+    { sessionId });
+}
+
+export function createDeliveryBindingService(ports, sessions) {
+  const { store, clock } = ports;
+
+  async function currentBindings(now) {
+    const bindings = await store.ephemeral.list("deliveryBinding");
+    const current = [];
+    for (const binding of bindings) {
+      const located = await sessions.locateSession(binding.sessionId);
+      if (located?.record.state !== "open"
+        || located.record.generation !== binding.generation) continue;
+      // A retirement is final. It is kept as a record rather than deleted so a
+      // stale generation cannot race a successor's publication, and it must
+      // never be read back as a live endpoint.
+      if (binding.retiredAt !== null && binding.retiredAt !== undefined) continue;
+      current.push({ binding, participantId: located.record.participantId,
+        reachable: Date.parse(binding.leaseUntil) > Date.parse(now) });
+    }
+    return current.sort((left, right) =>
+      left.binding.sessionId.localeCompare(right.binding.sessionId));
+  }
+
+  async function publishDeliveryBinding(input) {
+    const located = await sessions.locateSession(input.sessionId);
+    if (located?.record.state !== "open" || located.record.generation !== input.generation) {
+      throw conflict(input.sessionId);
+    }
+    let binding;
+    try {
+      binding = validateRecord("deliveryBinding", {
+        schemaVersion: SCHEMA_VERSION,
+        sessionId: input.sessionId,
+        generation: input.generation,
+        adapterId: input.adapterId,
+        clientVersion: input.clientVersion,
+        availableModes: Array.isArray(input.availableModes)
+          ? [...input.availableModes] : input.availableModes,
+        livePolicy: input.livePolicy,
+        opaqueEndpointRef: input.opaqueEndpointRef,
+        leaseUntil: input.leaseUntil,
+        retiredAt: null,
+      });
+    } catch (error) {
+      if (error?.details?.field === "opaqueEndpointRef") {
+        throw new AccError(error.code, error.message, { field: "opaqueEndpointRef" });
+      }
+      throw error;
+    }
+    await store.ephemeral.update("deliveryBinding", binding.sessionId, async () => {
+      // This check runs while the ephemeral key's writer lock is held. A stale
+      // publisher that passed the earlier check cannot replace a successor's
+      // endpoint after that successor becomes current.
+      const current = await sessions.locateSession(input.sessionId);
+      if (current?.record.state !== "open"
+        || current.record.generation !== input.generation) {
+        throw conflict(input.sessionId);
+      }
+      return binding;
+    });
+    const stillCurrent = await sessions.locateSession(input.sessionId);
+    if (stillCurrent?.record.state !== "open"
+      || stillCurrent.record.generation !== input.generation) {
+      // Do not delete here: a successor generation may have published between
+      // our put and this recheck. A stale record is filtered on every read and
+      // is safe; deleting a successor's endpoint is not.
+      throw conflict(input.sessionId);
+    }
+    return binding;
+  }
+
+  // Clearing is an in-place retirement under the same writer lock as
+  // publication. The store's update contract has no deletion sentinel and its
+  // delete() takes the same mutex, so this is the one atomic form: a stale
+  // generation cannot retire a successor's endpoint, and an absent or
+  // already-retired binding stays as it is.
+  //
+  // The retirement is recorded as its own fact rather than as an expired lease.
+  // Expiry and retirement used to be the same edit, so a channel still renewing
+  // its endpoint could extend a binding the session had already given up.
+  async function clearDeliveryBinding({ sessionId, generation }) {
+    await store.ephemeral.update("deliveryBinding", sessionId, async current => {
+      if (current === null || current === undefined) return null;
+      if (current.generation !== generation) throw conflict(sessionId);
+      if (current.retiredAt !== null && current.retiredAt !== undefined) return null;
+      const now = clock.now();
+      return { ...current, leaseUntil: now, retiredAt: now };
+    });
+  }
+
+  /**
+   * Extend the lease on a binding whose endpoint is still being served.
+   *
+   * Only the process holding the endpoint knows it is alive, and for a client
+   * with no heartbeat nothing else refreshes this record: measured on a real
+   * Claude 2.1.259 session, the channel kept its registration renewed while
+   * this lease went stale about a minute after the last turn, and the router
+   * stopped offering to a session that was still serving.
+   *
+   * Narrow on purpose. It moves the lease and nothing else, refuses anything
+   * but the current open generation, and will not revive a retired binding.
+   */
+  async function refreshDeliveryBinding({ sessionId, generation, leaseUntil }) {
+    const located = await sessions.locateSession(sessionId);
+    if (located?.record.state !== "open" || located.record.generation !== generation) {
+      throw conflict(sessionId);
+    }
+    await store.ephemeral.update("deliveryBinding", sessionId, async current => {
+      if (current === null || current === undefined) return null;
+      if (current.generation !== generation) throw conflict(sessionId);
+      if (current.retiredAt !== null && current.retiredAt !== undefined) return null;
+      return validateRecord("deliveryBinding", { ...current, leaseUntil });
+    });
+  }
+
+  async function listDeliveryBindings({ participantId, now }) {
+    return (await currentBindings(now))
+      .filter(item => item.participantId === participantId && item.reachable)
+      .map(item => item.binding);
+  }
+
+  return { publishDeliveryBinding, clearDeliveryBinding, refreshDeliveryBinding,
+    listDeliveryBindings, currentBindings };
+}

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

@@ -0,0 +1,97 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+const PAGE_SIZE = 256;
+
+export const projectReleasedClaim = claim => ({
+  claimId: claim.claimId,
+  resource: claim.resource,
+  mode: claim.mode,
+});
+
+function conflict(message) {
+  return new AccError(EXIT.CONFLICT,
+    "clientMessageId belongs to a different finish generation",
+    { clientMessageId: message.clientMessageId, messageId: message.messageId });
+}
+
+async function allEvents(store, workspaceId) {
+  const events = [];
+  let cursor = null;
+  while (true) {
+    const page = await store.eventsSince(workspaceId, cursor, PAGE_SIZE);
+    if (page.events.length === 0) return events;
+    events.push(...page.events);
+    cursor = page.cursor;
+  }
+}
+
+function claimProjection(events, releaseIndex) {
+  const release = events[releaseIndex];
+  const claimId = release.payload.claimId;
+  const facts = events.slice(0, releaseIndex + 1).findLast(event =>
+    (event.type === "claim.acquired" || event.type === "claim.renewed")
+      && event.payload.claimId === claimId
+      && typeof event.payload.resource === "string");
+  return facts === undefined ? null : {
+    claimId,
+    resource: facts.payload.resource,
+    mode: facts.payload.mode,
+  };
+}
+
+function correlatedReleaseIndexes(events, recordedIndex, closedIndex, session, message) {
+  const close = events[closedIndex];
+  const payload = close.payload;
+  const keys = Object.keys(payload).sort();
+  const expectedKeys = ["cause", "messageId", "releasedClaimIds", "sessionGeneration"];
+  if (keys.length !== expectedKeys.length
+    || !keys.every((key, index) => key === expectedKeys[index])
+    || payload.cause !== "finish"
+    || payload.messageId !== message.messageId
+    || payload.sessionGeneration !== session.generation
+    || !Array.isArray(payload.releasedClaimIds)
+    || payload.releasedClaimIds.some(claimId => typeof claimId !== "string")
+    || new Set(payload.releasedClaimIds).size !== payload.releasedClaimIds.length) {
+    throw conflict(message);
+  }
+
+  const between = events.slice(recordedIndex + 1, closedIndex);
+  if (between.length !== payload.releasedClaimIds.length
+    || between.some(event => event.type !== "claim.released"
+      || event.actorSessionId !== session.sessionId
+      || event.payload.authority !== null
+      || event.payload.reason !== null)) {
+    throw conflict(message);
+  }
+  const actualIds = between.map(event => event.payload.claimId);
+  if (actualIds.some((claimId, index) => claimId !== payload.releasedClaimIds[index])) {
+    throw conflict(message);
+  }
+  return actualIds.map((claimId, offset) => recordedIndex + offset + 1);
+}
+
+export async function reconstructFinishRetry({ store, workspaceId, session, message }) {
+  const events = await allEvents(store, workspaceId);
+  const recordedIndex = events.findIndex(event => event.type === "message.recorded"
+    && event.payload.messageId === message.messageId
+    && event.actorSessionId === session.sessionId);
+  if (session.state !== "closed" || recordedIndex === -1) throw conflict(message);
+
+  const laterOpen = events.slice(recordedIndex + 1).some(event =>
+    event.type === "session.opened" && event.actorSessionId === session.sessionId);
+  if (laterOpen) throw conflict(message);
+
+  const closedOffset = events.slice(recordedIndex + 1).findIndex(event =>
+    event.type === "session.closed" && event.actorSessionId === session.sessionId);
+  if (closedOffset === -1) throw conflict(message);
+  const closedIndex = recordedIndex + closedOffset + 1;
+  const releaseIndexes = correlatedReleaseIndexes(events, recordedIndex, closedIndex,
+    session, message);
+  const releasedClaims = releaseIndexes.map(index => claimProjection(events, index));
+  if (releasedClaims.includes(null)) throw conflict(message);
+  const snapshot = await store.snapshot(workspaceId, { kinds: ["claim"] });
+  if (snapshot.claims.some(claim => claim.ownerSessionId === session.sessionId)) {
+    throw conflict(message);
+  }
+  return releasedClaims;
+}