agents-can-communicate 0.1.18 → 0.2.0

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

@@ -1,334 +0,0 @@
-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/message-signals.mjs

@@ -1,41 +0,0 @@
-// A note is fire-and-forget: shown to the recipient once, no acknowledgement
-// owed, no standing reminder. Agents put decisions and warnings in notes anyway
-// - in one measured session a note carrying a merge decision was lost for three
-// hours - so this is the send-time tell that a note is waiting on a reply and
-// should have gone out as a question (`--requires-ack`) or a decision.
-//
-// A nudge, never a block, and deliberately not a keyword list: keyword lists
-// only fire in the language they were written in, and the agents here write in
-// several. A question mark marks a question in every script, and the warning
-// sign is the one glyph a peer reaches for when something must not be missed.
-const QUESTION = /[?？]/u;
-const WARNING = /⚠/u;
-
-/**
- * Does this note read like it needs a response from the recipient?
- *
- * Pure and total: a missing subject or body is empty text, not an error, so the
- * caller can hand it a message record without pre-checking its shape.
- */
-export function looksConsequential({ subject = "", body = "" } = {}) {
-  const text = `${subject}\n${body}`;
-  return QUESTION.test(text) || WARNING.test(text);
-}
-
-const NUDGE = "this note reads like it needs a reply, but a note is fire-and-forget: "
-  + "the recipient sees it once and owes no response. Re-send with --requires-ack "
-  + "for an answer, or record it with `acc decide`.";
-
-/**
- * The send-time advisory for a note that looks like it is waiting on a reply,
- * or null when there is nothing to say.
- *
- * Only notes, and only ones the sender did not already mark `requiresAck`: a
- * question already keeps a standing reminder, and nudging it would be noise.
- * A nudge, never a block - the send has already happened; this only tells the
- * sender the shape it chose does not carry the weight the words do.
- */
-export function noteNudge(message) {
-  return message?.type === "note" && message?.requiresAck !== true
-    && looksConsequential(message ?? {}) ? NUDGE : null;
-}

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

@@ -1,95 +0,0 @@
-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 } });
-  }
-}