agents-can-communicate 0.1.18 → 0.2.0

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

@@ -1,14 +1,19 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 
-import { AccError, EXIT, validateRecord } from "@agents-can-communicate/protocol";
+import { AccError, EXIT, assertPortableId, validateRecord }
+  from "@agents-can-communicate/protocol";
 
 import { encode, listDirectoryEntries, listJsonFiles, publishAtomic, readJsonIfPresent,
-  removeIfPresent } from "./atomic-json.mjs";
+  retainFile } from "./atomic-json.mjs";
+import { initialiseActiveJournal } from "./active-journal.mjs";
 import { requireStoreIdentity } from "./identity.mjs";
-import { journalEntry, readOpenJournals, rollForward, writeJournalEntry } from "./journal.mjs";
+import { journalEntry, readJournalCeiling, readOpenJournals, rollForward, writeJournalEntry }
+  from "./journal.mjs";
 import { assertEventBinding, assertStateBinding, eventPath, stateEnvelope, statePath }
   from "./record-id.mjs";
+import { ephemeralIsDeleted, markEphemeral, stateDeletionPublication,
+  stateGenerationIsDeleted } from "./retention.mjs";
 import { ensureManagedDirectory } from "./safe-directory.mjs";
 import { withWriterMutex } from "./writer-mutex.mjs";
 
@@ -23,10 +28,17 @@ export const ZERO_CURSOR = "0".repeat(SEQUENCE_WIDTH);
 // corrupt record, so nothing ever had a reason to put one aside. An empty
 // directory that reads as a feature is the same mistake as an attention kind
 // with no rule behind it. If quarantining is ever built, it comes back with it.
-const DIRECTORIES = ["state", "events", "journal", "locks", "ephemeral", "tmp"];
+const DIRECTORIES = ["state", "events", "journal", "locks", "ephemeral", "retained", "tmp"];
 
 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)])]));
@@ -37,8 +49,12 @@ async function listState(paths, root, kind) {
   for (const filePath of await listJsonFiles(path.join(paths.state, kind), { root })) {
     const found = await readJsonIfPresent(filePath, root);
     if (found === null) continue;
-    envelopes.push(assertStateBinding(found.value, kind,
-      path.basename(filePath, ".json"), filePath));
+    const envelope = assertStateBinding(found.value, kind,
+      path.basename(filePath, ".json"), filePath);
+    if (await stateGenerationIsDeleted(paths, root, kind, envelope.id,
+      envelope.generation)) continue;
+    validateRecord(kind, envelope.record);
+    envelopes.push(envelope);
   }
   return envelopes;
 }
@@ -67,11 +83,12 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
   // root, containment rules apply and each level is created individually so a
   // symlinked ancestor cannot be created past.
   await mkdir(root, { recursive: true });
-  for (const name of DIRECTORIES) await ensureManagedDirectory(root, paths[name]);
   // Identity is settled before any read or write. Adopting a directory that
   // already belongs to another workspace is the failure this fails closed on.
   await requireStoreIdentity(paths, { workspaceId, clock });
+  for (const name of DIRECTORIES) await ensureManagedDirectory(root, paths[name]);
   const publishOptions = { root, tmpDir: paths.tmp, clock, failAt };
+  await initialiseActiveJournal(paths, publishOptions);
 
   // Any journal left behind by a crashed writer is completed before the store
   // serves a single read, so callers never observe a half-published
@@ -107,7 +124,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
    * these transactions make reads as "nothing conflicts" when it finds nothing.
    * Declaring nothing reads everything, which is what this always did.
    */
