@cohortapp/agent-sdk 2.16.0 → 2.17.0

package/scripts/daemon/lib/session-router.mjs

@@ -19,7 +19,7 @@
  * explicitly rejects flock — "no stale lock files if the daemon dies".
  */
 
-import { promises as fsp } from "fs";
+import { promises as fsp, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { dirname } from "path";
 
 // canonicalizeSlackChannel exists in some installs of scripts/daemon/session-lock.mjs.
@@ -41,6 +41,122 @@ try {
 
 const EMPTY_REGISTRY = () => ({ sessions: {}, lru: [] });
 
+/**
+ * Routing keys with a CLI process live on them right now, in THIS daemon.
+ *
+ * A registry row only becomes "live" when a session CLOSES cleanly, so the
+ * registry alone cannot answer "is something already running on this key". It
+ * did not have to before: every dispatch minted its own `randomUUID()`, so two
+ * concurrent turns in one room were two unrelated sessions. Now they share a
+ * key, and `#capital-formation` — 9,187 messages in 21 days, ~38 an hour,
+ * TOP-LEVEL, so `agent-daemon.mjs`'s thread lock (which needs a thread id, or a
+ * DM) does not cover it — delivers bursts of three and four at a time. Without
+ * this set, all of them would resume the same id: N `claude --print
+ * --session-id <same>` processes appending one transcript.
+ *
+ * So: a key that is in flight never RESUMEs. The later turns spawn cold, which
+ * is exactly the behaviour being replaced, and continuity resumes on the next
+ * turn after the room goes quiet. Process-local by construction — the lease is
+ * about OUR child processes, and a stale entry cannot outlive the process that
+ * holds it.
+ */
+const inFlightKeys = new Set();
+
+/** Claim a key for a spawn. Returns false when something already holds it. */
+export function claimSession(key) {
+  const k = String(key || "");
+  if (!k || inFlightKeys.has(k)) return false;
+  inFlightKeys.add(k);
+  return true;
+}
+
+/** Release a claimed key. Safe to call twice, and for a key never claimed. */
+export function releaseSession(key) {
+  inFlightKeys.delete(String(key || ""));
+}
+
+/** Is a CLI process live on this key in this daemon? */
+export function isSessionInFlight(key) {
+  return inFlightKeys.has(String(key || ""));
+}
+
+/** For tests: forget every claim. */
+export function _resetInFlightForTests() {
+  inFlightKeys.clear();
+}
+
+/**
+ * Services whose routing key is `<source>:<channel>[:<thread>]`.
+ *
+ * Extend by adding a name here, not by editing the key function — a new channel
+ * adapter with the same room+thread shape needs nothing else.
+ */
+export const CONVERSATION_SOURCES = new Set(["cohort", "telegram", "whatsapp", "orgmail"]);
+
+/**
+ * Translate a DAEMON-shaped item into the `{source, …}` view {@link routingKey}
+ * expects. PURE.
+ *
+ * Daemon items are `{service, channel_id, thread_id, …}`; the router's key
+ * function was specced against `{source, channel, thread_ts, …}` (memo §4.2).
+ * This is the seam between them, and it lives HERE rather than in one caller so
+ * the responder and the dispatcher cannot key the same conversation two ways —
+ * which would give one room two sessions and defeat the whole mechanism.
+ *
+ * Returns null for an item the router cannot key (a service with no shape, or a
+ * missing channel/thread). The caller then mints a fresh id, exactly as before.
+ *
+ * @param {object} item
+ * @returns {object|null}
+ */
+export function routerItemFromDaemonItem(item) {
+  if (!item || typeof item !== "object") return null;
+
+  if (item.service === "slack") {
+    const channel = item.channel || item.channel_id;
+    if (!channel) return null;
+    return {
+      source: "slack",
+      channel,
+      thread_ts: item.thread_id || item.thread_ts || null,
+      ts: item.ts || item.timestamp || null,
+    };
+  }
+
+  if (item.service === "gmail") {
+    const tid = item.thread_id || item.threadId;
+    if (!tid) return null;
+    return { source: "gmail", thread_id: tid };
+  }
+
+  if (item.service === "calendar") {
+    const eid = item.event_id || item.eventId;
+    if (!eid) return null;
+    return { source: "calendar", event_id: eid };
+  }
+
+  // Cohort and the other room+thread services. THIS USED TO RETURN NULL FOR
+  // COHORT, so every turn in the agent's own workspace fell back to a fresh
+  // pre-minted UUID and started cold — the session router existed and the one
+  // surface the owner actually uses never reached it (design §3 R10).
+  //
+  // `channel_id` ONLY, never `channel`: `item.channel` is the display label
+  // (`task/<title>`, `doc/<name>`), and keying a session on a label collides
+  // two rooms that happen to share a title. A surface with no room id simply
+  // has no session to continue.
+  if (CONVERSATION_SOURCES.has(item.service)) {
+    const channel = item.channel_id;
+    if (!channel) return null;
+    return {
+      source: item.service,
+      channel,
+      thread_root_id: item.thread_root_id || item.thread_id || null,
+    };
+  }
+
+  return null;
+}
+
 /**
  * Pure key-derivation function (memo §4.2 table).
  *
@@ -71,6 +187,25 @@ export function routingKey(item) {
     return `gmail:${tid}`;
   }
 
+  // Conversation-shaped services: one ROOM, optionally one thread inside it.
+  //
+  // `cohort` used to fall through to the throw below, so every Cohort turn was
+  // keyed by nothing, routed by nothing, and spawned cold — the agent's own
+  // workspace was the one surface with no continuity at all (design §3 R10).
+  // telegram / whatsapp / orgmail have exactly the same shape and were in the
+  // same position.
+  //
+  // The room is the key when there is no thread, for the same reason a Slack DM
+  // is: a room with no threading IS one conversation. A thread root narrows it,
+  // so two threads in a busy channel do not share a session and leak each
+  // other's context.
+  if (CONVERSATION_SOURCES.has(source)) {
+    const channel = item.channel || item.channel_id || "";
+    if (!channel) throw new Error(`routingKey: ${source} item missing channel`);
+    const thread = item.thread_root_id || item.threadRootId || item.thread_id || item.thread_ts || "";
+    return thread ? `${source}:${channel}:${thread}` : `${source}:${channel}`;
+  }
+
   if (source === "calendar") {
     const eid = item.event_id || item.eventId;
     if (!eid) throw new Error("routingKey: calendar item missing event_id");
@@ -91,6 +226,51 @@ export function routingKey(item) {
   throw new Error(`routingKey: unknown source "${source}"`);
 }
 
+/**
+ * THE routing decision, as a pure function of the entry and the clock.
+ *
+ * Extracted so the async router (responder.mjs) and the SYNCHRONOUS one
+ * (dispatcher.mjs, whose spawn path is not async) cannot drift: one rule, two
+ * IO shells. Every branch is the memo §4.4 table.
+ *
+ * @param {object|undefined} entry  the registry row for this key
+ * @param {{now:number, ttlSeconds:number}} o
+ * @returns {{decision:"EPHEMERAL"|"EPHEMERAL_REPLACE"|"RESUME", resumeId:string|null}}
+ */
+export function decideRoute(entry, { now, ttlSeconds }) {
+  if (!entry) return { decision: "EPHEMERAL", resumeId: null };
+  if (now - entry.last_used_at > ttlSeconds * 1000) return { decision: "EPHEMERAL_REPLACE", resumeId: null };
+  if (entry.status !== "live") return { decision: "EPHEMERAL_REPLACE", resumeId: null };
+  if (entry.last_exit_code !== 0) return { decision: "EPHEMERAL_REPLACE", resumeId: null };
+  return { decision: "RESUME", resumeId: entry.claude_session_id };
+}
+
+/**
+ * Build the registry row for a touched key. Pure — {@link touchEntry} is the
+ * only place the row's shape is decided, for both IO shells.
+ */
+export function touchEntry(existing, { key, claudeSessionId, daemonSessionId, model, now, ttlSeconds }) {
+  return {
+    daemon_session_id: daemonSessionId || (existing && existing.daemon_session_id) || null,
+    claude_session_id: claudeSessionId ?? (existing && existing.claude_session_id) ?? null,
+    key,
+    model: model || (existing && existing.model) || null,
+    created_at: (existing && existing.created_at) || new Date(now).toISOString(),
+    last_used_at: now,
+    ttl_seconds: ttlSeconds,
+    status: "live",
+    last_exit_code: 0,
+  };
+}
+
+/** Coerce a parsed blob into the registry shape. Shared by both IO shells. */
+function asRegistry(parsed) {
+  if (!parsed || typeof parsed !== "object") return EMPTY_REGISTRY();
+  if (!parsed.sessions || typeof parsed.sessions !== "object") parsed.sessions = {};
+  if (!Array.isArray(parsed.lru)) parsed.lru = [];
+  return parsed;
+}
+
 /**
  * Read the registry from disk. Missing file → empty registry shape.
  * Corrupted JSON also degrades to empty (memo §6: "Read failure on the
@@ -98,15 +278,17 @@ export function routingKey(item) {
  */
 async function readRegistry(path) {
   try {
-    const raw = await fsp.readFile(path, "utf-8");
-    const parsed = JSON.parse(raw);
-    // Defensive: ensure shape
-    if (!parsed || typeof parsed !== "object") return EMPTY_REGISTRY();
-    if (!parsed.sessions || typeof parsed.sessions !== "object") parsed.sessions = {};
-    if (!Array.isArray(parsed.lru)) parsed.lru = [];
-    return parsed;
-  } catch (err) {
-    if (err && err.code === "ENOENT") return EMPTY_REGISTRY();
+    return asRegistry(JSON.parse(await fsp.readFile(path, "utf-8")));
+  } catch {
+    return EMPTY_REGISTRY();
+  }
+}
+
+/** The same read, synchronously — {@link createRouterSync} and every re-read. */
+function readRegistrySync(path) {
+  try {
+    return asRegistry(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
     return EMPTY_REGISTRY();
   }
 }
@@ -151,8 +333,25 @@ export async function createRouter({
     throw new Error("createRouter: registryPath is required");
   }
 
-  // Eagerly load so first call doesn't race with concurrent writers.
+  // RE-READ ON EVERY OPERATION. This used to load the file once and keep the
+  // object for the daemon's life, which was safe for exactly as long as this
+  // router was the only writer. It is not any more: `dispatcher.mjs` now writes
+  // the SAME file through `createRouterSync`, and a cached writer here did two
+  // destructive things with it — `touch()` wrote its stale snapshot back, and
+  // the LRU sweep at the end of `touch()` DELETED every key absent from that
+  // snapshot, so one ordinary quick reply erased the dispatcher's live session
+  // rows. Worse in the other direction: this shell would answer RESUME from a
+  // cached entry the dispatcher had already recorded as killed.
+  //
+  // A re-read costs one small JSON parse per spawn, against a process launch.
+  // Continuity is not worth a correctness hole, and two shells over one file
+  // must agree about what is in it.
   let registry = await readRegistry(registryPath);
+  /** Refresh from disk, so another writer's rows are never overwritten. */
+  function refresh() {
+    registry = readRegistrySync(registryPath);
+    return registry;
+  }
 
   /**
    * Decide RESUME / EPHEMERAL / EPHEMERAL_REPLACE for a key (memo §4.4).
@@ -162,24 +361,17 @@ export async function createRouter({
    * @returns {{ decision: "EPHEMERAL"|"EPHEMERAL_REPLACE"|"RESUME", resumeId: string|null }}
    */
   function route(key) {
-    const entry = registry.sessions[key];
-    if (!entry) return { decision: "EPHEMERAL", resumeId: null };
-
-    const ttlMs = ttlSeconds * 1000;
-    if (now() - entry.last_used_at > ttlMs) {
-      return { decision: "EPHEMERAL_REPLACE", resumeId: null };
-    }
-    if (entry.status !== "live") {
-      return { decision: "EPHEMERAL_REPLACE", resumeId: null };
+    // Never hand a running session's id to a second process — see inFlightKeys.
+    if (isSessionInFlight(key)) return { decision: "EPHEMERAL", resumeId: null };
+    const reg = refresh();
+    const entry = reg.sessions[key];
+    const out = decideRoute(entry, { now: now(), ttlSeconds });
+    if (out.decision === "RESUME") {
+      // Touch in-memory; persisted on next touch()/recordExit() write.
+      entry.last_used_at = now();
+      bumpLru(reg.lru, key);
     }
-    if (entry.last_exit_code !== 0) {
-      return { decision: "EPHEMERAL_REPLACE", resumeId: null };
-    }
-
-    // Touch in-memory; persisted on next touch()/recordExit() write.
-    entry.last_used_at = now();
-    bumpLru(registry.lru, key);
-    return { decision: "RESUME", resumeId: entry.claude_session_id };
+    return out;
   }
 
   /**
@@ -194,20 +386,12 @@ export async function createRouter({
    */
   async function touch(key, { claudeSessionId, daemonSessionId, model } = {}) {
     const ts = now();
-    const isoNow = new Date(ts).toISOString();
+    // Merge onto what is on disk NOW, not onto a snapshot from process start.
+    // The LRU sweep below deletes keys, so a stale base does not merely lose an
+    // update — it removes another writer's live sessions.
+    refresh();
     const existing = registry.sessions[key];
-
-    const entry = {
-      daemon_session_id: daemonSessionId || existing?.daemon_session_id || null,
-      claude_session_id: claudeSessionId ?? existing?.claude_session_id ?? null,
-      key,
-      model: model || existing?.model || null,
-      created_at: existing?.created_at || isoNow,
-      last_used_at: ts,
-      ttl_seconds: ttlSeconds,
-      status: "live",
-      last_exit_code: 0,
-    };
+    const entry = touchEntry(existing, { key, claudeSessionId, daemonSessionId, model, now: ts, ttlSeconds });
     registry.sessions[key] = entry;
     bumpLru(registry.lru, key);
 
@@ -231,6 +415,7 @@ export async function createRouter({
    * next route() returns EPHEMERAL_REPLACE.
    */
   async function recordExit(key, exitCode) {
+    refresh();
     const entry = registry.sessions[key];
     if (!entry) return; // No-op — key was never touched.
     entry.last_exit_code = exitCode;
@@ -245,6 +430,7 @@ export async function createRouter({
    * Returns the count evicted.
    */
   async function evictExpired() {
+    refresh();
     const ttlMs = ttlSeconds * 1000;
     const cutoff = now() - ttlMs;
     let evicted = 0;
@@ -267,8 +453,90 @@ export async function createRouter({
    * the live registry by accident.
    */
   function _readForTests() {
-    return JSON.parse(JSON.stringify(registry));
+    return JSON.parse(JSON.stringify(refresh()));
   }
 
   return { route, touch, recordExit, evictExpired, _readForTests };
 }
+
+
+/**
+ * The SYNCHRONOUS face of the same registry.
+ *
+ * `dispatcher.mjs#spawnSession` builds its argv and calls `spawn` in one
+ * synchronous pass, reached from a synchronous `dispatch()`. Making that path
+ * async to await the router would ripple through the queue, the eviction path
+ * and every caller — so the router grows a sync shell over the SAME file, the
+ * SAME key function and the SAME pure decision ({@link decideRoute}). Two IO
+ * shells, one rule; a drift between them would be a bug in one place, not two.
+ *
+ * The registry is a single small JSON file and these calls happen once per
+ * spawn, so the blocking read is nanoseconds against a process launch. Writes
+ * keep the temp-file + rename pattern, so a concurrent reader never sees a
+ * half-written file.
+ *
+ * Every method is FAIL-OPEN: an unreadable or corrupt registry routes
+ * EPHEMERAL (a cold session, which is exactly today's behaviour), and a failed
+ * write is logged by the caller and forgotten. Session continuity is an
+ * optimisation; losing it must never cost the work.
+ *
+ * @param {object} opts same shape as {@link createRouter}
+ */
+export function createRouterSync({
+  registryPath,
+  ttlSeconds = 1800,
+  maxLiveSessions = 8,
+  now = () => Date.now(),
+} = {}) {
+  if (!registryPath) throw new Error("createRouterSync: registryPath is required");
+
+  // Missing or corrupt: an empty registry, which routes EPHEMERAL. Same posture
+  // as the async shell — never throw on the spawn path.
+  const read = () => readRegistrySync(registryPath);
+
+  function write(registry) {
+    try {
+      mkdirSync(dirname(registryPath), { recursive: true });
+      const tmp = `${registryPath}.tmp.${process.pid}.${Date.now()}`;
+      writeFileSync(tmp, JSON.stringify(registry, null, 2), "utf-8");
+      renameSync(tmp, registryPath);
+      return true;
+    } catch {
+      // A registry we cannot persist costs continuity on the NEXT turn, nothing
+      // on this one. The session is already spawning.
+      return false;
+    }
+  }
+
+  return {
+    /** @returns {{decision:string, resumeId:string|null}} */
+    route(key) {
+      // Never hand a running session's id to a second process — see inFlightKeys.
+      if (isSessionInFlight(key)) return { decision: "EPHEMERAL", resumeId: null };
+      return decideRoute(read().sessions[key], { now: now(), ttlSeconds });
+    },
+    touch(key, { claudeSessionId, daemonSessionId, model } = {}) {
+      const registry = read();
+      registry.sessions[key] = touchEntry(registry.sessions[key], {
+        key, claudeSessionId, daemonSessionId, model, now: now(), ttlSeconds,
+      });
+      bumpLru(registry.lru, key);
+      while (registry.lru.length > maxLiveSessions) {
+        const evictKey = registry.lru.shift();
+        if (evictKey && evictKey !== key) delete registry.sessions[evictKey];
+      }
+      for (const k of Object.keys(registry.sessions)) {
+        if (!registry.lru.includes(k)) delete registry.sessions[k];
+      }
+      return write(registry);
+    },
+    recordExit(key, exitCode) {
+      const registry = read();
+      const entry = registry.sessions[key];
+      if (!entry) return false;
+      entry.last_exit_code = exitCode;
+      if (exitCode !== 0) entry.status = "killed";
+      return write(registry);
+    },
+  };
+}