agents-can-communicate 0.3.1 → 0.4.0

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

@@ -21,6 +21,9 @@ const data = (message, details) => {
 };
 
 export function assertMessageSemantics(message) {
+  if (message.decisionChange !== undefined && message.kind !== "decision") {
+    data("only a decision can replace or withdraw decisions", { kind: message.kind });
+  }
   const room = message.toParticipantIds.length === 0;
   if (room && !["note", "decision", "handoff"].includes(message.kind)) {
     data(`a room message cannot have kind ${message.kind}`, { kind: message.kind });

package/node_modules/@agents-can-communicate/protocol/src/decision-changes.mjs

@@ -0,0 +1,15 @@
+import { id, invalid, listOf, oneOf, plainObject } from "./fields.mjs";
+
+export function assertDecisionChange(value, field = "decisionChange") {
+  plainObject(value, field);
+  for (const key of Object.keys(value)) {
+    if (!["action", "messageIds"].includes(key)) invalid(`${field}.${key}`, "is not a known field", value[key]);
+  }
+  oneOf("replace", "withdraw")(value.action, `${field}.action`);
+  listOf(id)(value.messageIds, `${field}.messageIds`);
+  if (value.messageIds.length < 1 || value.messageIds.length > 16
+    || new Set(value.messageIds).size !== value.messageIds.length) {
+    invalid(`${field}.messageIds`, "requires 1 to 16 unique decision message ids", value.messageIds);
+  }
+  return value;
+}

package/node_modules/@agents-can-communicate/protocol/src/index.mjs

@@ -2,7 +2,8 @@
 export { AccError, EXIT, isAccError } from "./errors.mjs";
 export { assertPortableId, createId } from "./ids.mjs";
 export { ENVELOPE_VERSION, failure, ok } from "./envelopes.mjs";
-export { RECORD_KINDS, SCHEMA_VERSION, validateRecord } from "./schema.mjs";
+export { CLAIM_ENFORCEMENTS, CLAIM_MODES, HANDOFF_STATUSES, INTENT_MODES,
+  INTENT_STATES, RECORD_KINDS, SCHEMA_VERSION, validateRecord } from "./schema.mjs";
 export { GENERIC_MESSAGE_KINDS, MESSAGE_KINDS, OBLIGATIONS, VALID_OBLIGATIONS,
   assertMessageSemantics }
   from "./conversations.mjs";
@@ -10,3 +11,4 @@ export { CONFIG_FILENAME, CONFIG_SCHEMA_VERSION, RUNTIME_KEYS, defaultProjectCon
   validateProjectConfig } from "./config.mjs";
 export { RECEIPT_STATES, advanceReceipt } from "./states.mjs";
 export { assertMatchableResource, normaliseResource } from "./resources.mjs";
+export { assertDecisionChange } from "./decision-changes.mjs";

package/node_modules/@agents-can-communicate/protocol/src/schema.mjs

@@ -1,10 +1,19 @@
 import { assertMessageSemantics, MESSAGE_KINDS, OBLIGATIONS } from "./conversations.mjs";
+import { assertDecisionChange } from "./decision-changes.mjs";
 import { AccError, EXIT } from "./errors.mjs";
 import { id, invalid, listOf, nullable, oneOf, optional, plainObject, positiveInteger,
   resourceUri, sequence, text, timestamp } from "./fields.mjs";
 
 export const SCHEMA_VERSION = 3;
 
+// Shared with CLI help so advertised choices are the ones durable records accept.
+export const INTENT_MODES = Object.freeze(["observe", "explore", "edit", "review",
+  "coordinate", "wait"]);
+export const INTENT_STATES = Object.freeze(["active", "blocked", "waiting", "done"]);
+export const CLAIM_MODES = Object.freeze(["shared", "exclusive"]);
+export const CLAIM_ENFORCEMENTS = Object.freeze(["advisory", "guarded"]);
+export const HANDOFF_STATUSES = Object.freeze(["complete", "partial", "blocked"]);
+
 const line = text();
 const prose = text({ max: 4000, multiline: true });
 const summary = text({ max: 280 });
@@ -47,7 +56,7 @@ const artifactRef = (value, field) => {
 };
 
 const handoffPayload = (value, field) => closedObject(value, field, {
-  status: oneOf("complete", "partial", "blocked"),
+  status: oneOf(...HANDOFF_STATUSES),
   completed: listOf(line),
   remaining: listOf(line),
   blockers: listOf(line),
@@ -90,19 +99,19 @@ const DURABLE_RECORDS = Object.freeze({
     heartbeatCadenceMs: positiveInteger, startedAt: timestamp, heartbeatAt: timestamp },
 
   intent: { sessionId: id, workspaceId: id, summary,
-    mode: oneOf("observe", "explore", "edit", "review", "coordinate", "wait"),
+    mode: oneOf(...INTENT_MODES),
     resourceHints: listOf(resourceUri),
-    state: oneOf("active", "blocked", "waiting", "done"), updatedAt: timestamp },
+    state: oneOf(...INTENT_STATES), updatedAt: timestamp },
 
   claim: { claimId: id, workspaceId: id, ownerSessionId: id, resource: resourceUri,
-    mode: oneOf("shared", "exclusive"), enforcement: oneOf("advisory", "guarded"),
+    mode: oneOf(...CLAIM_MODES), enforcement: oneOf(...CLAIM_ENFORCEMENTS),
     reason: line, acquiredAt: timestamp, expiresAt: timestamp, generation: id },
 
   message: { messageId: id, threadId: id, clientMessageId: id, workspaceId: id,
     fromParticipantId: id, fromSessionId: id, toParticipantIds: listOf(id),
     kind: oneOf(...MESSAGE_KINDS), obligation: oneOf(...OBLIGATIONS),
     subject: line, body: prose, inReplyTo: nullable(id), artifacts: listOf(artifactRef),
-    handoff: nullable(handoffPayload), sentAt: timestamp },
+    handoff: nullable(handoffPayload), decisionChange: optional(assertDecisionChange), sentAt: timestamp },
 
   receipt: { messageId: id, workspaceId: id, recipientParticipantId: id,
     state: receiptState, updatedAt: timestamp },

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/src/atomic-json.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
+import { assertPublicationDeadline } from "./deadline.mjs";
 import { assertManagedDirectory, ensureManagedDirectory } from "./safe-directory.mjs";
 import { readRegularNoFollow } from "./safe-file.mjs";
 
@@ -62,7 +63,8 @@ async function replaceHandleBytes(handle, bytes) {
  *
  * @returns {Promise<"published" | "already_published">}
  */
-export async function publishAtomic(destination, bytes, { root, tmpDir, replace = false }) {
+export async function publishAtomic(destination, bytes, { root, tmpDir, replace = false, deadlineAt }) {
+  assertPublicationDeadline(deadlineAt);
   const destinationDir = path.dirname(destination);
   await Promise.all([
     ensureManagedDirectory(root, tmpDir),
@@ -87,12 +89,14 @@ export async function publishAtomic(destination, bytes, { root, tmpDir, replace
     if (replace) {
       await handle.close();
       handle = null;
+      assertPublicationDeadline(deadlineAt);
       await rename(temporary, destination);
       await syncDirectory(destinationDir);
       return "published";
     }
 
     try {
+      assertPublicationDeadline(deadlineAt);
       await link(temporary, destination);
       stageAcceptedBytes = true;
       await syncDirectory(destinationDir);

package/node_modules/@agents-can-communicate/storage-filesystem/src/deadline.mjs

@@ -0,0 +1,7 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+export function assertPublicationDeadline(deadlineAt) {
+  if (deadlineAt !== undefined && Date.now() >= deadlineAt) {
+    throw new AccError(EXIT.CONFLICT, "operation deadline expired before publication", {});
+  }
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/index.mjs

@@ -2,3 +2,5 @@
 export { openFilesystemStore, storePaths, ZERO_CURSOR } from "./store.mjs";
 export { diagnoseFilesystemStore, repairFilesystemStore } from "./recovery.mjs";
 export { readStoreIdentity, requireStoreIdentity, STORE_VERSION } from "./identity.mjs";
+export { withWriterMutex } from "./writer-mutex.mjs";
+export { readSessionRecord } from "./session-read.mjs";

package/node_modules/@agents-can-communicate/storage-filesystem/src/session-read.mjs

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { assertPortableId, validateRecord } from "@agents-can-communicate/protocol";
+import { readJsonIfPresent } from "./atomic-json.mjs";
+import { requireStoreIdentity } from "./identity.mjs";
+import { assertStateBinding, statePath } from "./record-id.mjs";
+import { ephemeralIsDeleted, stateGenerationIsDeleted } from "./retention.mjs";
+import { storePaths } from "./store.mjs";
+
+/** Inspect ownership without opening, creating, recovering, or locking the store. */
+export async function readSessionRecord({ root, workspaceId, sessionId }) {
+  assertPortableId(sessionId, "session id");
+  const paths = storePaths(root);
+  await requireStoreIdentity(paths, { workspaceId, create: false });
+  const file = statePath(paths, "session", sessionId);
+  const durable = await readJsonIfPresent(file, root);
+  if (durable !== null) {
+    const envelope = assertStateBinding(durable.value, "session", sessionId, file);
+    if (!await stateGenerationIsDeleted(paths, root, "session", sessionId, envelope.generation)) {
+      return validateRecord("session", envelope.record);
+    }
+  }
+  const ephemeral = await readJsonIfPresent(path.join(paths.ephemeral, "session", `${sessionId}.json`), root);
+  if (ephemeral === null || await ephemeralIsDeleted(paths, root, "session", sessionId)) return null;
+  return validateRecord("session", ephemeral.value);
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/store.mjs

@@ -7,6 +7,7 @@ import { AccError, EXIT, assertPortableId, validateRecord }
 import { encode, listDirectoryEntries, listJsonFiles, publishAtomic, readJsonIfPresent,
   retainFile } from "./atomic-json.mjs";
 import { initialiseActiveJournal } from "./active-journal.mjs";
+import { assertPublicationDeadline } from "./deadline.mjs";
 import { requireStoreIdentity } from "./identity.mjs";
 import { journalEntry, readJournalCeiling, readOpenJournals, rollForward, writeJournalEntry }
   from "./journal.mjs";
@@ -32,13 +33,6 @@ const DIRECTORIES = ["state", "events", "journal", "locks", "ephemeral", "retain
 
 const pad = value => String(value).padStart(SEQUENCE_WIDTH, "0");
 
-function assertBeforePublication(deadlineAt) {
-  if (deadlineAt !== undefined && Date.now() >= deadlineAt) {
-    throw new AccError(EXIT.CONFLICT,
-      "transaction deadline expired before durable publication", {});
-  }
-}
-
 export function storePaths(root) {
   return Object.freeze(Object.fromEntries([["root", root],
     ...DIRECTORIES.map(name => [name, path.join(root, name)])]));
@@ -77,7 +71,9 @@ async function nextSequence(paths, root) {
   return last === undefined ? 1 : Number(path.basename(last, ".json")) + 1;
 }
 
-export async function openFilesystemStore({ root, clock, ids, workspaceId, failAt }) {
+export async function openFilesystemStore({ root, clock, ids, workspaceId, failAt,
+  deadlineAt: storeDeadline }) {
+  assertPublicationDeadline(storeDeadline);
   const paths = storePaths(root);
   // The caller owns the root path, so its ancestors are created here. Inside the
   // root, containment rules apply and each level is created individually so a
@@ -100,7 +96,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
   async function recoverOpenJournals() {
     const open = await readOpenJournals(paths, root);
     if (open.length === 0) return [];
-    return withWriterMutex(paths, { root, tmpDir: paths.tmp, clock }, async () => {
+    return withWriterMutex(paths, { root, tmpDir: paths.tmp, clock, deadlineAt: storeDeadline }, async () => {
       const completed = [];
       for (const entry of await readOpenJournals(paths, root)) {
         completed.push(...await rollForward(paths, { root, tmpDir: paths.tmp, clock }, entry));
@@ -125,6 +121,8 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
    * Declaring nothing reads everything, which is what this always did.
    */
   async function transaction(callback, { kinds, deadlineAt } = {}) {
+    // A caller may tighten this invocation's budget, never extend it.
+    deadlineAt = Math.min(deadlineAt ?? Infinity, storeDeadline ?? Infinity);
     const wanted = kinds === undefined ? null : new Set(kinds);
     const declared = kind => {
       if (wanted !== null && !wanted.has(kind)) {
@@ -135,7 +133,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       return kind;
     };
     return withWriterMutex(paths, { ...publishOptions, deadlineAt }, async () => {
-      assertBeforePublication(deadlineAt);
+      assertPublicationDeadline(deadlineAt);
       // Reads are loaded once per transaction so get, list, and the generation
       // that put() compares against all describe the same instant.
       const loaded = await loadAllState(paths, root, wanted);
@@ -224,14 +222,13 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       ];
       if (publications.length === 0) return result;
 
-      // Cancellation is safe up to this point: nothing durable has decided the
-      // transaction. Once the journal write starts, recovery must finish it and
-      // the caller waits for that atomic outcome instead of reporting a false
-      // timeout while publication continues in the background.
-      assertBeforePublication(deadlineAt);
+      // Preparation is still cancellable. The active journal's atomic
+      // publication decides the write; roll-forward must then finish even if
+      // this invocation expires, so its publication options carry no deadline.
+      assertPublicationDeadline(deadlineAt);
       const entry = journalEntry(ids.next("transaction"), firstSequence, publications,
         clock.now());
-      await writeJournalEntry(paths, publishOptions, entry);
+      await writeJournalEntry(paths, { ...publishOptions, deadlineAt }, entry);
       await failAt?.("after-journal");
       await rollForward(paths, publishOptions, entry);
       return result;
@@ -308,29 +305,35 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
     },
     async put(kind, id, record) {
       validateRecord(kind, record);
-      return withWriterMutex(paths, publishOptions, async () => {
+      return withWriterMutex(paths, { ...publishOptions, deadlineAt: storeDeadline }, async () => {
         await publishAtomic(ephemeralPath(kind, id), encode(record),
-          { root, tmpDir: paths.tmp, replace: true });
+          { root, tmpDir: paths.tmp, replace: true, deadlineAt: storeDeadline });
+        // Once record bytes are accepted, finish the same logical publication.
         await markEphemeral(paths, publishOptions, kind, id, "present");
         return record;
       });
     },
-    async update(kind, id, updater) {
-      return withWriterMutex(paths, publishOptions, async () => {
+    async update(kind, id, updater, { deadlineAt = storeDeadline } = {}) {
+      deadlineAt = Math.min(deadlineAt ?? Infinity, storeDeadline ?? Infinity);
+      return withWriterMutex(paths, { ...publishOptions, deadlineAt }, async () => {
         const next = await updater(await readEphemeral(kind, id));
         if (next === null) return null;
         validateRecord(kind, next);
+        assertPublicationDeadline(deadlineAt);
         await publishAtomic(ephemeralPath(kind, id), encode(next),
-          { root, tmpDir: paths.tmp, replace: true });
+          { root, tmpDir: paths.tmp, replace: true, deadlineAt });
         await markEphemeral(paths, publishOptions, kind, id, "present");
         return next;
       });
     },
-    async delete(kind, id) {
-      return withWriterMutex(paths, publishOptions, async () => {
-        if (await readEphemeral(kind, id) === null) return null;
+    async delete(kind, id, guard = () => true) {
+      return withWriterMutex(paths, { ...publishOptions, deadlineAt: storeDeadline }, async () => {
+        // Decide and delete under the same lock; a caller may be retiring an
+        // old generation while its replacement is waiting to write this id.
+        const current = await readEphemeral(kind, id);
+        if (current === null || !await guard(current)) return null;
         await retainFile(ephemeralPath(kind, id), { root });
-        await markEphemeral(paths, publishOptions, kind, id, "deleted");
+        await markEphemeral(paths, { ...publishOptions, deadlineAt: storeDeadline }, kind, id, "deleted");
         return null;
       });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [
@@ -60,6 +60,7 @@
     "docs/RELEASING.md",
     "docs/SECURITY_MODEL.md",
     "docs/TROUBLESHOOTING.md",
+    "docs/UPGRADING.md",
     "docs/WHY_ACC.md",
     "docs/index.md",
     "SECURITY.md",