-  async function transaction(callback, { kinds } = {}) {
+  async function transaction(callback, { kinds, deadlineAt } = {}) {
     const wanted = kinds === undefined ? null : new Set(kinds);
     const declared = kind => {
       if (wanted !== null && !wanted.has(kind)) {
@@ -117,7 +134,8 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       }
       return kind;
     };
-    return withWriterMutex(paths, publishOptions, async () => {
+    return withWriterMutex(paths, { ...publishOptions, deadlineAt }, async () => {
+      assertBeforePublication(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);
@@ -171,7 +189,9 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
             throw new AccError(EXIT.CONFLICT, `${kind} ${id} changed under this transaction`,
               { kind, id, expectedGeneration, actualGeneration: actual });
           }
-          staged.set(key, { kind, id, removed: true });
+          const persisted = loaded.get(key);
+          if (persisted === undefined) staged.delete(key);
+          else staged.set(key, { kind, id, generation: persisted.generation, removed: true });
         },
         append(event) {
           const stamped = { ...event, sequence: pad(sequence) };
@@ -194,7 +214,8 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
           replace: false,
         })),
         ...[...staged.values()].map(entry => (entry.removed === true
-          ? { path: path.relative(root, statePath(paths, entry.kind, entry.id)), remove: true }
+          ? stateDeletionPublication(paths, root, entry.kind, entry.id, entry.generation,
+            statePath(paths, entry.kind, entry.id))
           : {
             path: path.relative(root, statePath(paths, entry.kind, entry.id)),
             bytes: encode(stateEnvelope(entry.kind, entry.id, entry.generation, entry.record)),
@@ -203,6 +224,11 @@ 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);
       const entry = journalEntry(ids.next("transaction"), firstSequence, publications,
         clock.now());
       await writeJournalEntry(paths, publishOptions, entry);
@@ -217,7 +243,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
     // An open journal marks a transaction that is decided but not fully
     // published. Bounding the page below its first sequence is what keeps a
     // partially published transaction invisible to every reader.
-    const ceiling = (await readOpenJournals(paths, root)).at(0)?.firstSequence ?? null;
+    const ceiling = await readJournalCeiling(paths, root);
     const events = [];
     for (const filePath of await listJsonFiles(paths.events, { root })) {
       const sequence = path.basename(filePath, ".json");
@@ -225,7 +251,7 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       if (ceiling !== null && sequence >= ceiling) break;
       const found = await readJsonIfPresent(filePath, root);
       if (found === null) continue;
-      const event = assertEventBinding(found.value, filePath);
+      const event = validateRecord("event", assertEventBinding(found.value, filePath));
       if (event.workspaceId !== workspace) continue;
       events.push(event);
       if (events.length === limit) break;
@@ -255,49 +281,65 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       participants: await of("participant"),
       sessions: await of("session"),
       intents: await of("intent"),
-      workstreams: await of("workstream"),
-      tasks: await of("task"),
       claims: await of("claim"),
       messages: await of("message"),
       receipts: await of("receipt"),
-      decisions: await of("decision"),
-      handoffs: await of("handoff"),
     };
   }
   // Ephemeral records are published by replace and never journalled: they carry
-  // no history, append no events, and are expected to disappear.
-  const ephemeralPath = (kind, id) => path.join(paths.ephemeral, kind, `${id}.json`);
+  // no durable history and append no events. Deletion is represented by a
+  // retained marker because Node cannot unlink safely through a directory fd.
+  const ephemeralDirectory = kind => {
+    assertPortableId(kind, "ephemeral record kind");
+    return path.join(paths.ephemeral, kind);
+  };
+  const ephemeralPath = (kind, id) => {
+    assertPortableId(id, "ephemeral record id");
+    return path.join(ephemeralDirectory(kind), `${id}.json`);
+  };
+  const readEphemeral = async (kind, id) => {
+    const found = await readJsonIfPresent(ephemeralPath(kind, id), root);
+    if (found === null || await ephemeralIsDeleted(paths, root, kind, id)) return null;
+    return validateRecord(kind, found.value);
+  };
   const ephemeral = Object.freeze({
     async get(kind, id) {
-      return (await readJsonIfPresent(ephemeralPath(kind, id), root))?.value ?? null;
+      return readEphemeral(kind, id);
     },
     async put(kind, id, record) {
+      validateRecord(kind, record);
       return withWriterMutex(paths, publishOptions, async () => {
         await publishAtomic(ephemeralPath(kind, id), encode(record),
           { root, tmpDir: paths.tmp, replace: true });
+        await markEphemeral(paths, publishOptions, kind, id, "present");
         return record;
       });
     },
     async update(kind, id, updater) {
       return withWriterMutex(paths, publishOptions, async () => {
-        const found = await readJsonIfPresent(ephemeralPath(kind, id), root);
-        const next = await updater(found?.value ?? null);
+        const next = await updater(await readEphemeral(kind, id));
         if (next === null) return null;
         validateRecord(kind, next);
         await publishAtomic(ephemeralPath(kind, id), encode(next),
           { root, tmpDir: paths.tmp, replace: true });
+        await markEphemeral(paths, publishOptions, kind, id, "present");
         return next;
       });
     },
     async delete(kind, id) {
-      return withWriterMutex(paths, publishOptions,
-        async () => removeIfPresent(ephemeralPath(kind, id)));
+      return withWriterMutex(paths, publishOptions, async () => {
+        if (await readEphemeral(kind, id) === null) return null;
+        await retainFile(ephemeralPath(kind, id), { root });
+        await markEphemeral(paths, publishOptions, kind, id, "deleted");
+        return null;
+      });
     },
     async list(kind) {
       const records = [];
-      for (const filePath of await listJsonFiles(path.join(paths.ephemeral, kind), { root })) {
+      for (const filePath of await listJsonFiles(ephemeralDirectory(kind), { root })) {
         const found = await readJsonIfPresent(filePath, root);
-        if (found !== null) records.push(found.value);
+        if (found !== null && !await ephemeralIsDeleted(paths, root, kind,
+          path.basename(filePath, ".json"))) records.push(validateRecord(kind, found.value));
       }
       return records;
     },

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

@@ -1,21 +1,23 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, rm } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import { performance } from "node:perf_hooks";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
-import { encode, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
+import { encode, readJsonIfPresent } from "./atomic-json.mjs";
 import { ensureManagedDirectory } from "./safe-directory.mjs";
+import { withRegularNoFollow } from "./safe-file.mjs";
 
 const STALE_MS = 60_000;
 const ACQUIRE_TIMEOUT_MS = 2_500;
 const OWNER = "owner.json";
 const sleepFor = duration => new Promise(resolve => { setTimeout(resolve, duration); });
 
-// Directory creation is the atomic primitive: mkdir either creates or fails
-// with EEXIST, with no window in between. Ported from the reconciled
-// prototype's repair mutex and reused here as the per-workspace writer lock.
+// A fully prepared directory is the atomic primitive. Publishing the owner
+// with the directory means a crash can leave an unused candidate, but never an
+// ownerless canonical lock that blocks every later writer.
 function defaultPidIsAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -25,13 +27,59 @@ function defaultPidIsAlive(pid) {
   }
 }
 
+async function syncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function prepareCandidate(paths, root, owner) {
+  const identity = createHash("sha256").update(owner.token).digest("hex");
+  const candidate = path.join(paths.locks, `writer.candidate-${identity}.lock`);
+  await mkdir(candidate);
+  try {
+    await withRegularNoFollow(path.join(candidate, OWNER), root,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, async handle => {
+        await handle.writeFile(encode(owner));
+        await handle.sync();
+      });
+    await syncDirectory(candidate);
+    return candidate;
+  } catch (error) {
+    await rm(candidate, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function releaseCanonical(directory, root, owner, openFile) {
+  const current = await readOwner(directory, root, openFile);
+  if (current?.token !== owner.token) return;
+  // Recursive removal would first unlink owner.json and briefly expose an
+  // empty canonical directory. Move the complete lock aside atomically so a
+  // successor can only arrive after this owner has left the canonical name.
+  const identity = createHash("sha256")
+    .update(JSON.stringify([owner.pid, owner.token, owner.acquiredAt]))
+    .digest("hex");
+  const retired = path.join(path.dirname(directory), `writer.released-${identity}.lock`);
+  try {
+    await rename(directory, retired);
+  } catch (error) {
+    if (["ENOENT", "EEXIST", "ENOTEMPTY"].includes(error.code)) return;
+    throw error;
+  }
+  await rm(retired, { recursive: true, force: true });
+}
+
 /**
  * Who holds the lock, or nothing if it moved while we looked.
  *
  * Reads inside the store refuse a parent directory whose identity changed
  * between the check and the open - the defence against a directory being
  * swapped under a read. This lock is the one directory whose entire life is
- * being created and removed: `mkdir` grants it, `rm` releases it, so its inode
+ * being published and retired: `rename` grants and releases it, so its inode
  * changes every time it passes from one process to the next. Reading its owner
  * through the strict path meant a contended lock raised
  * "record parent directory changed while opening" and the whole command failed -
@@ -82,49 +130,79 @@ async function takeStaleOwnership(directory, root, owner, now, pidIsAlive) {
   if (owner === null) return false;
   const age = Date.parse(now) - Date.parse(owner.acquiredAt);
   if (pidIsAlive(owner.pid) && !(age > STALE_MS)) return false;
-  await rm(directory, { recursive: true, force: true });
-  return true;
+  // Every contender that observed this owner names the same retained target.
+  // rename() moves the whole lock atomically; exactly one contender can put it
+  // there. The target is deliberately left non-empty. A late contender cannot
+  // rename a successor over it, so a stale pathname observation never becomes
+  // permission to remove the writer that acquired the lock afterwards.
+  const identity = createHash("sha256")
+    .update(JSON.stringify([owner.pid, owner.token, owner.acquiredAt]))
+    .digest("hex");
+  const reclaimed = path.join(path.dirname(directory), `writer.reclaimed-${identity}.lock`);
+  try {
+    await rename(directory, reclaimed);
+    return true;
+  } catch (error) {
+    if (["ENOENT", "EEXIST", "ENOTEMPTY"].includes(error.code)) return false;
+    throw error;
+  }
 }
 
 export async function withWriterMutex(paths, options, operation) {
   const { root, clock, pidIsAlive = defaultPidIsAlive, uuid = randomUUID,
     attempts = Number.POSITIVE_INFINITY, waitMs = 20, openFile,
     acquireTimeoutMs = ACQUIRE_TIMEOUT_MS, monotonicNow = () => performance.now(),
-    sleep = sleepFor } = options;
+    wallNow = Date.now, deadlineAt, sleep = sleepFor } = options;
   const directory = path.join(paths.locks, "writer.lock");
   // Wall time can jump while a process waits. A monotonic absolute deadline
   // bounds all owner reads and retries, leaving half the hook's five-second
   // budget for publishing the owner, doing the write, and rendering a result.
-  const deadline = monotonicNow() + acquireTimeoutMs;
+  const started = monotonicNow();
+  const callerBudget = deadlineAt === undefined
+    ? Number.POSITIVE_INFINITY : Math.max(0, deadlineAt - wallNow());
+  const deadline = started + Math.min(acquireTimeoutMs, callerBudget);
   await ensureManagedDirectory(root, paths.locks);
   const token = uuid();
+  const owner = { pid: process.pid, token, acquiredAt: clock.now() };
+  const candidate = await prepareCandidate(paths, root, owner);
+  let ownsCanonical = false;
 
-  for (let attempt = 0; attempt < attempts; attempt += 1) {
-    if (monotonicNow() >= deadline) break;
-    try {
-      await mkdir(directory);
-    } catch (error) {
-      if (error.code !== "EEXIST") throw error;
-      const owner = await readOwner(directory, root, openFile);
-      if (!await takeStaleOwnership(directory, root, owner, clock.now(), pidIsAlive)) {
-        const remaining = deadline - monotonicNow();
-        if (remaining <= 0) break;
-        await sleep(Math.min(waitMs, remaining));
+  try {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      if (monotonicNow() >= deadline) break;
+      try {
+        // POSIX rename replaces an empty directory atomically. That recovers a
+        // lock left by the old mkdir-then-publish sequence. A live publisher
+        // either fills it first (so rename fails) or loses its no-replace owner
+        // publication after this complete candidate wins.
+        await rename(candidate, directory);
+        ownsCanonical = true;
+        await syncDirectory(paths.locks);
+      } catch (error) {
+        if (!["EEXIST", "ENOTEMPTY"].includes(error.code)) throw error;
+        const current = await readOwner(directory, root, openFile);
+        if (!await takeStaleOwnership(directory, root, current, clock.now(), pidIsAlive)) {
+          const remaining = deadline - monotonicNow();
+          if (remaining <= 0) break;
+          await sleep(Math.min(waitMs, remaining));
+        }
+        continue;
       }
-      continue;
-    }
-    if (monotonicNow() >= deadline) {
-      await rm(directory, { recursive: true, force: true });
-      break;
-    }
-    const owner = { pid: process.pid, token, acquiredAt: clock.now() };
-    await publishAtomic(path.join(directory, OWNER), encode(owner), { root, tmpDir: paths.tmp });
-    try {
+      if (monotonicNow() >= deadline) break;
       return await operation();
-    } finally {
-      const current = await readOwner(directory, root, openFile);
-      if (current?.token === token) await rm(directory, { recursive: true, force: true });
+    }
+  } finally {
+    if (ownsCanonical) {
+      await releaseCanonical(directory, root, owner, openFile);
+    } else {
+      const current = await readOwner(candidate, root, openFile);
+      if (current?.token === token) {
+        await rm(candidate, { recursive: true, force: true });
+      }
     }
   }
-  throw new AccError(EXIT.CONFLICT, "another writer holds the store lock", { directory });
+  const reason = deadlineAt !== undefined && wallNow() >= deadlineAt
+    ? "transaction deadline expired while waiting for the store lock"
+    : "another writer holds the store lock";
+  throw new AccError(EXIT.CONFLICT, reason, { directory });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "type": "module",
   "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [
@@ -45,7 +45,23 @@
   },
   "files": [
     "bin/",
+    "docs/ADAPTER_AUTHORING.md",
+    "docs/ARCHITECTURE.md",
     "docs/CAPABILITIES.md",
+    "docs/CLI.md",
+    "docs/CONCEPTS.md",
+    "docs/CONFIGURATION.md",
+    "docs/DESIGN_DECISIONS.md",
+    "docs/GETTING_STARTED.md",
+    "docs/GLOSSARY.md",
+    "docs/MCP.md",
+    "docs/PROTOCOL.md",
+    "docs/RELEASING.md",
+    "docs/SECURITY_MODEL.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/WHY_ACC.md",
+    "docs/index.md",
+    "SECURITY.md",
     "README.md",
     "LICENSE"
   ],
@@ -58,6 +74,7 @@
     "@agents-can-communicate/adapter-sdk": "*",
     "@agents-can-communicate/cli": "*",
     "@agents-can-communicate/core": "*",
+    "@agents-can-communicate/delivery-router": "*",
     "@agents-can-communicate/hook-runner": "*",
     "@agents-can-communicate/installer": "*",
     "@agents-can-communicate/mcp-server": "*",
@@ -73,6 +90,7 @@
     "@agents-can-communicate/adapter-sdk",
     "@agents-can-communicate/cli",
     "@agents-can-communicate/core",
+    "@agents-can-communicate/delivery-router",
     "@agents-can-communicate/hook-runner",
     "@agents-can-communicate/installer",
     "@agents-can-communicate/mcp-server",