@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/plugins/maestro-skills/skills/main-session.md

@@ -31,6 +31,10 @@ a slower reply, never a dropped one.
    counts open handoffs and board items from `state/org/board-mine.json`, the
    daemon's five-minute cache — when that file is missing the count is 0 and
    you run `maestro board mine` yourself.
+   `maestro session status` (and the `session_status` tool) also carries
+   `currentWork` — what is running, queued and blocked across your sessions on
+   this machine; a "what are you doing right now?" is answered from that, not
+   from memory.
 
 3. Drain what is already waiting: `maestro inbox list --new`, then
    `maestro session handoffs` — anything there arrived while you were down.
@@ -43,12 +47,14 @@ Each line is a JSON object with a `type`. Handle it in the turn it arrives.
 
 - `inbound` — `{id, surface, topic, from, channelId, threadId, preview, path}`.
   `maestro inbox show <id>` for the full item, then follow the
-  `inbound-triage` skill: reply now, or `maestro board track <id> --stage
-  accepted` + work it, or spawn a peer. Saying something BEFORE the answer is
-  the exception, not the rule — see that skill's one-interim rule. Claim it first
-  (`maestro inbox claim <id>`) so the daemon's sweep does not re-deliver it,
-  reply with `maestro inbox reply <id> --text "…"`, and close with
-  `maestro inbox done <id>`. The reply command is the reply lane: it runs the
+  `inbound-triage` skill: reply now, work it here, or spawn a peer. Saying
+  something BEFORE the answer is the exception, not the rule — see that skill's
+  one-interim rule. Claim it first (`maestro inbox claim <id>`) so the daemon's
+  sweep does not re-deliver it, reply with `maestro inbox reply <id> --text "…"`,
+  and close with `maestro inbox done <id>`. Those four commands ALSO write the
+  ask's board row — open, running, closed, channel tagged — so there is no
+  separate `board track` step to remember; the server's gate decides whether a
+  given ask earns a row at all. The reply command is the reply lane: it runs the
   outbound gate — banned phrases, disclosure, barriers and the persona check —
   in-process before anything is sent. In the agent directory the
   `messaging_send` tool is blocked by the repo's own hook; do not try to route
@@ -62,7 +68,12 @@ Each line is a JSON object with a `type`. Handle it in the turn it arrives.
   the old way, so ack promptly and never twice.
 - `directive` — `restart`: finish the current turn, then `maestro session
   restart` (the supervisor brings you back on the same session id).
-  `upgrade-available`: same, at the next idle moment. `daemon-stale`: the
+  `upgrade-available`: same, at the next idle moment. `daemon-unhealthy`:
+  NOT a restart cue — the hourly autoupdate is reporting the daemon unhealthy
+  on the version already installed (`detail.notice.reason` says why: crash
+  loop, fatal line, or the org rejecting its beat); there is nothing to
+  restart onto, so keep your context, tell your principal and run `maestro
+  doctor`. `daemon-stale`: the
   daemon has not beaten for 5 minutes; say so to your principal if it persists
   past a second event, and keep working — the feed still delivers what is on
   disk.

package/scaffold/config/collective.yaml

@@ -19,6 +19,13 @@ captureOn: [Stop, PreCompact]
 minTurnsToCapture: 2
 # Hard cap on cards distilled from a single session (anti-bloat + cost guard).
 maxCardsPerSession: 12
+# Machine-wide ceiling on capture workers doing model work at once. Each worker
+# runs one or two `claude --print` passes; the ceiling keeps a burst of session
+# ends from fanning out into unbounded model processes.
+captureMaxConcurrent: 2
+# How long a worker waits for a free slot before it gives up and records a
+# skipped capture (counter `collective.capture_skipped`, reason `no-slot`).
+captureQueueWaitMs: 30000
 # Repos/paths whose sessions must NOT contribute to memory (substring or glob,
 # matched against the session cwd). Client work, secrets, anything ring-fenced.
 # Information-barrier domains are always excluded regardless of this list.

package/scripts/ci/check-durable-write-seam.mjs

@@ -42,7 +42,7 @@
  * `eslint.config.mjs`/`authz-drift.test.ts` use in the Cohort repo.
  *
  * Set equality also makes this guard self-canarying: the register is non-empty,
- * so a regex broken by a refactor yields zero matches and fails LOUDLY as three
+ * so a regex broken by a refactor yields zero matches and fails LOUDLY as
  * stale entries, rather than passing vacuously.
  *
  * Pure, dependency-light: Node builtins only. ESM.
