@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/scripts/session/feed.test.mjs

@@ -0,0 +1,196 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, utimesSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+import { createFeed, parseFeedArgs } from "./feed.mjs";
+import { inboxItemToYaml } from "../poller/utils.mjs";
+import { newMainSession, saveMainSession } from "../../lib/session/identity.mjs";
+import { sessionPaths } from "../../lib/session/config.mjs";
+import { parseHeartbeat } from "../../lib/session/liveness.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FEED = resolve(__dirname, "feed.mjs");
+const T0 = Date.parse("2026-09-08T10:00:00Z");
+const UUID = "11111111-2222-4333-8444-555555555555";
+
+function makeAgent() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-feed-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Olivia" }));
+  saveMainSession(root, { ...newMainSession({ now: T0, uuid: () => UUID }), resumes: 1 });
+  return root;
+}
+
+function writeItem(root, id, over = {}) {
+  const dir = join(root, "state", "inbox", "cohort");
+  mkdirSync(dir, { recursive: true });
+  const p = join(dir, `2026-09-08T09-59-00-000Z-${id}.yaml`);
+  writeFileSync(p, inboxItemToYaml({
+    id, service: "cohort", channel: "dm/casey", channel_id: "ch_1", sender: "Casey", sender_privilege: "ceo",
+    timestamp: "2026-09-08T09:59:00.000Z", subject: "Cohort message", content: `hello ${id}`, thread_id: "", raw_ref: `cohort:ch_1:${id}`, ...over,
+  }));
+  return p;
+}
+
+test("parseFeedArgs", () => {
+  assert.deepEqual(parseFeedArgs([]), { once: false });
+  assert.deepEqual(parseFeedArgs(["--once"]), { once: true });
+});
+
+test("createFeed: tick emits new inbox items + handoffs + directives as objects, persists the seen-set, and beats", () => {
+  const root = makeAgent();
+  try {
+    const itemPath = writeItem(root, "m1");
+    const paths = sessionPaths(root);
+    mkdirSync(paths.handoffsDir, { recursive: true });
+    writeFileSync(join(paths.handoffsDir, "t-1.json"), JSON.stringify({ tickId: "t-1", cadence: "morning-brief", promptPath: "/p", enqueuedAt: "x" }));
+    writeFileSync(paths.restartRequestedFile, "");
+
+    const lines = [];
+    let t = T0;
+    const feed = createFeed({ agentRoot: root, config: { services: ["cohort"] }, now: () => t, emit: (o) => lines.push(o), pid: 4242, ppid: 4241, pidAlive: () => false });
+    feed.tick();
+    assert.deepEqual(lines.map((l) => [l.type, l.id || l.action]), [["inbound", "m1"], ["handoff", "t-1"], ["directive", "restart"], ["directive", "daemon-stale"]]);
+    const inbound = lines[0];
+    assert.equal(inbound.path, itemPath);
+    assert.equal(inbound.preview, "hello m1");
+    assert.equal(inbound.channelName, "dm/casey");
+    assert.ok(existsSync(paths.feedSeenFile));
+    const seen = JSON.parse(readFileSync(paths.feedSeenFile, "utf8"));
+    assert.equal(seen.seq, 4);
+
+    // Heartbeat carries the stable session id and the <first>-main name.
+    feed.beat();
+    const hb = parseHeartbeat(readFileSync(paths.heartbeatFile, "utf8"));
+    assert.equal(hb.pid, 4242);
+    assert.equal(hb.ppid, 4241);
+    assert.equal(hb.sessionId, UUID);
+    assert.equal(hb.name, "olivia-main");
+    assert.equal(hb.ts, "2026-09-08T10:00:00.000Z");
+
+    // Second tick: nothing new; a second feed instance (Monitor restart) replays nothing either.
+    t += 1000;
+    lines.length = 0;
+    feed.tick();
+    assert.deepEqual(lines, []);
+    const feed2 = createFeed({ agentRoot: root, config: { services: ["cohort"] }, now: () => t, emit: (o) => lines.push(o), pidAlive: () => false });
+    feed2.tick();
+    assert.deepEqual(lines, []);
+
+    // A new item and a daemon coming alive (fresh health file) — only the item is emitted.
+    writeItem(root, "m2");
+    mkdirSync(dirname(paths.daemonHealthFile), { recursive: true });
+    writeFileSync(paths.daemonHealthFile, "updated: now\n");
+    utimesSync(paths.daemonHealthFile, new Date(t), new Date(t));
+    feed2.tick();
+    assert.deepEqual(lines.map((l) => [l.type, l.id]), [["inbound", "m2"]]);
+    assert.equal(lines[0].seq, 5);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("createFeed: claimed (.dispatched) and processed items are not emitted; a re-opened item is", () => {
+  const root = makeAgent();
+  try {
+    const p = writeItem(root, "m1");
+    const lines = [];
+    const feed = createFeed({ agentRoot: root, config: { services: ["cohort"] }, now: () => T0, emit: (o) => lines.push(o), pidAlive: () => true });
+    feed.tick();
+    assert.equal(lines.filter((l) => l.type === "inbound").length, 1);
+    // Claimed by the session → renamed; nothing re-emitted.
+    const claimed = p + ".dispatched";
+    writeFileSync(claimed, readFileSync(p));
+    rmSync(p);
+    lines.length = 0;
+    feed.tick();
+    assert.deepEqual(lines, []);
+    // Assurance sweep re-opens it → re-emitted once.
+    writeFileSync(p, readFileSync(claimed));
+    rmSync(claimed);
+    feed.tick();
+    assert.equal(lines.length, 1);
+    assert.equal(lines[0].id, "m1");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("createFeed: an already-seen inbox item is stat-only — its body is not re-read every tick (O(backlog) reads)", () => {
+  const root = makeAgent();
+  try {
+    for (let i = 0; i < 5; i++) writeItem(root, `m${i}`);
+    const reads = [];
+    const fs = { readFileSync: (p, enc) => { reads.push(String(p)); return readFileSync(p, enc); } };
+    const lines = [];
+    const feed = createFeed({ agentRoot: root, config: { services: ["cohort"] }, now: () => T0, emit: (o) => lines.push(o), pidAlive: () => true, fs });
+    feed.tick();
+    assert.equal(lines.filter((l) => l.type === "inbound").length, 5);
+    const firstPassBodies = reads.filter((p) => p.includes("/state/inbox/cohort/")).length;
+    assert.equal(firstPassBodies, 5);
+    reads.length = 0;
+    feed.tick();
+    feed.tick();
+    assert.equal(reads.filter((p) => p.includes("/state/inbox/cohort/")).length, 0, "seen items must not be read again");
+    // A new item lands: only it is read.
+    writeItem(root, "m9");
+    reads.length = 0;
+    feed.tick();
+    assert.deepEqual(reads.filter((p) => p.includes("/state/inbox/cohort/")).map((p) => basename(p)), ["2026-09-08T09-59-00-000Z-m9.yaml"]);
+    assert.equal(lines.filter((l) => l.type === "inbound").length, 6);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("createFeed: tickSafely never throws — a throwing emitter (closed stdout) costs one tick and a stderr line", () => {
+  const root = makeAgent();
+  try {
+    writeItem(root, "m1");
+    const logs = [];
+    const feed = createFeed({ agentRoot: root, config: { services: ["cohort"] }, now: () => T0, emit: () => { throw new Error("EPIPE"); }, log: (l) => logs.push(l), pidAlive: () => true });
+    assert.throws(() => feed.tick(), /EPIPE/);
+    assert.deepEqual(feed.tickSafely(), []);
+    assert.ok(logs.some((l) => /tick failed/.test(l) && /EPIPE/.test(l)));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("createFeed: a missing inbox dir, a missing daemon, a missing main-session file — all fail open", () => {
+  const root = mkdtempSync(join(tmpdir(), "maestro-feed-bare-"));
+  try {
+    const lines = [];
+    const feed = createFeed({ agentRoot: root, config: { services: ["cohort", "slack"] }, now: () => T0, emit: (o) => lines.push(o), pidAlive: () => false });
+    assert.doesNotThrow(() => feed.tick());
+    assert.deepEqual(lines.map((l) => l.action), ["daemon-stale"]);
+    assert.deepEqual(feed.beat(), { ok: true });
+    const hb = parseHeartbeat(readFileSync(sessionPaths(root).heartbeatFile, "utf8"));
+    assert.equal(hb.sessionId, null);
+    // No config at all → the directory-name derivation the plist generator uses.
+    assert.equal(hb.name, `${basename(root)}-main`);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feed.mjs --once: stdout is JSON lines only, nothing else", () => {
+  const root = makeAgent();
+  try {
+    writeItem(root, "m1");
+    const r = spawnSync(process.execPath, [FEED, "--once"], { env: { ...process.env, AGENT_ROOT: root, AGENT_DIR: root }, encoding: "utf8", timeout: 20_000 });
+    assert.equal(r.status, 0, r.stderr);
+    const lines = r.stdout.split("\n").filter(Boolean);
+    assert.ok(lines.length >= 1, "expected at least the inbound line");
+    const parsed = lines.map((l) => JSON.parse(l));
+    assert.equal(parsed[0].type, "inbound");
+    assert.equal(parsed[0].id, "m1");
+    assert.ok(existsSync(sessionPaths(root).heartbeatFile), "heartbeat written by --once");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/scripts/session/supervisor-sh.test.mjs

@@ -0,0 +1,218 @@
+/**
+ * supervisor-sh.test.mjs — coverage for scripts/session/supervisor.sh.
+ *
+ * Builds a fixture agent root, points NODE_BIN at a stub that dumps its argv
+ * and environment, runs the wrapper, and asserts what reached the "node"
+ * process: AGENT_ROOT, HOME, the PATH prefix, the .env variables (quotes
+ * stripped, malformed lines skipped, existing env not clobbered), and the
+ * supervisor.mjs entrypoint. Also pins that the wrapper's exit code is the
+ * child's (exec) and that the log lands under logs/session/.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, copyFileSync, chmodSync, rmSync, realpathSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WRAPPER_SRC = resolve(__dirname, "supervisor.sh");
+
+function makeAgent() {
+  // The wrapper resolves AGENT_ROOT with `pwd -P`, so compare against the real path (/var → /private/var on macOS).
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "maestro-supervisor-sh-")));
+  mkdirSync(join(root, "scripts", "session"), { recursive: true });
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ firstName: "Olivia" }));
+  copyFileSync(WRAPPER_SRC, join(root, "scripts", "session", "supervisor.sh"));
+  chmodSync(join(root, "scripts", "session", "supervisor.sh"), 0o755);
+  writeFileSync(join(root, "scripts", "session", "supervisor.mjs"), "// stub entrypoint (never run: NODE_BIN is a stub)\n");
+  mkdirSync(join(root, "bin"), { recursive: true });
+  const stub = join(root, "bin", "node");
+  writeFileSync(stub, [
+    "#!/bin/sh",
+    'echo "ARGV:$*"',
+    "env | grep -E '^(AGENT_ROOT|AGENT_DIR|HOME|USER|PATH|MAESTRO_TEST_[A-Z_]*)=' | sort",
+    'exit "${STUB_EXIT:-0}"',
+    "",
+  ].join("\n"));
+  chmodSync(stub, 0o755);
+  return { root, stub };
+}
+
+function runWrapper(root, stub, extraEnv = {}) {
+  const env = { PATH: "/usr/bin:/bin", NODE_BIN: stub, ...extraEnv };
+  const r = spawnSync("/bin/bash", [join(root, "scripts", "session", "supervisor.sh"), "--flag", "x"], { env, encoding: "utf8", timeout: 20_000 });
+  const logDir = join(root, "logs", "session");
+  let log = "";
+  try {
+    const files = readdirSync(logDir).filter((f) => /^supervisor-\d{4}-\d{2}-\d{2}\.log$/.test(f));
+    log = files.map((f) => readFileSync(join(logDir, f), "utf8")).join("");
+  } catch { /* no log dir → assertions below fail loudly */ }
+  return { r, log };
+}
+
+test("supervisor.sh parses under bash -n", () => {
+  const r = spawnSync("/bin/bash", ["-n", WRAPPER_SRC], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+});
+
+test("wrapper sets AGENT_ROOT/HOME/PATH, sources .env safely, execs supervisor.mjs and logs under logs/session", () => {
+  const { root, stub } = makeAgent();
+  try {
+    writeFileSync(join(root, ".env"), [
+      "# comment line",
+      "",
+      "MAESTRO_TEST_PLAIN=plain",
+      'MAESTRO_TEST_QUOTED="has spaces and = signs"',
+      "MAESTRO_TEST_SINGLE='single quoted'",
+      "export MAESTRO_TEST_EXPORTED=exported",
+      "MAESTRO_TEST_PRESET=from-dotenv",
+      "this line is not a kv pair",
+      "BAD KEY=nope",
+      "MAESTRO_TEST_BAD-DASH=nope",
+      // dotenv semantics the daemon already relies on: an unquoted value ends
+      // at the first `#` and is trimmed; a quoted value keeps its `#`; a CRLF
+      // line (edited on Windows) must not leak a trailing \r into a token.
+      "MAESTRO_TEST_INLINE=value # trailing comment",
+      "MAESTRO_TEST_NOSPACE=abc#def",
+      "MAESTRO_TEST_TRAIL=spaced   ",
+      'MAESTRO_TEST_QHASH="keep # this"',
+      "MAESTRO_TEST_CRLF=windows\r",
+      "MAESTRO_TEST_CRLFQ=\"quoted windows\"\r",
+      "",
+    ].join("\n"));
+    const { r, log } = runWrapper(root, stub, { MAESTRO_TEST_PRESET: "from-shell", HOME: "/Users/fixture" });
+    assert.equal(r.status, 0, `${r.stdout}\n${r.stderr}`);
+    assert.equal(r.stdout, "", "wrapper must not write to its own stdout (everything goes to the log)");
+    // exec'd entrypoint + passthrough args
+    assert.match(log, new RegExp(`^ARGV:${join(root, "scripts", "session", "supervisor.mjs").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")} --flag x$`, "m"));
+    assert.match(log, new RegExp(`^AGENT_ROOT=${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "m"));
+    assert.match(log, new RegExp(`^AGENT_DIR=${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "m"));
+    assert.match(log, /^HOME=\/Users\/fixture$/m);
+    assert.match(log, /^USER=.+$/m);
+    assert.match(log, /^PATH=\/Users\/fixture\/\.local\/bin:\/opt\/homebrew\/bin:\/opt\/homebrew\/sbin:\/usr\/local\/bin:\/usr\/bin:\/bin:\/usr\/sbin:\/sbin:\/usr\/bin:\/bin$/m);
+    // .env semantics
+    assert.match(log, /^MAESTRO_TEST_PLAIN=plain$/m);
+    assert.match(log, /^MAESTRO_TEST_QUOTED=has spaces and = signs$/m);
+    assert.match(log, /^MAESTRO_TEST_SINGLE=single quoted$/m);
+    assert.match(log, /^MAESTRO_TEST_EXPORTED=exported$/m);
+    assert.match(log, /^MAESTRO_TEST_PRESET=from-shell$/m, "an existing env var must win over .env");
+    assert.doesNotMatch(log, /MAESTRO_TEST_BAD/);
+    assert.doesNotMatch(log, /nope/);
+    assert.match(log, /^MAESTRO_TEST_INLINE=value$/m, "unquoted inline comment must be stripped");
+    assert.match(log, /^MAESTRO_TEST_NOSPACE=abc$/m);
+    assert.match(log, /^MAESTRO_TEST_TRAIL=spaced$/m);
+    assert.match(log, /^MAESTRO_TEST_QHASH=keep # this$/m, "a quoted # is data");
+    assert.match(log, /^MAESTRO_TEST_CRLF=windows$/m, "CR from a CRLF line must not reach the value");
+    assert.match(log, /^MAESTRO_TEST_CRLFQ=quoted windows$/m);
+    assert.doesNotMatch(log, /\r/, "no carriage return anywhere in the child env");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("wrapper works with no .env at all and returns the supervisor's exit code (75)", () => {
+  const { root, stub } = makeAgent();
+  try {
+    const { r, log } = runWrapper(root, stub, { STUB_EXIT: "75" });
+    assert.equal(r.status, 75);
+    assert.match(log, /^ARGV:/m);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("under an emergency stop (.emergency-stop or state/EMERGENCY_STOP) the wrapper exits 0 without starting node — launchd's KeepAlive does not relaunch a clean exit", () => {
+  for (const marker of [".emergency-stop", join("state", "EMERGENCY_STOP")]) {
+    const { root, stub } = makeAgent();
+    try {
+      mkdirSync(join(root, "state"), { recursive: true });
+      writeFileSync(join(root, marker), "2026-09-09T00:00:00Z\n");
+      const { r, log } = runWrapper(root, stub);
+      assert.equal(r.status, 0, `${marker}: ${r.stderr}`);
+      assert.match(r.stderr, /emergency stop is active/, marker);
+      assert.match(r.stderr, /maestro session start/);
+      assert.ok(!/ARGV:/.test(log), `${marker}: node must not be started`);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+});
+
+test("wrapper exits 127 when no node can be found (candidate list overridden so the branch is deterministic)", () => {
+  const { root } = makeAgent();
+  try {
+    const r = spawnSync("/bin/bash", [join(root, "scripts", "session", "supervisor.sh")], {
+      env: {
+        PATH: "/usr/bin:/bin",
+        HOME: join(root, "nohome"), // no ~/.nvm here either
+        NODE_BIN: "/nonexistent/node",
+        MAESTRO_NODE_CANDIDATES: "/nonexistent/a/node:/nonexistent/b/node",
+      },
+      encoding: "utf8",
+      timeout: 20_000,
+    });
+    assert.equal(r.status, 127, `${r.stdout}\n${r.stderr}`);
+    assert.match(r.stderr, /could not find node/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("MAESTRO_NODE_CANDIDATES: the first executable candidate wins", () => {
+  const { root, stub } = makeAgent();
+  try {
+    const r = spawnSync("/bin/bash", [join(root, "scripts", "session", "supervisor.sh")], {
+      env: { PATH: "/usr/bin:/bin", HOME: join(root, "nohome"), MAESTRO_NODE_CANDIDATES: `/nonexistent/node:${stub}` },
+      encoding: "utf8",
+      timeout: 20_000,
+    });
+    assert.equal(r.status, 0, r.stderr);
+    const log = readdirSync(join(root, "logs", "session")).map((f) => readFileSync(join(root, "logs", "session", f), "utf8")).join("");
+    assert.match(log, /^ARGV:/m);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a preset AGENT_ROOT wins over the script's own location (the npm-global copy can serve an agent dir)", () => {
+  const pkg = makeAgent();   // where the wrapper lives (stands in for the global package)
+  const agent = makeAgent(); // the seat
+  try {
+    const r = spawnSync("/bin/bash", [join(pkg.root, "scripts", "session", "supervisor.sh")], {
+      env: { PATH: "/usr/bin:/bin", NODE_BIN: pkg.stub, AGENT_ROOT: agent.root },
+      encoding: "utf8",
+      timeout: 20_000,
+    });
+    assert.equal(r.status, 0, r.stderr);
+    const logDir = join(agent.root, "logs", "session");
+    const log = readdirSync(logDir).map((f) => readFileSync(join(logDir, f), "utf8")).join("");
+    const esc = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    assert.match(log, new RegExp(`^AGENT_ROOT=${esc(agent.root)}$`, "m"));
+    assert.match(log, new RegExp(`^ARGV:${esc(join(agent.root, "scripts", "session", "supervisor.mjs"))}$`, "m"));
+    assert.ok(!existsSync(join(pkg.root, "logs")), "nothing is written under the package dir");
+  } finally {
+    rmSync(pkg.root, { recursive: true, force: true });
+    rmSync(agent.root, { recursive: true, force: true });
+  }
+});
+
+test("wrapper refuses (exit 78, EX_CONFIG) when the resolved root is not an agent dir (no config/agent.json)", () => {
+  const { root, stub } = makeAgent();
+  try {
+    rmSync(join(root, "config", "agent.json"));
+    const r = spawnSync("/bin/bash", [join(root, "scripts", "session", "supervisor.sh")], {
+      env: { PATH: "/usr/bin:/bin", NODE_BIN: stub },
+      encoding: "utf8",
+      timeout: 20_000,
+    });
+    assert.equal(r.status, 78, `${r.stdout}\n${r.stderr}`);
+    assert.match(r.stderr, /not an agent directory/);
+    assert.ok(!existsSync(join(root, "logs")), "must not create logs/ or run node in a non-agent dir");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});