agents-can-communicate 0.1.0

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

@@ -0,0 +1,273 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { classifySessionPresence } from "./sessions.mjs";
+import { overlaps } from "./claims.mjs";
+
+const DEFAULT_LIMIT = 100;
+
+// The shape every event carries, and the only thing a caller may ask to resume
+// from. `null` means the beginning, which is what a session with no cursor yet
+// has.
+const CURSOR = /^[0-9]{16}$/;
+
+// The two a caller may ask for. An unknown one used to become `delta`, so
+// `--scope ful` answered the one question the full scope exists for - "show me
+// everything, I cannot see the rest of the system" - with a delta carrying no
+// snapshot at all, and the agent concluded there was nothing to see.
+const SCOPES = Object.freeze(["delta", "full"]);
+
+function assertScope(scope) {
+  if (scope != null && !SCOPES.includes(scope)) {
+    throw new AccError(EXIT.USAGE,
+      `scope is one of ${SCOPES.join(", ")}; leave it out for ${SCOPES[0]}`, { scope });
+  }
+}
+
+function assertCursor(cursor) {
+  if (typeof cursor !== "string" || !CURSOR.test(cursor)) {
+    throw new AccError(EXIT.USAGE,
+      "a cursor is the 16-digit sequence a previous sync returned; "
+      + "leave it out to start from the beginning",
+      { cursor });
+  }
+}
+
+// Attention is computed from explicit rules, never from a hidden classifier.
+// Lower priority sorts first.
+//
+// Exported so a test can prove every kind listed here is reachable. A fifth
+// entry once sat here with no rule behind it, which read as a feature in review
+// and produced nothing at runtime.
+export const ATTENTION_PRIORITY = Object.freeze({
+  direct_request: 1,
+  claim_conflict: 2,
+  task_unblocked: 3,
+  coordinator_missing: 4,
+  request_stalled: 5,
+  claim_expired: 6,
+});
+
+function directRequests(snapshot, participantId) {
+  const items = [];
+  for (const receipt of snapshot.receipts ?? []) {
+    if (receipt.recipientParticipantId !== participantId) continue;
+    if (receipt.state === "acknowledged" || receipt.state === "failed") continue;
+    const message = (snapshot.messages ?? []).find(item => item.messageId === receipt.messageId);
+    if (message === undefined || !message.requiresAck) continue;
+    items.push({ kind: "direct_request", priority: ATTENTION_PRIORITY.direct_request,
+      sourceId: message.messageId, summary: message.subject });
+  }
+  return items;
+}
+
+/**
+ * A claim of yours that has run out.
+ *
+ * A lease lapses on the clock, and nothing said so. Measured: while it held, a
+ * peer's write into the file was refused; three seconds later the same write
+ * went through, and the holder's turn was identical before and after. It went on
+ * working on a file it believed it had reserved, and everyone else was free to
+ * change it.
+ *
+ * Only for the session that took it, and only while that session is the one
+ * asking: a lapsed claim is news to its owner and nobody else's business.
+ * Re-claiming refreshes the lease and clears this; releasing it clears it too.
+ */
+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}` }));
+}
+
+/**
+ * Work waiting on me.
+ *
+ * Addressed by participant, so a request survives the recipient restarting -
+ * the next session of that agent is told about it. A task already taken by one
+ * of my sessions matches too, since that session may have been replaced.
+ *
+ * Unaddressed tasks are deliberately absent. Anyone may take one, but pushing
+ * every open task into every turn is how a coordination layer becomes noise.
+ */
+function unblockedTasks(snapshot, session, participantId) {
+  const mine = task => (task.assigneeParticipantId !== null
+    && task.assigneeParticipantId === participantId)
+    || (task.assigneeSessionId !== null && task.assigneeSessionId === session?.sessionId);
+  return (snapshot.tasks ?? [])
+    .filter(task => task.state === "pending" && mine(task))
+    .map(task => ({ kind: "task_unblocked", priority: ATTENTION_PRIORITY.task_unblocked,
+      sourceId: task.taskId, summary: task.title }));
+}
+
+/**
+ * Work you asked for that nobody is doing any more.
+ *
+ * A task taken by a session that then crashed stayed `in_progress` for good:
+ * the requester was told nothing and nobody else could take it. Unlike the
+ * one-shot answers a request produces, this repeats until it is resolved,
+ * because it stays true until someone picks the work back up.
+ */
+/**
+ * A question nobody is left to answer.
+ *
+ * The task rule below tells a requester when work they asked for is going
+ * nowhere. A `requiresAck` message had no such rule, and a message is the other
+ * half of the same act: an agent asked a peer a direct question, the peer's
+ * session ended without answering, and the asker's next turn was empty. Not
+ * "still waiting" - empty. Measured, with the only other agent gone and an
+ * unanswered question standing between them.
+ *
+ * The same kind as the task case, because it is the same fact about the world:
+ * you asked, and there is nobody there.
+ */
+function unansweredQuestions(snapshot, participantId, onlineParticipants) {
+  const items = [];
+  for (const receipt of snapshot.receipts ?? []) {
+    if (receipt.state === "acknowledged" || receipt.state === "failed") continue;
+    const message = (snapshot.messages ?? [])
+      .find(item => item.messageId === receipt.messageId);
+    if (message === undefined || !message.requiresAck) continue;
+    if (message.fromParticipantId !== participantId) continue;
+    // Not answered yet by someone who is here is ordinary waiting, and saying so
+    // every turn would be noise the reader learns to skip.
+    if (onlineParticipants.has(receipt.recipientParticipantId)) continue;
+    items.push({ kind: "request_stalled", priority: ATTENTION_PRIORITY.request_stalled,
+      sourceId: message.messageId,
+      summary: `${message.subject} - ${receipt.recipientParticipantId} is not here to answer` });
+  }
+  return items;
+}
+
+function stalledRequests(snapshot, participantId, now) {
+  const live = new Map((snapshot.sessions ?? [])
+    .map(session => [session.sessionId, classifySessionPresence(session, now)]));
+  const onlineParticipants = new Set((snapshot.sessions ?? [])
+    .filter(session => classifySessionPresence(session, now) === "online")
+    .map(session => session.participantId));
+  const goingNowhere = task => {
+    // Taken by someone who has gone quiet.
+    if (task.state === "in_progress") {
+      return task.assigneeSessionId !== null
+        && live.get(task.assigneeSessionId) !== "online";
+    }
+    // Or waiting on an agent that is not here - including one that closed and
+    // never came back, which leaves the work addressed to nobody at all.
+    return task.state === "pending" && task.assigneeParticipantId !== null
+      && !onlineParticipants.has(task.assigneeParticipantId);
+  };
+  return [
+    ...(snapshot.tasks ?? [])
+      .filter(task => task.requestedByParticipantId === participantId
+        && goingNowhere(task))
+      .map(task => ({ kind: "request_stalled", priority: ATTENTION_PRIORITY.request_stalled,
+        sourceId: task.taskId,
+        summary: `${task.title} - nobody is working on it` })),
+    ...unansweredQuestions(snapshot, participantId, onlineParticipants),
+  ];
+}
+
+function coordinatorGaps(snapshot) {
+  return (snapshot.workstreams ?? [])
+    .filter(workstream => workstream.state === "open"
+      && workstream.coordinatorSessionId === null)
+    .map(workstream => ({ kind: "coordinator_missing",
+      priority: ATTENTION_PRIORITY.coordinator_missing,
+      sourceId: workstream.workstreamId, summary: workstream.title }));
+}
+
+export function computeAttention(snapshot, { session, participantId, now }) {
+  return [
+    ...directRequests(snapshot, participantId),
+    ...claimConflicts(snapshot, session, now),
+    ...expiredClaims(snapshot, session, now),
+    ...unblockedTasks(snapshot, session, participantId),
+    ...coordinatorGaps(snapshot),
+    ...stalledRequests(snapshot, participantId, now),
+  ].sort((left, right) => left.priority - right.priority
+    || left.sourceId.localeCompare(right.sourceId));
+}
+
+export function createSyncService(ports, sessions) {
+  const { store, clock } = ports;
+
+  /**
+   * Any session may request the full Workspace scope. Peer equality is a
+   * knowledge property: no session receives a reduced
+   * view because of its role. The bounded delta is only the ambient default.
+   */
+  async function sync(input = {}) {
+    // A cursor that is not a cursor answered "nothing new", every time, for as
+    // long as it was held. `eventsSince` compares sequences as strings, so
+    // `not-a-cursor` sorts after every event there has ever been - and an
+    // adapter holding a corrupt one, or an agent that invented one, saw a quiet
+    // workspace rather than a mistake. `"0000000000000001; DROP"` was quietly
+    // taken as the sequence it starts with.
+    if (input.cursor != null) assertCursor(input.cursor);
+    assertScope(input.scope);
+    const workspaceId = input.workspaceId ?? store.workspaceId;
+    const now = clock.now();
+    const located = input.sessionId === undefined
+      ? null
+      : await sessions.locateSession(input.sessionId, workspaceId);
+    const session = located?.record ?? null;
+
+    const durable = await store.snapshot(workspaceId);
+    // A workspace that has not materialised still has a truthful roster: its
+    // sessions live in the ephemeral area. Reading only the durable snapshot
+    // would make a lone session invisible to itself, and would disagree with
+    // what `status` reports from the same state.
+    const snapshot = durable.workspace !== null
+      ? durable
+      : { ...durable,
+        sessions: await store.ephemeral.list("session"),
+        intents: await store.ephemeral.list("intent") };
+    const page = await store.eventsSince(workspaceId, input.cursor ?? null,
+      input.limit ?? DEFAULT_LIMIT);
+    const attention = computeAttention(snapshot, { session,
+      participantId: session?.participantId ?? input.participantId, now });
+
+    const roster = snapshot.sessions.map(item => ({
+      sessionId: item.sessionId,
+      participantId: item.participantId,
+      parentSessionId: item.parentSessionId,
+      harness: item.harness,
+      branch: item.branch ?? null,
+      presence: classifySessionPresence(item, now),
+    }));
+
+    // Solo zero-overhead: one live session, no claims and
+    // no attention means an empty result, not a "nothing to report" banner.
+    const peers = roster.filter(item => item.sessionId !== session?.sessionId
+      && item.presence !== "offline");
+    const solo = peers.length === 0 && attention.length === 0
+      && snapshot.claims.length === 0;
+
+    return {
+      cursor: page.cursor,
+      scope: input.scope === "full" ? "full" : "delta",
+      solo,
+      attention,
+      roster,
+      events: page.events,
+      ...(input.scope === "full" ? { snapshot } : {}),
+    };
+  }
+
+  return { sync };
+}

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

@@ -0,0 +1,238 @@
+import { AccError, EXIT, SCHEMA_VERSION, createId, transitionTask as stepTask, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { ensureMaterialised } from "./materialisation.mjs";
+import { assertKnownParticipants } from "./participants.mjs";
+import { classifySessionPresence } from "./sessions.mjs";
+import { closeRequestReceipt, writeWorkResponse } from "./notify.mjs";
+
+// Dependency completion unblocks tasks deterministically, inside the same
+// transaction that completed the dependency. It must never depend on a model
+// remembering to re-evaluate the graph.
+//
+// Exported because a caller may supply its own task id - an adapter mirroring
+// an external tracker, for instance - and that is the only way a create can
+// close a cycle. Without an explicit id the guard would be unreachable.
+export function wouldCycle(tasks, taskId, dependsOn) {
+  const byId = new Map(tasks.map(task => [task.taskId, task]));
+  const seen = new Set();
+  const stack = [...dependsOn];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === taskId) return true;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    stack.push(...(byId.get(current)?.dependsOn ?? []));
+  }
+  return false;
+}
+
+const blockedBy = (task, byId) => task.dependsOn
+  .filter(id => (byId.get(id)?.state ?? "pending") !== "done");
+
+/**
+ * Write one task inside a transaction the caller already owns.
+ *
+ * Separated so that `acc request` - which creates the task and tells the
+ * recipient about it - can do both as one write. A request that produced a task
+ * and then failed to mention it would leave work addressed to an agent that was
+ * never told, which is worse than no request at all.
+ */
+export function writeTask(tx, { input, session, workspaceId, now, ids }) {
+  const taskId = input.taskId ?? createId("task");
+  const existing = tx.list("task");
+  const dependsOn = input.dependsOn ?? [];
+  for (const dependency of dependsOn) {
+    if (tx.get("task", dependency) === null) {
+      throw new AccError(EXIT.DATA, "a dependency does not exist", { dependency });
+    }
+  }
+  if (wouldCycle(existing, taskId, dependsOn)) {
+    throw new AccError(EXIT.DATA, "the dependency graph would contain a cycle", { taskId });
+  }
+  // A workstream is optional - "finish these tests for me" should not require
+  // inventing a project first - but a named one has to exist, or the task hangs
+  // off nothing and nobody notices.
+  const workstreamId = input.workstreamId ?? null;
+  if (workstreamId !== null && tx.get("workstream", workstreamId) === null) {
+    throw new AccError(EXIT.DATA, "the workstream does not exist", { workstreamId });
+  }
+  const record = validateRecord("task", {
+    schemaVersion: SCHEMA_VERSION,
+    taskId,
+    workstreamId,
+    workspaceId,
+    title: input.title,
+    detail: input.detail ?? null,
+    state: blockedBy({ dependsOn }, new Map(existing.map(task => [task.taskId, task])))
+      .length > 0 ? "blocked" : "pending",
+    // Addressed to a participant, so the request survives that agent closing
+    // its terminal. Whoever picks it up is recorded separately.
+    assigneeParticipantId: input.assigneeParticipantId ?? null,
+    assigneeSessionId: null,
+    requestedByParticipantId: input.requestedByParticipantId ?? null,
+    dependsOn,
+    acceptance: input.acceptance ?? [],
+    createdAt: now,
+  });
+  tx.put("task", taskId, record);
+  tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+    actorSessionId: session.sessionId, type: "task.created", occurredAt: now,
+    payload: { taskId, state: record.state,
+      assigneeParticipantId: record.assigneeParticipantId } });
+  return record;
+}
+
+export function createTaskService(ports, workstreams) {
+  const { store, clock, ids } = ports;
+
+  async function createTask(input) {
+    const session = await workstreams.requireOpenSession(input, "create a task");
+    const workspaceId = session.workspaceId;
+    await ensureMaterialised(ports, { workspaceId, descriptor: input.descriptor,
+      reason: "durable_object" });
+    // The same rule as addressing a message. `acc task --assignee physcis` was
+    // accepted and left work `pending` for a participant nobody has ever been:
+    // invisible to every roster, raising `task_unblocked` for nobody, and not
+    // even stalled, since nothing was waiting on it that could be told.
+    if (input.assigneeParticipantId != null) {
+      await assertKnownParticipants(store, workspaceId, [input.assigneeParticipantId]);
+    }
+    const now = clock.now();
+    let record = null;
+    await store.transaction(async tx => {
+      record = writeTask(tx, { input, session, workspaceId, now, ids });
+    // `writeTask` reads and writes on this handle, so its kinds are ours.
+    }, { kinds: ["session", "task", "workstream"] });
+    return record;
+  }
+
+  async function claimTask(input) {
+    const session = await workstreams.requireOpenSession(input, "claim a task");
+    const now = clock.now();
+    let record = null;
+    await store.transaction(async tx => {
+      const existing = tx.get("task", input.taskId);
+      if (existing === null) {
+        throw new AccError(EXIT.DATA, "the task does not exist", { taskId: input.taskId });
+      }
+      if (existing.assigneeSessionId !== null
+        && existing.assigneeSessionId !== session.sessionId) {
+        // A holder that is gone is not a holder. Closing a session hands its
+        // work back, so this is the crash case: no session end ever arrived and
+        // presence has decayed. Staleness alone does not release it - that is
+        // the same rule claims follow, because an idle agent may be thinking
+        // rather than dead - but it can be taken over deliberately.
+        const holder = tx.get("session", existing.assigneeSessionId);
+        const presence = holder === null
+          ? "offline"
+          : classifySessionPresence(holder, now);
+        if (presence === "online") {
+          throw new AccError(EXIT.CONFLICT, "the task already has an assignee",
+            { taskId: input.taskId, assigneeSessionId: existing.assigneeSessionId });
+        }
+        if (presence === "stale" && input.force !== true) {
+          throw new AccError(EXIT.CONFLICT,
+            "the task is held by a session that has gone quiet; take it with force",
+            { taskId: input.taskId, assigneeSessionId: existing.assigneeSessionId,
+              presence });
+        }
+      }
+      // Work addressed to one participant is not picked up by another. Taking
+      // an unaddressed task is open to anyone, which is what makes a request
+      // with no named recipient a request to the room.
+      if (existing.assigneeParticipantId !== null
+        && existing.assigneeParticipantId !== session.participantId) {
+        throw new AccError(EXIT.CONFLICT, "the task is addressed to another participant",
+          { taskId: input.taskId,
+            assigneeParticipantId: existing.assigneeParticipantId });
+      }
+      record = { ...existing, assigneeSessionId: session.sessionId,
+        assigneeParticipantId: existing.assigneeParticipantId ?? session.participantId,
+        state: stepTask(existing.state, "in_progress") };
+      // Whoever asked is waiting on an answer, and "someone is on it" is one.
+      writeWorkResponse(tx, { task: record, actor: session,
+        workspaceId: session.workspaceId, now, ids, outcome: "accepted" });
+      tx.put("task", input.taskId, record, tx.generationOf("task", input.taskId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+        type: "task.claimed", occurredAt: now, payload: { taskId: input.taskId } });
+    }, { kinds: ["message", "receipt", "session", "task"] });
+    return record;
+  }
+
+  async function transitionTask(input) {
+    const session = await workstreams.requireOpenSession(input, "transition a task");
+    const now = clock.now();
+    let record = null;
+    await store.transaction(async tx => {
+      const existing = tx.get("task", input.taskId);
+      if (existing === null) {
+        throw new AccError(EXIT.DATA, "the task does not exist", { taskId: input.taskId });
+      }
+      record = { ...existing, state: stepTask(existing.state, input.state) };
+      tx.put("task", input.taskId, record, tx.generationOf("task", input.taskId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+        type: "task.transitioned", occurredAt: now,
+        payload: { taskId: input.taskId, state: record.state } });
+
+      if (record.state === "done" || record.state === "review") {
+        writeWorkResponse(tx, { task: record, actor: session,
+          workspaceId: session.workspaceId, now, ids, outcome: record.state });
+      }
+      // Doing the work answers the request that asked for it.
+      if (record.state === "done") closeRequestReceipt(tx, { task: record, actor: session, now, ids });
+      if (record.state !== "done") return;
+      // Unblock dependents here, in the same transaction, so the graph is
+      // never left in a state that needs someone to notice it later.
+      const byId = new Map(tx.list("task").map(task => [task.taskId, task]));
+      byId.set(record.taskId, record);
+      for (const dependent of byId.values()) {
+        if (dependent.state !== "blocked") continue;
+        if (blockedBy(dependent, byId).length > 0) continue;
+        const unblocked = { ...dependent, state: "pending" };
+        tx.put("task", dependent.taskId, unblocked,
+          tx.generationOf("task", dependent.taskId));
+        tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+          workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+          type: "task.unblocked", occurredAt: now, payload: { taskId: dependent.taskId } });
+      }
+    }, { kinds: ["message", "receipt", "task"] });
+    return record;
+  }
+
+  /**
+   * Refuse a request, with a reason.
+   *
+   * The task returns to unclaimed rather than being deleted: the work is still
+   * wanted, it is just not this agent's. Leaving a request pending forever was
+   * the only way to say no, and it looks identical to not having read it.
+   */
+  async function declineTask(input) {
+    const session = await workstreams.requireOpenSession(input, "decline a task");
+    const now = clock.now();
+    let record = null;
+    await store.transaction(async tx => {
+      const existing = tx.get("task", input.taskId);
+      if (existing === null) {
+        throw new AccError(EXIT.DATA, "the task does not exist", { taskId: input.taskId });
+      }
+      record = { ...existing, assigneeParticipantId: null, assigneeSessionId: null,
+        state: "pending" };
+      tx.put("task", input.taskId, record, tx.generationOf("task", input.taskId));
+      writeWorkResponse(tx, { task: existing, actor: session,
+        workspaceId: session.workspaceId, now, ids, outcome: "declined",
+        reason: input.reason ?? null });
+      // Refusing is also an answer, so the request stops demanding one.
+      closeRequestReceipt(tx, { task: existing, actor: session, now, ids });
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+        type: "task.declined", occurredAt: now,
+        payload: { taskId: input.taskId, reason: input.reason ?? null } });
+    }, { kinds: ["message", "receipt", "task"] });
+    return record;
+  }
+
+  return { createTask, claimTask, transitionTask, declineTask };
+}

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

@@ -0,0 +1,109 @@
+import { AccError, EXIT, SCHEMA_VERSION, createId, validateRecord }
+  from "@agents-can-communicate/protocol";
+
+import { ensureMaterialised } from "./materialisation.mjs";
+import { classifySessionPresence } from "./sessions.mjs";
+
+// A workstream groups related collaboration. It may have zero or one
+// coordinator lease, and the coordinator plans - it is never the transport,
+// the durable owner, or an information gatekeeper.
+export function createWorkstreamService(ports, sessions) {
+  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 createWorkstream(input) {
+    const session = await requireOpenSession(input, "create a workstream");
+    const workspaceId = session.workspaceId;
+    await ensureMaterialised(ports, { workspaceId, descriptor: input.descriptor,
+      reason: "durable_object" });
+    const now = clock.now();
+    const workstreamId = createId("workstream");
+    const record = validateRecord("workstream", {
+      schemaVersion: SCHEMA_VERSION,
+      workstreamId,
+      workspaceId,
+      title: input.title,
+      objective: input.objective,
+      // A workstream never acquires a coordinator merely by being created.
+      coordinatorSessionId: null,
+      state: "open",
+      createdAt: now,
+    });
+    await store.transaction(async tx => {
+      tx.put("workstream", workstreamId, record);
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"), workspaceId,
+        actorSessionId: session.sessionId, type: "workstream.created", occurredAt: now,
+        payload: { workstreamId } });
+    }, { kinds: ["workstream"] });
+    return record;
+  }
+
+  async function acquireCoordinator(input) {
+    const session = await requireOpenSession(input, "coordinate");
+    const now = clock.now();
+    const snapshot = await store.snapshot(session.workspaceId,
+      { kinds: ["session", "workstream"] });
+    let record = null;
+    await store.transaction(async tx => {
+      const existing = tx.get("workstream", input.workstreamId);
+      if (existing === null) {
+        throw new AccError(EXIT.CONFLICT, "the workstream does not exist",
+          { workstreamId: input.workstreamId });
+      }
+      const held = existing.coordinatorSessionId;
+      if (held !== null && held !== session.sessionId) {
+        const holder = snapshot.sessions.find(item => item.sessionId === held);
+        const presence = holder === undefined ? "offline"
+          : classifySessionPresence(holder, now);
+        // A coordinator lease is replaced only when the holder is genuinely
+        // gone or policy says so - not because a peer would like the role.
+        if (presence !== "offline" && input.authority !== "human"
+          && input.authority !== "policy") {
+          throw new AccError(EXIT.CONFLICT, "the workstream already has a coordinator",
+            { workstreamId: input.workstreamId, coordinatorSessionId: held,
+              coordinatorPresence: presence });
+        }
+      }
+      record = { ...existing, coordinatorSessionId: session.sessionId };
+      tx.put("workstream", input.workstreamId, record,
+        tx.generationOf("workstream", input.workstreamId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+        type: "workstream.coordinator_acquired", occurredAt: now,
+        payload: { workstreamId: input.workstreamId, replaced: held } });
+    }, { kinds: ["workstream"] });
+    return record;
+  }
+
+  async function releaseCoordinator(input) {
+    const session = await requireOpenSession(input, "release coordination");
+    const now = clock.now();
+    let record = null;
+    await store.transaction(async tx => {
+      const existing = tx.get("workstream", input.workstreamId);
+      if (existing === null || existing.coordinatorSessionId !== session.sessionId) {
+        throw new AccError(EXIT.CONFLICT, "only the coordinator may release the lease",
+          { workstreamId: input.workstreamId });
+      }
+      record = { ...existing, coordinatorSessionId: null };
+      tx.put("workstream", input.workstreamId, record,
+        tx.generationOf("workstream", input.workstreamId));
+      tx.append({ schemaVersion: SCHEMA_VERSION, eventId: ids.next("event"),
+        workspaceId: session.workspaceId, actorSessionId: session.sessionId,
+        type: "workstream.coordinator_released", occurredAt: now,
+        payload: { workstreamId: input.workstreamId } });
+    }, { kinds: ["workstream"] });
+    return record;
+  }
+
+  return { createWorkstream, acquireCoordinator, releaseCoordinator, requireOpenSession };
+}

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@agents-can-communicate/hook-runner",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/runner.mjs"
+  },
+  "files": [
+    "src/"
+  ]
+}