@@ -71,6 +71,8 @@ export const SANCTIONED_DIRECT_WRITES = {
     "acquireScheduleLock: reclaim of a lock already proven stale by mtime; must land in place under the same name.",
   "lib/cadence-bus.mjs:328":
     "acquireScheduleLock: second O_EXCL attempt after the stale holder vanished.",
+  "lib/collective/capture-slots.mjs:152":
+    "tryAcquireLock: O_EXCL create of a capture slot/session lock (the machine-wide capture ceiling). A lock published by rename is not a lock — two workers could both hold one slot.",
 };
 
 /** Argument spellings that are already safe and must never be flagged. */

package/scripts/ci/check-tarball-fidelity.mjs

@@ -16,6 +16,12 @@
  *      pack/install; cf. the broken `validate_outbound.py` cross-tenant link).
  *   3. Requireability — the package main (exports["."], default lib/index.js)
  *      is present in the extracted tree, so a consumer's `import` resolves.
+ *   4. No tests or fixtures (CF-15) — `*.test.mjs`, `fixtures/`, `test-fixtures/`,
+ *      `test/` and the replay examples are negated in files[] and must not ship;
+ *      every relative import/require/`new URL(…, import.meta.url)` in the
+ *      packaged JS that names a file in the source tree names a packaged file;
+ *      and every exports[] module and lib/**\/index imports from the extracted
+ *      tarball (with the source tree's node_modules linked in after the walk).
  *
  * This is a SLOW check (it shells out to `npm pack` and `tar`), so it is wired
  * as its own opt-in npm script (`npm run test:pack`) and is NOT part of the
@@ -37,6 +43,7 @@ import {
   readdirSync,
   lstatSync,
   existsSync,
+  symlinkSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -50,8 +57,98 @@ export const FORBIDDEN_PATTERNS = [
   { label: "python bytecode (*.pyc)", re: /\.pyc$/ },
   { label: "python bytecode (*.pyo)", re: /\.pyo$/ },
   { label: "bytecode cache dir (__pycache__)", re: /(^|\/)__pycache__(\/|$)/ },
+  // CF-15 (W5): tests and their fixtures are not runtime; package.json files[] negates them.
+  { label: "test file (*.test.mjs / *.test.js)", re: /\.test\.(mjs|js|cjs)$/ },
+  { label: "test fixture directory", re: /(^|\/)(fixtures|test-fixtures|__fixtures__)\// },
+  { label: "test directory (test/)", re: /^test\// },
+  { label: "eval example fixtures", re: /^scripts\/eval\/replay\/examples\// },
 ];
 
+/**
+ * Relative module and file references in a JS source: static `import`/`export … from`,
+ * literal `import("…")` and `require("…")`, and `new URL("…", import.meta.url)` naming a
+ * file (with an extension). Pure.
+ * @param {string} source
+ * @returns {string[]} the relative specifiers, as written
+ */
+export function relativeReferences(source) {
+  const out = new Set();
+  const patterns = [
+    /\b(?:import|export)\s[^'"`;]*?\bfrom\s*["'](\.{1,2}\/[^"']+)["']/g,
+    /\bimport\s*["'](\.{1,2}\/[^"']+)["']/g,
+    /\bimport\(\s*["'](\.{1,2}\/[^"']+)["']\s*\)/g,
+    /\brequire\(\s*["'](\.{1,2}\/[^"']+)["']\s*\)/g,
+    /\bnew URL\(\s*["'](\.{1,2}\/[^"']*\.[A-Za-z0-9]+)["']\s*,\s*import\.meta\.url\s*\)/g,
+  ];
+  for (const re of patterns) for (const m of source.matchAll(re)) out.add(m[1]);
+  return [...out];
+}
+
+/**
+ * Every relative reference in the packaged JS that resolves to a file present in
+ * the source tree but absent from the tarball — a runtime path the packaging
+ * cut off. References that do not resolve in the source tree either (optional,
+ * generated or seat-local files) are not a packaging fault and are not reported.
+ * Comment lines are skipped. Pure over its inputs.
+ * @param {{files:string[], read:(rel:string)=>string, existsInSource:(rel:string)=>boolean}} p
+ * @returns {Array<{file:string, ref:string, target:string}>}
+ */
+export function brokenPackagedReferences({ files, read, existsInSource }) {
+  const shipped = new Set(files);
+  const broken = [];
+  for (const file of files) {
+    if (!/\.(mjs|js|cjs)$/.test(file)) continue;
+    const source = read(file)
+      .split("\n")
+      .filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l))
+      .join("\n");
+    for (const ref of relativeReferences(source)) {
+      const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), ref));
+      if (shipped.has(target) || !existsInSource(target)) continue;
+      broken.push({ file, ref, target });
+    }
+  }
+  return broken;
+}
+
+/**
+ * The modules a consumer (or the CLI) imports by name: every exports[] target
+ * that is JavaScript, and every lib/**\/index.(mjs|js). Pure.
+ * @param {object} pkg @param {string[]} files
+ */
+export function smokeImportTargets(pkg, files) {
+  const fromExports = Object.values((pkg && pkg.exports) || {})
+    .map((v) => (typeof v === "string" ? v : v && (v.import || v.default)))
+    .filter((v) => typeof v === "string" && /\.(mjs|js)$/.test(v))
+    .map((v) => v.replace(/^\.\//, ""));
+  const indexes = files.filter((f) => /^lib\/(.+\/)?index\.(mjs|js)$/.test(f));
+  return [...new Set([...fromExports, ...indexes])].sort();
+}
+
+/**
+ * Import each module in a child node process run in `root`; returns the ones that
+ * failed, with the first line of the error. Bounded by `timeoutMs`.
+ * @param {string} root @param {string[]} modules @param {number} [timeoutMs]
+ * @returns {Array<{module:string, error:string}>}
+ */
+export function smokeImport(root, modules, timeoutMs = 180_000) {
+  const script = [
+    "const mods = JSON.parse(process.argv[1]);",
+    "const failed = [];",
+    "for (const m of mods) { try { await import(new URL(m, 'file://' + process.cwd() + '/').href); } catch (e) { failed.push({ module: m, error: String((e && e.message) || e).split('\\n')[0] }); } }",
+    "process.stdout.write(JSON.stringify(failed));",
+    "process.exit(0);",
+  ].join("\n");
+  const env = { PATH: process.env.PATH || "/usr/bin:/bin", HOME: mkdtempSync(path.join(tmpdir(), "maestro-pack-home-")), NODE_ENV: "production" };
+  try {
+    const out = execFileSync(process.execPath, ["--input-type=module", "-e", script, JSON.stringify(modules)], { cwd: root, env, encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+    const last = out.trim().split("\n").pop() || "[]";
+    return JSON.parse(last);
+  } finally {
+    try { rmSync(env.HOME, { recursive: true, force: true }); } catch { /* */ }
+  }
+}
+
 /**
  * The "main" file a consumer's bare `import "@cohortapp/agent-sdk"` resolves to.
  * Falls back to lib/index.js (the documented default) when exports["."] is odd.
@@ -146,9 +243,11 @@ export function checkTarball(opts = {}) {
 
     // 4) Completeness — every files[] entry must be represented. A directory
     //    entry (e.g. "lib/") is satisfied by any packaged path beneath it; a
-    //    file entry must appear verbatim.
+    //    file entry must appear verbatim. A negation ("!**/*.test.mjs") removes
+    //    paths rather than declaring them (CF-15), so it has nothing to find.
     const missing = [];
     for (const decl of filesAllowlist) {
+      if (typeof decl !== "string" || decl.startsWith("!")) continue;
       const norm = decl.replace(/^\.\//, "").replace(/\/+$/, "");
       const asDirPrefix = norm + "/";
       const present = filePaths.some(
@@ -162,12 +261,37 @@ export function checkTarball(opts = {}) {
       missing.push(`${mainEntry} (package main / exports["."])`);
     }
 
+    // 6) CF-15: no packaged module points at a file the packaging left out.
+    const broken = brokenPackagedReferences({
+      files: filePaths,
+      read: (rel) => readFileSync(path.join(pkgRoot, rel), "utf8"),
+      existsInSource: (rel) => existsSync(path.join(cwd, rel)),
+    });
+    for (const b of broken) missing.push(`${b.target} (referenced as "${b.ref}" by ${b.file}, excluded from the tarball)`);
+
+    // 7) CF-15: every exported entry and lib/**/index imports from the extracted
+    //    tarball (dependencies from the source tree's node_modules). A module that
+    //    also fails from the source tree is not a packaging fault.
+    let smoked = 0;
+    if (opts.smoke !== false) {
+      const targets = smokeImportTargets(pkg, filePaths);
+      const sourceModules = path.join(cwd, "node_modules");
+      if (existsSync(sourceModules)) symlinkSync(sourceModules, path.join(pkgRoot, "node_modules"), "dir");
+      const failedPacked = smokeImport(pkgRoot, targets);
+      const failedSource = failedPacked.length > 0 ? new Set(smokeImport(cwd, failedPacked.map((f) => f.module)).map((f) => f.module)) : new Set();
+      for (const f of failedPacked) {
+        if (!failedSource.has(f.module)) missing.push(`${f.module} (does not import from the tarball: ${f.error})`);
+      }
+      smoked = targets.length;
+    }
+
     return {
       ok: offenders.length === 0 && missing.length === 0,
       offenders,
       missing,
       tarballFiles: filePaths.length,
       mainEntry,
+      smoked,
     };
   } finally {
     try { rmSync(work, { recursive: true, force: true }); } catch { /* */ }
@@ -184,7 +308,7 @@ export async function run(cwd = REPO_ROOT) {
     return 2;
   }
   if (res.ok) {
-    console.log(`check-tarball-fidelity: OK (${res.tarballFiles} files; main "${res.mainEntry}" present; no node_modules/.pyc/symlinks)`);
+    console.log(`check-tarball-fidelity: OK (${res.tarballFiles} files; main "${res.mainEntry}" present; no node_modules/.pyc/symlinks/tests/fixtures; every relative reference resolves; ${res.smoked} entry modules import from the tarball)`);
     return 0;
   }
   if (res.missing.length) {

package/scripts/ci/run-tests.mjs

@@ -10,24 +10,31 @@
  *
  * Node builtins only (maestro is "type":"module", near-zero-dep by design).
  *
- * Usage: `node scripts/ci/run-tests.mjs`
+ * Usage: `node scripts/ci/run-tests.mjs [--list]`
  *   exit 0 → all tests passed; non-zero → at least one failed (or none found).
+ *   `--list` prints the discovered files and runs nothing. It exists so that
+ *   "what does the suite cover?" has ONE answer. `package.json` used to answer
+ *   it a second time with a hand-enumerated `test:list`, which had drifted to
+ *   46 of 82 files by the time an audit caught it (L25) and was still missing
+ *   newly added suites afterwards — a second source of truth about coverage
+ *   that lies is worse than none, because it reads like an inventory.
  *
  * @module scripts/ci/run-tests
  */
 
 import { readdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 
 const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const ROOTS = ["lib", "scripts", "bin", "services"];
+const ROOTS = ["lib", "scripts", "bin", "services", "test"];
 const SKIP_DIRS = new Set(["node_modules", ".git", "state", "logs", "audit"]);
 
 /**
- * Recursively collect `*.test.mjs` files under `dir` (absolute), returning
- * paths relative to REPO_ROOT for stable, readable output.
+ * Recursively collect `*.test.mjs` files under `dir`, returning ABSOLUTE
+ * paths — `node --test` is spawned with cwd REPO_ROOT, but absolute paths
+ * survive a caller that is not. `--list` relativises them for readability.
  * @param {string} dir
  * @returns {string[]}
  */
@@ -50,22 +57,43 @@ function findTests(dir) {
   return out;
 }
 
-const files = ROOTS.flatMap((r) => findTests(join(REPO_ROOT, r))).sort();
-
-if (files.length === 0) {
-  console.error("run-tests: no *.test.mjs files found — refusing to report success.");
-  process.exit(1);
+/**
+ * Every test file the suite runs, repo-relative and sorted. The single source
+ * of truth about what `npm test` covers.
+ * @returns {string[]}
+ */
+export function discoverTests() {
+  return ROOTS.flatMap((r) => findTests(join(REPO_ROOT, r))).sort();
 }
 
-console.log(`run-tests: discovered ${files.length} test file(s).`);
+function main(argv) {
+  const files = discoverTests();
+
+  if (files.length === 0) {
+    console.error("run-tests: no *.test.mjs files found — refusing to report success.");
+    return 1;
+  }
+
+  if (argv.includes("--list")) {
+    for (const f of files) console.log(relative(REPO_ROOT, f));
+    console.error(`run-tests: ${files.length} test file(s) discovered (nothing was run).`);
+    return 0;
+  }
+
+  console.log(`run-tests: discovered ${files.length} test file(s).`);
 
-const result = spawnSync(process.execPath, ["--test", ...files], {
-  cwd: REPO_ROOT,
-  stdio: "inherit",
-});
+  const result = spawnSync(process.execPath, ["--test", ...files], {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    console.error("run-tests: failed to launch node --test:", result.error.message);
+    return 1;
+  }
+  return result.status ?? 1;
+}
 
-if (result.error) {
-  console.error("run-tests: failed to launch node --test:", result.error.message);
-  process.exit(1);
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
 }
-process.exit(result.status ?? 1);

package/scripts/cohort-llm/api-key-helper.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * scripts/cohort-llm/api-key-helper.mjs — Claude Code `apiKeyHelper` for a
+ * seat retargeted to cohort-llm (the internal "Path B" testbed, design C1).
+ *
+ * Claude Code runs this in /bin/sh and sends stdout as the request credential
+ * (public docs, code.claude.com/docs/en/iam: `apiKeyHelper` ranks below
+ * ANTHROPIC_AUTH_TOKEN, so a cohort retarget carries NO auth token and lets this
+ * helper supply — and, every CLAUDE_CODE_API_KEY_HELPER_TTL_MS, refresh — the
+ * seat token for the whole life of a long session).
+ *
+ *   node scripts/cohort-llm/api-key-helper.mjs [--agent-root <dir>]
+ *
+ * stdout: exactly one fresh `cst_…` token and a newline. Nothing else ever goes
+ * to stdout — anything printed there would be sent as the credential.
+ * failure: exit 1 with one line on stderr naming the typed error. The token and
+ * the seat's key never appear on stderr.
+ *
+ * Key resolution: the cached token (state/cohort-llm/token.json) when it is
+ * before its refresh point; otherwise the seat's OrgApiKey from config/org.yaml,
+ * the environment, or the agent's .env (a retarget child's env is scrubbed of
+ * credentials, so the .env is the usual source here).
+ *
+ * @module scripts/cohort-llm/api-key-helper
+ */
+
+import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+import { seatTokenManager, redactSecrets, REJECTED_TOKEN_FP_ENV } from "../../lib/org/llm-token.mjs";
+
+/** @param {string[]} argv */
+export function parseHelperArgs(argv) {
+  const out = { agentRoot: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--agent-root") out.agentRoot = argv[++i] || null;
+    else if (a.startsWith("--agent-root=")) out.agentRoot = a.slice("--agent-root=".length) || null;
+  }
+  return out;
+}
+
+/**
+ * @param {object} [deps]
+ * @param {string[]} [deps.argv]
+ * @param {object} [deps.env]
+ * @param {{write:(s:string)=>unknown}} [deps.stdout]
+ * @param {{write:(s:string)=>unknown}} [deps.stderr]
+ * @param {typeof fetch} [deps.fetchImpl]
+ * @param {() => number} [deps.now]
+ * @param {object} [deps.cfg]
+ * @returns {Promise<number>} exit code
+ */
+export async function main(deps = {}) {
+  const env = deps.env || process.env;
+  const stdout = deps.stdout || process.stdout;
+  const stderr = deps.stderr || process.stderr;
+  const args = parseHelperArgs(deps.argv || process.argv.slice(2));
+  const agentRoot = resolve(args.agentRoot || env.AGENT_ROOT || env.AGENT_DIR || process.cwd());
+  try {
+    const manager = seatTokenManager({ agentRoot, env, cfg: deps.cfg, readDotEnv: true, fetchImpl: deps.fetchImpl, now: deps.now });
+    // The engine re-runs this helper after a 401 and names the refused token by
+    // fingerprint: the manager serves a replacement if one exists, else re-mints
+    // under its per-window cap. A plain run (TTL refresh) never forces a mint.
+    const rejectedFp = typeof env[REJECTED_TOKEN_FP_ENV] === "string" ? env[REJECTED_TOKEN_FP_ENV].trim() : "";
+    const r = await manager.getToken(rejectedFp ? { rejectedFp } : {});
+    if (r.ok && typeof r.token === "string" && r.token) {
+      stdout.write(`${r.token}\n`);
+      return 0;
+    }
+    const e = (r && r.error) || { code: "cohort_unavailable", message: "no token" };
+    stderr.write(`cohort-llm api-key-helper: ${e.code}: ${redactSecrets(e.message)}\n`);
+    return 1;
+  } catch (err) {
+    stderr.write(`cohort-llm api-key-helper: cohort_unavailable: ${redactSecrets(err && err.message ? err.message : err)}\n`);
+    return 1;
+  }
+}
+
+function isEntrypoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint()) {
+  process.exitCode = await main();
+}