@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/session/identity.mjs

@@ -0,0 +1,220 @@
+/**
+ * lib/session/identity.mjs — WHO the main session is, and how it comes back.
+ *
+ * The main session's id is STABLE across relaunches so the agent keeps its
+ * transcript: `state/session/main-session.json` holds
+ *
+ *   { sessionId, createdAt, resumes, lastLaunchAt?, rotations: [iso…], rotatedFrom? }
+ *
+ * The first launch of an id runs `claude --session-id <id>`; every later
+ * launch runs `claude --resume <id>`. If a resume dies non-zero inside
+ * {@link FAILURE_WINDOW_MS} the transcript is presumed missing/corrupt and the
+ * supervisor ROTATES to a fresh id — at most {@link MAX_ROTATIONS_PER_HOUR}
+ * times per hour, after which it backs off {@link BACKOFF_MS} and lets launchd
+ * relaunch it. Every decision here is a pure function of the record, the
+ * observed exit and an injected clock; the supervisor does the I/O.
+ *
+ * Names: the mux session is `maestro-<first>` and the Claude session is
+ * `<first>-main`, where `<first>` is {@link agentFirstName} — the SAME
+ * derivation `scripts/local-triggers/generate-plists.sh` uses for the launchd
+ * labels (lower-cased `firstName` from `config/agent.json`, else an inline
+ * literal in `config/agent.ts`, else the directory name minus `-ai`), so the
+ * plist, the lock, the mux and the session agree. `identity.test.mjs` runs the
+ * generator's block verbatim against this function to pin that.
+ *
+ * @module lib/session/identity
+ */
+
+"use strict";
+
+import { readFileSync as fsReadFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import { writeJsonAtomic as fsWriteJsonAtomic } from "../fs-atomic.mjs";
+import { sessionPaths } from "./config.mjs";
+
+/** A resume that dies inside this window is treated as a broken transcript. */
+export const FAILURE_WINDOW_MS = 20_000;
+/** Rotations allowed in any rolling hour before the supervisor backs off. */
+export const MAX_ROTATIONS_PER_HOUR = 3;
+/** How long the supervisor sleeps once the rotation budget is spent. */
+export const BACKOFF_MS = 10 * 60_000;
+const HOUR_MS = 3_600_000;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function iso(ms) { return new Date(ms).toISOString(); }
+function nowMs(now) { return typeof now === "function" ? Number(now()) : (now == null ? Date.now() : Number(now)); }
+
+/**
+ * Pure: parse the on-disk record. Returns null for anything that is not a
+ * record carrying a valid session id, so a corrupt file simply means "start
+ * fresh" rather than a crash.
+ * @param {string|null|undefined} text
+ */
+export function parseMainSession(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  let raw;
+  try { raw = JSON.parse(text); } catch { return null; }
+  if (!raw || typeof raw !== "object" || !UUID_RE.test(String(raw.sessionId || ""))) return null;
+  const rec = {
+    sessionId: String(raw.sessionId).toLowerCase(),
+    createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "",
+    resumes: Number.isInteger(raw.resumes) && raw.resumes >= 0 ? raw.resumes : 0,
+    rotations: Array.isArray(raw.rotations) ? raw.rotations.filter((r) => typeof r === "string" && Number.isFinite(Date.parse(r))) : [],
+  };
+  if (typeof raw.lastLaunchAt === "string") rec.lastLaunchAt = raw.lastLaunchAt;
+  if (typeof raw.rotatedFrom === "string") rec.rotatedFrom = raw.rotatedFrom;
+  return rec;
+}
+
+/**
+ * Pure: mint a brand-new main-session record.
+ * @param {{now?:number|Function, uuid?:Function}} [opts]
+ */
+export function newMainSession(opts = {}) {
+  const uuid = opts.uuid || randomUUID;
+  return { sessionId: uuid(), createdAt: iso(nowMs(opts.now)), resumes: 0, rotations: [] };
+}
+
+/**
+ * Read `state/session/main-session.json`. Fail-open: null when absent/corrupt.
+ * @param {string} agentRoot
+ * @param {{readFileSync?:Function}} [deps]
+ */
+export function loadMainSession(agentRoot, deps = {}) {
+  const readFileSync = deps.readFileSync || fsReadFileSync;
+  try {
+    return parseMainSession(readFileSync(sessionPaths(agentRoot).mainSessionFile, "utf8"));
+  } catch {
+    // Absent on first boot, or unreadable — either way the caller starts fresh.
+    return null;
+  }
+}
+
+/**
+ * Persist the record atomically. Returns a result frame rather than throwing.
+ * @param {string} agentRoot
+ * @param {object} record
+ * @param {{writeJsonAtomic?:Function}} [deps]
+ * @returns {{ok:true}|{ok:false, error:string}}
+ */
+export function saveMainSession(agentRoot, record, deps = {}) {
+  const writeJsonAtomic = deps.writeJsonAtomic || fsWriteJsonAtomic;
+  try {
+    writeJsonAtomic(sessionPaths(agentRoot).mainSessionFile, record);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * The agent's first name as generate-plists.sh derives it, so the launchd
+ * label, the lock, the mux session and the Claude session name agree:
+ *
+ *   1. `config/agent.json` `firstName`, lower-cased (NOT slugged — the
+ *      generator only lower-cases, and one derivation must win);
+ *   2. else `config/agent.ts` with an INLINE quoted literal
+ *      (`firstName: 'Priya'`; a type-only `firstName: string;` is not a value);
+ *   3. else, or when the value is "unconfigured", the agent directory's
+ *      basename minus a `-ai` suffix (`~/ravi-ai` → `ravi`).
+ *
+ * "agent" only when even the directory yields nothing. Never throws.
+ * @param {string} agentRoot
+ * @param {{readFileSync?:Function}} [deps]
+ */
+export function agentFirstName(agentRoot, deps = {}) {
+  const readFileSync = deps.readFileSync || fsReadFileSync;
+  let first = "";
+  try {
+    const agent = JSON.parse(readFileSync(join(agentRoot, "config", "agent.json"), "utf8"));
+    const v = agent && agent.firstName;
+    first = v == null || v === false ? "" : String(v).trim().toLowerCase();
+  } catch {
+    first = ""; // absent or malformed → next source
+  }
+  if (!first) {
+    try {
+      const ts = readFileSync(join(agentRoot, "config", "agent.ts"), "utf8");
+      const line = ts.split("\n").find((l) => /firstName:\s*['"]/.test(l));
+      const m = line && line.match(/firstName:\s*['"]([^'"]*)['"]/);
+      first = m ? m[1].trim().toLowerCase() : "";
+    } catch {
+      first = "";
+    }
+  }
+  if (!first || first === "unconfigured") first = basename(agentRoot).replace(/-ai$/, ""); // as-is: the generator does not lower-case this one
+  return first || "agent";
+}
+
+/** `maestro-<first>` — the screen/tmux session name. */
+export function muxSessionName(first) { return `maestro-${first}`; }
+/** `<first>-main` — the Claude session `--name`. */
+export function mainSessionName(first) { return `${first}-main`; }
+
+/**
+ * Pure: which flag this launch needs. A never-launched id (or `resume:false`)
+ * starts with `--session-id`; an id that has run before is `--resume`d.
+ * @param {{resumes:number}} record
+ * @param {{resume?:boolean}} [cfg]
+ * @returns {"session-id"|"resume"}
+ */
+export function launchMode(record, cfg = {}) {
+  if (cfg.resume === false) return "session-id";
+  return record && record.resumes > 0 ? "resume" : "session-id";
+}
+
+/**
+ * Pure: the record after a launch has been issued.
+ * @param {object} record @param {{now?:number|Function}} [opts]
+ */
+export function recordLaunch(record, opts = {}) {
+  return { ...record, resumes: (record.resumes || 0) + 1, lastLaunchAt: iso(nowMs(opts.now)) };
+}
+
+/**
+ * Pure: what the supervisor does after the mux session ends.
+ *
+ *   relaunch — the session ended (cleanly, or after living past the window):
+ *              exit 75 and let launchd bring it back with the same id.
+ *   rotate   — a resume died inside the failure window: mint a fresh id first.
+ *   backoff  — the rotation budget for this hour is spent: sleep, then exit 75.
+ *
+ * An UNKNOWN exit code (the exit file was not written) inside the window is
+ * treated as a failure: the cost of a wrong rotation is a fresh transcript,
+ * the cost of a wrong relaunch is a seat stuck in a 30-second crash loop.
+ *
+ * @param {{record:object, mode:"session-id"|"resume", exitCode:number|null, startedAt:number, endedAt:number, now?:number|Function, failureWindowMs?:number, maxRotationsPerHour?:number}} a
+ * @returns {{action:"relaunch"}|{action:"rotate"}|{action:"backoff", sleepMs:number}}
+ */
+export function rotationDecision(a) {
+  const windowMs = a.failureWindowMs ?? FAILURE_WINDOW_MS;
+  const max = a.maxRotationsPerHour ?? MAX_ROTATIONS_PER_HOUR;
+  const durationMs = Number(a.endedAt) - Number(a.startedAt);
+  const failed = a.exitCode === null || a.exitCode === undefined || a.exitCode !== 0;
+  if (a.mode !== "resume" || !failed || !(durationMs < windowMs)) return { action: "relaunch" };
+  const t = nowMs(a.now);
+  const recent = (a.record && a.record.rotations || []).filter((r) => t - Date.parse(r) < HOUR_MS);
+  if (recent.length >= max) return { action: "backoff", sleepMs: BACKOFF_MS };
+  return { action: "rotate" };
+}
+
+/**
+ * Pure: the record after a rotation — fresh id, zero resumes, this rotation
+ * stamped, and the rotation history pruned to the last hour.
+ * @param {object} record @param {{now?:number|Function, uuid?:Function}} [opts]
+ */
+export function rotateMainSession(record, opts = {}) {
+  const t = nowMs(opts.now);
+  const fresh = newMainSession({ now: t, uuid: opts.uuid });
+  const kept = (record.rotations || []).filter((r) => t - Date.parse(r) < HOUR_MS);
+  return { ...fresh, rotations: [...kept, iso(t)], rotatedFrom: record.sessionId };
+}
+
+export default {
+  FAILURE_WINDOW_MS, MAX_ROTATIONS_PER_HOUR, BACKOFF_MS,
+  parseMainSession, newMainSession, loadMainSession, saveMainSession,
+  agentFirstName, muxSessionName, mainSessionName,
+  launchMode, recordLaunch, rotationDecision, rotateMainSession,
+};

package/lib/session/identity.test.mjs

@@ -0,0 +1,180 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+import {
+  parseMainSession,
+  newMainSession,
+  loadMainSession,
+  saveMainSession,
+  agentFirstName,
+  muxSessionName,
+  mainSessionName,
+  launchMode,
+  recordLaunch,
+  rotationDecision,
+  rotateMainSession,
+  FAILURE_WINDOW_MS,
+  MAX_ROTATIONS_PER_HOUR,
+  BACKOFF_MS,
+} from "./identity.mjs";
+
+const T0 = Date.parse("2026-09-08T10:00:00Z");
+const UUID = "11111111-2222-4333-8444-555555555555";
+
+test("parseMainSession: valid record round-trips; junk → null", () => {
+  const rec = parseMainSession(JSON.stringify({ sessionId: UUID, createdAt: "2026-09-08T09:00:00Z", resumes: 2 }));
+  assert.deepEqual(rec, { sessionId: UUID, createdAt: "2026-09-08T09:00:00Z", resumes: 2, rotations: [] });
+  assert.equal(parseMainSession("{not json"), null);
+  assert.equal(parseMainSession(JSON.stringify({ sessionId: "not-a-uuid" })), null);
+  assert.equal(parseMainSession(JSON.stringify({ resumes: 1 })), null);
+  assert.equal(parseMainSession(null), null);
+});
+
+test("newMainSession: uses the injected uuid + clock, starts at zero resumes", () => {
+  const rec = newMainSession({ now: T0, uuid: () => UUID });
+  assert.deepEqual(rec, { sessionId: UUID, createdAt: "2026-09-08T10:00:00.000Z", resumes: 0, rotations: [] });
+});
+
+test("loadMainSession / saveMainSession go through injected fs and the atomic writer", () => {
+  const disk = {};
+  const deps = {
+    readFileSync: (p) => { if (!(p in disk)) { const e = new Error("ENOENT"); e.code = "ENOENT"; throw e; } return disk[p]; },
+    writeJsonAtomic: (p, obj) => { disk[p] = JSON.stringify(obj); },
+  };
+  assert.equal(loadMainSession("/agent", deps), null);
+  const rec = newMainSession({ now: T0, uuid: () => UUID });
+  const saved = saveMainSession("/agent", rec, deps);
+  assert.deepEqual(saved, { ok: true });
+  assert.ok(disk[join("/agent", "state", "session", "main-session.json")]);
+  assert.deepEqual(loadMainSession("/agent", deps), rec);
+});
+
+test("saveMainSession: a failing writer is a returned error, not a throw", () => {
+  const res = saveMainSession("/agent", newMainSession({ now: T0, uuid: () => UUID }), {
+    writeJsonAtomic: () => { throw new Error("EROFS"); },
+  });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /EROFS/);
+});
+
+test("agentFirstName: lower-cased firstName from config/agent.json; agent.ts, then the dir name minus -ai, as generate-plists.sh does", () => {
+  const fs = (files) => ({ readFileSync: (p) => { if (!(p in files)) { const e = new Error(`ENOENT ${p}`); e.code = "ENOENT"; throw e; } return files[p]; } });
+  const J = join("/Users/o/ravi-ai", "config", "agent.json");
+  const T = join("/Users/o/ravi-ai", "config", "agent.ts");
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"Olivia"}' })), "olivia");
+  // NOT slugged: the plist generator lower-cases only, and the label, the
+  // lock, the mux and the session name must agree on one derivation.
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"Jean Luc"}' })), "jean luc");
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"José"}' })), "josé");
+  // Fallbacks in the generator's order: agent.ts inline literal, then the directory.
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [T]: "export const AGENT = { firstName: 'Priya', lastName: 'T' };\n" })), "priya");
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [T]: "interface A { firstName: string; }\n" })), "ravi", "a type-only firstName is not a value");
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: '{"firstName":"UNCONFIGURED"}' })), "ravi");
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({ [J]: "{" })), "ravi");
+  assert.equal(agentFirstName("/Users/o/ravi-ai", fs({})), "ravi");
+  assert.equal(agentFirstName("/Users/o/sam", fs({})), "sam");
+  // Blank everywhere (no usable dir name either) → "agent".
+  assert.equal(agentFirstName("/", fs({ [join("/", "config", "agent.json")]: '{"firstName":"  "}' })), "agent");
+});
+
+test("agentFirstName agrees with generate-plists.sh's derivation, run verbatim from the script (cross-pin)", () => {
+  const script = readFileSync(resolve(__dirname, "..", "..", "scripts", "local-triggers", "generate-plists.sh"), "utf8");
+  const start = script.indexOf('AGENT_JSON="$AGENT_DIR/config/agent.json"');
+  const end = script.indexOf("AGENT_UPPER=");
+  assert.ok(start > 0 && end > start, "generate-plists.sh derivation block markers moved — update this cross-pin AND agentFirstName together");
+  const block = script.slice(start, end);
+  const shellFirst = (dir) => {
+    const r = spawnSync("/bin/bash", ["-c", `AGENT_DIR=${JSON.stringify(dir)}\n${block}\nprintf '%s' "$AGENT_FIRST"`], { encoding: "utf8", env: { PATH: "/usr/bin:/bin", LANG: "en_US.UTF-8", LC_ALL: "en_US.UTF-8" } });
+    assert.equal(r.status, 0, r.stderr);
+    return r.stdout;
+  };
+  const cases = [
+    ["ravi-ai", { json: { firstName: "Olivia" } }],
+    ["ravi-ai", { json: { firstName: "Jean Luc" } }],
+    ["ravi-ai", { json: { firstName: "José" } }],
+    ["ravi-ai", { json: { firstName: "UNCONFIGURED" } }],
+    ["ravi-ai", { ts: "export const AGENT = { firstName: 'Priya', lastName: 'T' };\n" }],
+    ["ravi-ai", { ts: "interface A { firstName: string; }\n" }],
+    ["sam-ai", {}],
+    ["kai", { json: {} }],
+    ["Ravi-ai", {}], // the generator does NOT lower-case the directory fallback
+  ];
+  for (const [dirName, fx] of cases) {
+    const base = mkdtempSync(join(tmpdir(), "maestro-first-"));
+    const dir = join(base, dirName);
+    mkdirSync(join(dir, "config"), { recursive: true });
+    if (fx.json) writeFileSync(join(dir, "config", "agent.json"), JSON.stringify(fx.json));
+    if (fx.ts) writeFileSync(join(dir, "config", "agent.ts"), fx.ts);
+    try {
+      assert.equal(agentFirstName(dir), shellFirst(dir), `${dirName} ${JSON.stringify(fx)}`);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+});
+
+test("muxSessionName / mainSessionName", () => {
+  assert.equal(muxSessionName("olivia"), "maestro-olivia");
+  assert.equal(mainSessionName("olivia"), "olivia-main");
+});
+
+test("launchMode: a never-launched id starts fresh; a launched id resumes; resume:false always starts fresh", () => {
+  const fresh = newMainSession({ now: T0, uuid: () => UUID });
+  assert.equal(launchMode(fresh, { resume: true }), "session-id");
+  const launched = recordLaunch(fresh, { now: T0 });
+  assert.equal(launched.resumes, 1);
+  assert.equal(launched.lastLaunchAt, "2026-09-08T10:00:00.000Z");
+  assert.equal(launchMode(launched, { resume: true }), "resume");
+  assert.equal(launchMode(launched, { resume: false }), "session-id");
+  // recordLaunch is pure — the input is untouched.
+  assert.equal(fresh.resumes, 0);
+});
+
+test("rotationDecision: non-zero exit inside the failure window on a resume → rotate", () => {
+  const rec = { sessionId: UUID, createdAt: "x", resumes: 2, rotations: [] };
+  const d = rotationDecision({ record: rec, mode: "resume", exitCode: 1, startedAt: T0, endedAt: T0 + 5_000, now: T0 + 5_000 });
+  assert.equal(d.action, "rotate");
+});
+
+test("rotationDecision: a clean end, a long-lived session, or a fresh-id launch → relaunch (exit 75)", () => {
+  const rec = { sessionId: UUID, createdAt: "x", resumes: 2, rotations: [] };
+  const base = { record: rec, startedAt: T0, now: T0 + 5_000 };
+  assert.equal(rotationDecision({ ...base, mode: "resume", exitCode: 0, endedAt: T0 + 5_000 }).action, "relaunch");
+  assert.equal(rotationDecision({ ...base, mode: "resume", exitCode: 1, endedAt: T0 + FAILURE_WINDOW_MS + 1, now: T0 + FAILURE_WINDOW_MS + 1 }).action, "relaunch");
+  assert.equal(rotationDecision({ ...base, mode: "session-id", exitCode: 1, endedAt: T0 + 5_000 }).action, "relaunch");
+});
+
+test("rotationDecision: an unknown exit code inside the window counts as a failure (fail-safe toward rotation)", () => {
+  const rec = { sessionId: UUID, createdAt: "x", resumes: 1, rotations: [] };
+  const d = rotationDecision({ record: rec, mode: "resume", exitCode: null, startedAt: T0, endedAt: T0 + 1_000, now: T0 + 1_000 });
+  assert.equal(d.action, "rotate");
+});
+
+test("rotationDecision: more than MAX_ROTATIONS_PER_HOUR in the last hour → backoff", () => {
+  const recent = Array.from({ length: MAX_ROTATIONS_PER_HOUR }, (_, i) => new Date(T0 - (i + 1) * 60_000).toISOString());
+  const rec = { sessionId: UUID, createdAt: "x", resumes: 1, rotations: recent };
+  const d = rotationDecision({ record: rec, mode: "resume", exitCode: 1, startedAt: T0, endedAt: T0 + 1_000, now: T0 + 1_000 });
+  assert.equal(d.action, "backoff");
+  assert.equal(d.sleepMs, BACKOFF_MS);
+  // Rotations older than an hour no longer count.
+  const old = recent.map((iso) => new Date(Date.parse(iso) - 3_600_000).toISOString());
+  const d2 = rotationDecision({ record: { ...rec, rotations: old }, mode: "resume", exitCode: 1, startedAt: T0, endedAt: T0 + 1_000, now: T0 + 1_000 });
+  assert.equal(d2.action, "rotate");
+});
+
+test("rotateMainSession: fresh id, zero resumes, rotation stamped and pruned to the last hour", () => {
+  const rec = { sessionId: UUID, createdAt: "x", resumes: 4, rotations: [new Date(T0 - 2 * 3_600_000).toISOString()] };
+  const next = rotateMainSession(rec, { now: T0, uuid: () => "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee" });
+  assert.equal(next.sessionId, "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee");
+  assert.equal(next.resumes, 0);
+  assert.deepEqual(next.rotations, ["2026-09-08T10:00:00.000Z"]);
+  assert.equal(next.rotatedFrom, UUID);
+  assert.equal(rec.resumes, 4);
+});