@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/session-runtime/notifications.mjs

@@ -0,0 +1,129 @@
+/**
+ * lib/engine/session-runtime/notifications.mjs — events that reach the model
+ * between turns: background shells that ended (CF-50), Monitor output lines,
+ * monitors that ended, and background subagents' reports (a drain source).
+ *
+ * The loop drains the queue before each model request (`drainNotifications`),
+ * so an event that arrives while a turn runs is seen at that turn's next
+ * request. In `cohort session`, an event that arrives while the session is
+ * idle wakes it: the inbox turns a batch into a turn of its own.
+ *
+ * Caps keep a chatty monitor from flooding the context:
+ *   · one drain takes at most `maxBatch` events and `maxChars` characters; the
+ *     rest stay queued for the next drain (nothing is lost below the queue cap);
+ *   · a single line is clipped at `maxLineChars`;
+ *   · at most `maxQueued` events wait; beyond that new events are counted and
+ *     dropped, and the next batch says how many.
+ *
+ * The formatters are pure; `createNotificationQueue` holds the state.
+ *
+ * @module lib/engine/session-runtime/notifications
+ */
+
+export const NOTICE_CAPS = Object.freeze({ maxQueued: 500, maxBatch: 40, maxChars: 16_000, maxLineChars: 2_000 });
+
+/** @param {string} s @param {number} max */
+function clip(s, max) {
+  return s.length <= max ? s : `${s.slice(0, max)}… [${s.length - max} more characters]`;
+}
+
+/**
+ * One batch of queued events as a single user message. Pure.
+ * @param {string[]} texts @param {{dropped?:number}} [o]
+ */
+export function formatNoticeBatch(texts, { dropped = 0 } = {}) {
+  const lines = [texts.length === 1 && dropped === 0 ? "[Event]" : `[Events: ${texts.length}]`, ...texts];
+  if (dropped > 0) lines.push(`[${dropped} further event(s) were dropped because too many were waiting]`);
+  return lines.join("\n");
+}
+
+/**
+ * The notice for a background shell that ended on its own. Pure.
+ * @param {{id:string, command:string, description?:string|null, kind?:string, status:string, exitCode:number|null, spillPath?:string|null}} s
+ */
+export function shellExitNotice(s) {
+  const what = s.kind === "monitor" ? "Monitor" : "Background shell";
+  const label = s.description ? `${s.description} (${clip(s.command, 120)})` : clip(s.command, 120);
+  const how = s.status === "completed" ? "exited with code 0" : `ended: ${s.exitCode == null ? "it could not run" : `exit code ${s.exitCode}`}`;
+  return `${what} ${s.id} ${how}: ${label}. Read what it printed with BashOutput {"bash_id":"${s.id}"}.`;
+}
+
+/**
+ * One Monitor output line as an event. Pure.
+ * @param {{id:string, description:string}} m @param {string} line
+ */
+export function monitorLineNotice(m, line) {
+  return `${m.id} (${m.description}): ${line}`;
+}
+
+/**
+ * @param {{caps?:Partial<typeof NOTICE_CAPS>}} [o]
+ */
+export function createNotificationQueue({ caps = {} } = {}) {
+  const c = { ...NOTICE_CAPS, ...caps };
+  /** @type {string[]} */
+  const queue = [];
+  let dropped = 0;
+  let poked = false;
+  /** @type {Array<() => string[]>} */
+  const sources = [];
+  /** @type {Set<() => void>} */
+  const listeners = new Set();
+  const announce = () => {
+    for (const l of [...listeners]) {
+      try {
+        l();
+      } catch {
+        /* a listener defect must not lose the event */
+      }
+    }
+  };
+
+  return {
+    /** Queue one event. @param {string} text */
+    push(text) {
+      if (queue.length >= c.maxQueued) dropped++;
+      else queue.push(clip(String(text), c.maxLineChars));
+      announce();
+    },
+    /** Another producer's drain (background subagents keep their own queue). @param {() => string[]} drain */
+    addSource(drain) {
+      sources.push(drain);
+    },
+    /** A source has something ready. */
+    poke() {
+      poked = true;
+      announce();
+    },
+    /** @param {() => void} fn @returns {() => void} unsubscribe */
+    onAvailable(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    hasPending: () => queue.length > 0 || dropped > 0 || poked,
+    get size() {
+      return queue.length;
+    },
+    /**
+     * Everything ready now, as user-message texts: the sources' own messages,
+     * then at most one capped batch of queued events.
+     * @returns {string[]}
+     */
+    drain() {
+      poked = false;
+      const out = [];
+      for (const s of sources) out.push(...s());
+      if (queue.length === 0 && dropped === 0) return out;
+      const take = [];
+      let chars = 0;
+      while (queue.length > 0 && take.length < c.maxBatch && (take.length === 0 || chars + queue[0].length <= c.maxChars)) {
+        const t = /** @type string */ (queue.shift());
+        chars += t.length;
+        take.push(t);
+      }
+      out.push(formatNoticeBatch(take, { dropped }));
+      dropped = 0;
+      return out;
+    },
+  };
+}

package/lib/engine/session-runtime/registry.mjs

@@ -0,0 +1,328 @@
+/**
+ * lib/engine/session-runtime/registry.mjs — the local session registry.
+ *
+ * One file per live `cohort session`: `<dir>/<name>.json`, where `<dir>` is
+ * `$COHORT_SESSION_DIR` or `~/.cohort/sessions` (mode 0700):
+ *
+ *   { name, sessionId, pid, cwd, socketPath, startedAt, heartbeatAt, heartbeatMs,
+ *     engine:"cohort", state:"starting"|"idle"|"busy", agentRoot? }
+ *
+ * · Names are unique among LIVE sessions. Every change to `<name>.json` is made
+ *   under a short `<name>.lock` (created with O_EXCL, broken after 10 s), so two
+ *   sessions started together cannot both take a name.
+ * · An entry is live only while its pid is alive AND its heartbeat is recent
+ *   (within 3 × its `heartbeatMs`). A pid alone proves nothing after a crash:
+ *   the number may belong to another process by now.
+ *     dead    (pid gone)            listing prunes it — under the lock, after
+ *                                   re-reading, and only if the file still names
+ *                                   that same instance (pid, sessionId, startedAt)
+ *     silent  (pid there, no beat)  hidden from listing and free to claim; its
+ *                                   files are left alone until a claim takes it
+ * · Each instance binds its own socket file (`<name>.<nonce>.sock`), so removing
+ *   an old instance's socket can never unlink a successor's.
+ * · The owner rewrites its entry on every idle/busy change and every heartbeat,
+ *   restores it if it has vanished and the name is free, and removes it on exit.
+ *   Refresh and release act only on the caller's own instance, so a replaced
+ *   session cannot erase its successor.
+ *
+ * `planClaim`, `entryLiveness`, `describeSession`, `socketPathFor` and
+ * `formatAge` are pure; `createRegistry` is the edge (fs, clock and the pid
+ * probe are injectable).
+ *
+ * @module lib/engine/session-runtime/registry
+ */
+
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { writeJsonAtomic } from "../../fs-atomic.mjs";
+
+export const HEARTBEAT_MS = 15_000;
+export const LOCK_STALE_MS = 10_000;
+/** An entry whose heartbeat is older than this many intervals is not live. */
+export const STALE_HEARTBEATS = 3;
+/** macOS allows 104 bytes for a Unix socket path (including the NUL); Linux 108. */
+export const SOCKET_PATH_MAX = 100;
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** @param {unknown} name @returns {name is string} */
+export function isValidSessionName(name) {
+  return typeof name === "string" && NAME_RE.test(name) && !name.includes("..");
+}
+
+/** @param {{env:Record<string,string|undefined>, homedir:string}} o */
+export function defaultRegistryDir({ env, homedir }) {
+  return env.COHORT_SESSION_DIR || path.join(homedir, ".cohort", "sessions");
+}
+
+/**
+ * The control socket's path: `<dir>/<name>.<nonce>.sock`, or — when that is too
+ * long for a Unix socket — a hashed name in a per-user directory under the
+ * temp base (`os.tmpdir()`, per user on macOS), else under /tmp. The socket
+ * server refuses a directory that is not a real 0700 directory of this user
+ * (socket.mjs `ensurePrivateDir`). Pure given its inputs.
+ * @param {string} dir @param {string} name @param {{uid?:number, nonce?:string, tmpBase?:string}} [o]
+ */
+export function socketPathFor(dir, name, { uid = typeof process.getuid === "function" ? process.getuid() : 0, nonce = "", tmpBase = os.tmpdir() } = {}) {
+  const p = path.join(dir, nonce ? `${name}.${nonce}.sock` : `${name}.sock`);
+  if (Buffer.byteLength(p) <= SOCKET_PATH_MAX) return p;
+  const file = `${createHash("sha256").update(p).digest("hex").slice(0, 24)}.sock`;
+  const inTmp = path.join(tmpBase, `cohort-sessions-${uid}`, file);
+  return Buffer.byteLength(inTmp) <= SOCKET_PATH_MAX ? inTmp : path.join("/tmp", `cohort-sessions-${uid}`, file);
+}
+
+/** Two entries describe the same session instance. @param {any} a @param {any} b */
+export function sameInstance(a, b) {
+  return Boolean(a && b && a.pid === b.pid && a.sessionId === b.sessionId && a.startedAt === b.startedAt);
+}
+
+/**
+ * Is an entry's session still there? Pure.
+ * @param {any} e @param {{isAlive:(pid:number)=>boolean, now:number}} o
+ * @returns {'live'|'silent'|'dead'}
+ */
+export function entryLiveness(e, { isAlive, now }) {
+  if (!isAlive(e.pid)) return "dead";
+  const beat = Date.parse(e.heartbeatAt);
+  const every = Number.isFinite(e.heartbeatMs) && e.heartbeatMs > 0 ? e.heartbeatMs : HEARTBEAT_MS;
+  if (!Number.isFinite(beat) || now - beat > STALE_HEARTBEATS * every) return "silent";
+  return "live";
+}
+
+/** @param {any} e */
+export function isEntry(e) {
+  return Boolean(e && typeof e === "object" && isValidSessionName(e.name) && Number.isInteger(e.pid) && e.pid > 0 && typeof e.socketPath === "string");
+}
+
+/**
+ * What a claim of `name` should do, given the entry already there. Pure.
+ * @param {{existing:any, isAlive:(pid:number)=>boolean, pid:number, now:number, force?:boolean}} p
+ * @returns {{kind:'free'}|{kind:'stale', entry:any}|{kind:'taken', entry:any}|{kind:'force', entry:any}}
+ */
+export function planClaim({ existing, isAlive, pid, now, force = false }) {
+  if (!isEntry(existing)) return { kind: "free" };
+  if (existing.pid === pid || entryLiveness(existing, { isAlive, now }) !== "live") return { kind: "stale", entry: existing };
+  return force ? { kind: "force", entry: existing } : { kind: "taken", entry: existing };
+}
+
+/** @param {number} ms */
+export function formatAge(ms) {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86_400) return `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
+  return `${Math.floor(s / 86_400)}d${Math.floor((s % 86_400) / 3600)}h`;
+}
+
+/**
+ * A registry entry as ListAgents reports it. Pure.
+ * @param {any} e @param {{now:number, self?:string|null}} o
+ */
+export function describeSession(e, { now, self = null }) {
+  const started = Date.parse(e.startedAt);
+  const beat = Date.parse(e.heartbeatAt);
+  return {
+    name: e.name,
+    cwd: e.cwd,
+    status: e.state === "busy" ? "busy" : e.state === "starting" ? "starting" : "idle",
+    age: Number.isFinite(started) ? formatAge(now - started) : null,
+    lastHeartbeat: Number.isFinite(beat) ? formatAge(now - beat) : null,
+    ...(e.name === self ? { self: true } : {}),
+  };
+}
+
+/**
+ * Is a process alive? EPERM means it exists under another user. A live pid is
+ * necessary, not sufficient: see `entryLiveness`. @param {number} pid
+ */
+export function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return /** @type {NodeJS.ErrnoException} */ (e).code === "EPERM";
+  }
+}
+
+/**
+ * @param {{dir:string, isAlive?:(pid:number)=>boolean, now?:()=>number}} o
+ */
+export function createRegistry({ dir, isAlive = isPidAlive, now = Date.now }) {
+  const entryPath = (/** @type string */ name) => path.join(dir, `${name}.json`);
+  const ensureDir = () => {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+      chmodSync(dir, 0o700);
+    } catch {
+      /* not ours to change; the socket itself is still 0600 */
+    }
+  };
+  const read = (/** @type string */ name) => {
+    try {
+      const e = JSON.parse(readFileSync(entryPath(name), "utf8"));
+      return isEntry(e) ? e : null;
+    } catch {
+      return null;
+    }
+  };
+  const removeFiles = (/** @type any */ e) => {
+    for (const p of [entryPath(e.name), e.socketPath].filter(Boolean)) {
+      try {
+        unlinkSync(p);
+      } catch {
+        /* already gone */
+      }
+    }
+  };
+
+  /**
+   * Remove a dead instance's files — under the lock, and only if the entry on
+   * disk is still that instance and still dead (a successor may have claimed
+   * the name since it was read). @param {any} seen
+   */
+  const prune = (seen) =>
+    withLock(seen.name, () => {
+      const cur = read(seen.name);
+      if (cur && sameInstance(cur, seen) && entryLiveness(cur, { isAlive, now: now() }) === "dead") removeFiles(cur);
+    });
+
+  /** @template T @param {string} name @param {() => T} fn @returns {T|null} null = could not take the lock */
+  const withLock = (name, fn) => {
+    ensureDir();
+    const lock = path.join(dir, `${name}.lock`);
+    for (let attempt = 0; attempt < 50; attempt++) {
+      try {
+        closeSync(openSync(lock, "wx", 0o600));
+        try {
+          return fn();
+        } finally {
+          try {
+            unlinkSync(lock);
+          } catch {
+            /* removed by a stale-lock breaker */
+          }
+        }
+      } catch (e) {
+        if (/** @type any */ (e)?.code !== "EEXIST") throw e;
+        try {
+          if (now() - statSync(lock).mtimeMs > LOCK_STALE_MS) unlinkSync(lock);
+        } catch {
+          /* raced with its owner */
+        }
+        const until = Date.now() + 20;
+        while (Date.now() < until) {
+          /* a claim holds the lock for one small write */
+        }
+      }
+    }
+    return null;
+  };
+
+  return {
+    dir,
+    entryPath,
+    /** Live entries; dead ones are pruned, silent ones hidden. */
+    list() {
+      let files = [];
+      try {
+        files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+      } catch {
+        return [];
+      }
+      const live = [];
+      for (const f of files.sort()) {
+        const e = read(f.slice(0, -".json".length));
+        if (!e) continue;
+        const l = entryLiveness(e, { isAlive, now: now() });
+        if (l === "live") live.push(e);
+        else if (l === "dead") prune(e);
+      }
+      return live;
+    },
+    /** @param {string} name */
+    get(name) {
+      if (!isValidSessionName(name)) return null;
+      const e = read(name);
+      if (!e) return null;
+      const l = entryLiveness(e, { isAlive, now: now() });
+      if (l === "live") return e;
+      if (l === "dead") prune(e);
+      return null;
+    },
+    /**
+     * @param {any} entry @param {{force?:boolean}} [o]
+     * @returns {{ok:true}|{ok:false, code:'session_name_taken'|'registry_locked'|'invalid_session_name', message:string, entry?:any}}
+     */
+    claim(entry, { force = false } = {}) {
+      if (!isValidSessionName(entry.name)) return { ok: false, code: "invalid_session_name", message: `invalid session name "${entry.name}"` };
+      const r = withLock(entry.name, () => {
+        const plan = planClaim({ existing: read(entry.name), isAlive, pid: entry.pid, now: now(), force });
+        if (plan.kind === "taken") return { ok: /** @type {false} */ (false), code: /** @type {'session_name_taken'} */ ("session_name_taken"), message: `a session named "${entry.name}" is already running (pid ${plan.entry.pid}, ${plan.entry.cwd})`, entry: plan.entry };
+        if (plan.kind === "stale") removeFiles(plan.entry);
+        writeJsonAtomic(entryPath(entry.name), entry, { mode: 0o600 });
+        return { ok: /** @type {true} */ (true) };
+      });
+      return r ?? { ok: false, code: "registry_locked", message: `could not lock the registry entry for "${entry.name}"` };
+    },
+    /**
+     * The owner's heartbeat and state writes: rewrite its own entry — or put it
+     * back if it has vanished (or only a dead or silent instance holds the name).
+     * "replaced" = another live session holds the name now; nothing is written.
+     * @param {any} entry  the owner's full entry
+     * @returns {'ok'|'restored'|'replaced'|'locked'|'failed'}
+     */
+    refresh(entry) {
+      const r = withLock(entry.name, () => {
+        const cur = read(entry.name);
+        const own = sameInstance(cur, entry);
+        if (cur && !own && planClaim({ existing: cur, isAlive, pid: entry.pid, now: now() }).kind === "taken") return "replaced";
+        try {
+          if (cur && !own) removeFiles({ ...cur, socketPath: cur.socketPath === entry.socketPath ? "" : cur.socketPath });
+          writeJsonAtomic(entryPath(entry.name), entry, { mode: 0o600 });
+          return own ? "ok" : "restored";
+        } catch {
+          return "failed";
+        }
+      });
+      return r ?? "locked";
+    },
+    /** Rewrite the caller's own entry (by pid). @param {string} name @param {number} pid @param {Record<string,unknown>} patch */
+    update(name, pid, patch) {
+      const r = withLock(name, () => {
+        const e = read(name);
+        if (!e || e.pid !== pid) return false;
+        try {
+          writeJsonAtomic(entryPath(name), { ...e, ...patch }, { mode: 0o600 });
+          return true;
+        } catch {
+          return false;
+        }
+      });
+      return r ?? false;
+    },
+    /**
+     * Remove the caller's own entry (not a successor's).
+     * @param {string} name @param {number} pid @param {{sessionId:string, startedAt:string}} [instance]
+     */
+    release(name, pid, instance) {
+      const r = withLock(name, () => {
+        const e = read(name);
+        if (!e || e.pid !== pid) return false;
+        if (instance && !sameInstance(e, { pid, ...instance })) return false;
+        try {
+          unlinkSync(entryPath(name));
+        } catch {
+          /* already gone */
+        }
+        return true;
+      });
+      return r ?? false;
+    },
+  };
+}
+
+/** Where the registry lives for this process. @param {Record<string,string|undefined>} env */
+export function registryDirFromEnv(env) {
+  return defaultRegistryDir({ env, homedir: env.HOME || os.homedir() });
+}