@cohortapp/agent-sdk 2.3.0 → 2.3.2

package/bin/maestro.mjs

@@ -9,6 +9,7 @@
  */
 
 import { resolve, join, dirname, relative, sep, basename } from "node:path";
+import { writeAgentPackageJson } from "../scripts/setup/generate-agent-package-json.mjs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import {
   mkdirSync,
@@ -23,6 +24,7 @@ import {
   openSync,
   readSync,
   closeSync,
+  realpathSync,
 } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -43,6 +45,23 @@ const MAESTRO_ROOT = resolve(__dirname, "..");
 const SCAFFOLD_DIR = join(MAESTRO_ROOT, "scaffold");
 const FRAMEWORK_FEATURES_PATH = join(MAESTRO_ROOT, "framework-features.json");
 
+/**
+ * This framework's own version, so a created agent PINS the version it was
+ * scaffolded from (`@cohortapp/agent-sdk: ^<version>`). That is what makes
+ * `npm update @cohortapp/agent-sdk` meaningful and makes per-agent drift
+ * measurable. Falls back to "*" rather than throwing — a missing version must
+ * never be the reason `create` fails.
+ */
+function readFrameworkVersion() {
+  try {
+    return JSON.parse(
+      readFileSync(join(MAESTRO_ROOT, "package.json"), "utf-8"),
+    ).version || "*";
+  } catch {
+    return "*";
+  }
+}
+
 // Plist architecture marker — must match the value emitted by
 // scripts/local-triggers/generate-plists.sh. Used by doctor + upgrade
 // migration to distinguish cadence-bus plists from the legacy
@@ -619,57 +638,26 @@ rubrics: []
 
   log("Generating package.json...");
 
-  const agentPackage = {
+  // The agent package.json is built by scripts/setup/generate-agent-package-json.mjs,
+  // NOT inline here. That module exists precisely because this inline shape had two
+  // distribution-breaking holes, and wiring it in was left as a follow-up that never
+  // landed — so every agent created since has shipped with them:
+  //
+  //   1. no dependency on @cohortapp/agent-sdk, making the documented upgrade path
+  //      (`npm update @cohortapp/agent-sdk`) a no-op and leaving `npx` to re-fetch
+  //      whatever is newest instead of the version the agent was created against;
+  //   2. no `js-yaml` / `better-sqlite3`, the framework's real runtime deps. They
+  //      are not hoisted transitively. The js-yaml gap is not cosmetic: loadOrgConfig
+  //      requires it to read config/org.yaml, so a freshly-created agent silently
+  //      failed to load its org enrolment, never joined the mesh, never beat, and
+  //      could not receive the `halt` kill switch — while looking healthy.
+  //
+  // Keeping ONE builder means that class of bug is fixed once, for create and for
+  // any later regeneration, instead of drifting between two copies.
+  writeAgentPackageJson(targetDir, {
     name: targetName,
-    version: "1.0.0",
-    description: "Maestro AI agent — configure with: maestro setup",
-    type: "module",
-    private: true,
-    scripts: {
-      "init-agent": "./scripts/setup/init-agent.sh",
-      "configure-macos": "sudo ./scripts/setup/configure-macos.sh",
-      "configure-macos:check": "./scripts/setup/configure-macos.sh --check",
-      daemon: "node scripts/daemon/maestro-daemon.mjs",
-      "cadence:enqueue": "node scripts/cadence/enqueue-cadence-tick.mjs",
-      "cadence:consume": "node scripts/daemon/cadence-consumer.mjs",
-      "cadence:status": "node scripts/cadence/cadence-status.mjs",
-      healthcheck: "./scripts/healthcheck.sh",
-      "emergency-stop": "./scripts/emergency-stop.sh",
-      resume: "./scripts/resume-operations.sh",
-      "pdf:memo": "node scripts/pdf-generation/build-document.mjs --template memo",
-      "pdf:board-pack": "node scripts/pdf-generation/build-document.mjs --template board-pack",
-      "pdf:letter": "node scripts/pdf-generation/build-document.mjs --template corporate-letter",
-      "pdf:investor": "node scripts/pdf-generation/build-document.mjs --template investor-letter",
-      "gen:illustration": "node scripts/media-generation/generate-assets.mjs --illustration",
-      "gen:video": "node scripts/media-generation/generate-assets.mjs --video",
-      "gen:all-missing": "node scripts/media-generation/generate-assets.mjs --all-missing",
-      "gen:list": "node scripts/media-generation/generate-assets.mjs --list",
-      "slack:events": "node scripts/slack-events-server.mjs",
-      "slack:events:start": "./scripts/slack-events-ctl.sh start",
-      "slack:events:stop": "./scripts/slack-events-ctl.sh stop",
-      "slack:events:status": "./scripts/slack-events-ctl.sh status",
-      upgrade: "npx @cohortapp/agent-sdk upgrade",
-      init: "npx @cohortapp/agent-sdk init",
-      doctor: "npx @cohortapp/agent-sdk doctor",
-    },
-    dependencies: {
-      "@google/genai": "^1.42.0",
-      dotenv: "^16.4.5",
-      execa: "^9.6.1",
-      imapflow: "^1.2.18",
-      mailparser: "^3.9.6",
-      openai: "^6.33.0",
-    },
-    devDependencies: {
-      sharp: "^0.34.5",
-      tsx: "^4.20.6",
-    },
-  };
-
-  writeFileSync(
-    join(targetDir, "package.json"),
-    JSON.stringify(agentPackage, null, 2) + "\n"
-  );
+    frameworkVersion: readFrameworkVersion(),
+  });
   ok("package.json");
 
   // ── Step 5: Copy .env.example and .gitignore ────────────────────────────
@@ -3511,6 +3499,22 @@ Upgrade workflow (existing agents):
 
 // Dispatch only when invoked as the CLI entrypoint — importing for tests must
 // not run any command (process.argv would be the test runner's argv).
-if (import.meta.url === `file://${process.argv[1]}`) {
+//
+// Both sides must be realpath-resolved file URLs. npm installs bins as symlinks
+// (node_modules/.bin/maestro -> ../@cohortapp/agent-sdk/bin/maestro.mjs) and
+// import.meta.url is already symlink-resolved, so comparing against a raw
+// argv[1] never matches and every installed invocation silently no-ops.
+// pathToFileURL (not `file://` + path) also keeps paths with spaces working.
+function isCliEntrypoint() {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(invoked)).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isCliEntrypoint()) {
   await main();
 }

package/lib/channels/inbox-item.mjs

@@ -167,6 +167,17 @@ export function eventToInboxItem(ev) {
     source: ev.ingest_source || ev.channel || "channel",
   };
 
+  // CONFIDENTIALITY SIGNALS. Carried through verbatim when the adapter resolved
+  // them (Slack's `channel_type` / an explicit `is_private`), and OMITTED
+  // otherwise — the daemon's outcome gate reads `is_private === false` as a
+  // positive "this source is public" assertion, so a default would forge one.
+  // Omission also keeps items without a signal byte-identical to today.
+  if (typeof ev.channel_type === "string" && ev.channel_type) {
+    item.channel_type = sanitizeYamlField(ev.channel_type);
+  }
+  if (typeof ev.is_private === "boolean") item.is_private = ev.is_private;
+  if (typeof ev.is_dm === "boolean") item.is_dm = ev.is_dm;
+
   // Only stamp `kind` when it's not the default. Existing message items must
   // remain byte-identical to what the Slack socket-mode writer produced before
   // this seam existed (it never wrote a `kind` field).
@@ -203,7 +214,16 @@ export function inboxItemToEvent(item) {
   // Reconstruct message_id from the inbox id (poller convention swaps "." → "-").
   const messageId = item.raw_ref ? (String(item.raw_ref).split(":").pop() || item.id) : item.id;
 
+  // Confidentiality signals round-trip only when present, so that
+  // eventToInboxItem(inboxItemToEvent(x)) stays a fixed point on x and an item
+  // that never carried a privacy verdict never acquires one here.
+  const privacy = {};
+  if (typeof item.channel_type === "string" && item.channel_type) privacy.channel_type = item.channel_type;
+  if (typeof item.is_private === "boolean") privacy.is_private = item.is_private;
+  if (typeof item.is_dm === "boolean") privacy.is_dm = item.is_dm;
+
   return {
+    ...privacy,
     channel,
     message_id: messageId,
     id: item.id,

package/lib/org/client.mjs

@@ -63,13 +63,31 @@ const DEFAULT_TIMEOUT_MS = 8000;
  * @returns {object}
  */
 export function loadOrgConfig(agentRoot) {
+  const p = join(agentRoot, "config", "org.yaml");
+  // Genuinely absent is not a fault: an un-enrolled agent has no org.yaml.
+  if (!existsSync(p)) return {};
   try {
-    const p = join(agentRoot, "config", "org.yaml");
-    if (!existsSync(p)) return {};
     const require = createRequire(import.meta.url);
     const yaml = require("js-yaml");
     return yaml.load(readFileSync(p, "utf8")) || {};
-  } catch {
+  } catch (err) {
+    // The file EXISTS but could not be read/parsed. Returning {} silently here
+    // is how an enrolled agent ends up quietly un-enrolled: `isEnabled({})` is
+    // false, so the org mesh no-ops, the daemon logs nothing, and the agent
+    // never beats or receives the kill switch. Observed in the wild — the
+    // scaffold's package.json omitted `js-yaml`, so this require() threw on
+    // every freshly-created agent and the org integration was simply off.
+    //
+    // Still fail-open (callers depend on never throwing), but never silent.
+    const why = /Cannot find module 'js-yaml'/.test(String(err && err.message))
+      ? "js-yaml is not installed — run `npm install` (it is a required runtime dep)"
+      : String(err && err.message);
+    try {
+      console.warn(
+        `[org] config/org.yaml exists but could not be loaded (${why}). ` +
+        `Treating this agent as NOT enrolled — it will not join the org mesh.`,
+      );
+    } catch { /* never throw from logging */ }
     return {};
   }
 }

package/lib/org/client.test.mjs

@@ -8,9 +8,22 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Run `fn` with console.warn captured; returns the captured lines. */
+function captureWarn(fn) {
+  const lines = [];
+  const real = console.warn;
+  console.warn = (...a) => { lines.push(a.join(" ")); };
+  try { fn(); } finally { console.warn = real; }
+  return lines;
+}
 
 import {
   isEnabled,
+  loadOrgConfig,
   configFromAgent,
   pairRequest,
   call,
@@ -1105,3 +1118,41 @@ test("fetchHierarchy: GET /v1/hierarchy bare payload → {members,reporting}; nu
   const fail = fakeFetch(() => ({ ok: false, status: 503, body: { error: { code: "INTERNAL", message: "down" } } }));
   assert.equal(await fetchHierarchy({ base: BASE, token: TOKEN, orgId: "acme", fetchImpl: fail }), null);
 });
+
+// ---------------------------------------------------------------------------
+// loadOrgConfig — an enrolled agent must never go quietly un-enrolled
+// ---------------------------------------------------------------------------
+
+test("loadOrgConfig: absent org.yaml is silent (an un-enrolled agent is not a fault)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "orgcfg-"));
+  const warnings = captureWarn(() => {
+    assert.deepEqual(loadOrgConfig(dir), {});
+  });
+  assert.deepEqual(warnings, [], "no file, no noise");
+});
+
+test("loadOrgConfig: parses config/org.yaml", () => {
+  const dir = mkdtempSync(join(tmpdir(), "orgcfg-"));
+  mkdirSync(join(dir, "config"), { recursive: true });
+  writeFileSync(
+    join(dir, "config", "org.yaml"),
+    "org:\n  cohort:\n    enabled: true\n    base: https://os.example.com\n",
+  );
+  const cfg = loadOrgConfig(dir);
+  assert.equal(cfg.org.cohort.enabled, true);
+  assert.equal(isEnabled(cfg), true);
+});
+
+test("loadOrgConfig: a PRESENT but unparseable org.yaml WARNS (never silently un-enrols)", () => {
+  // Returning {} quietly is how an enrolled agent ends up out of the mesh:
+  // isEnabled({}) is false, so the daemon no-ops, never beats, and cannot
+  // receive `halt`. Fail-open is right; silence is not.
+  const dir = mkdtempSync(join(tmpdir(), "orgcfg-"));
+  mkdirSync(join(dir, "config"), { recursive: true });
+  writeFileSync(join(dir, "config", "org.yaml"), "org:\n  cohort:\n   - [unbalanced\n");
+  let cfg;
+  const warnings = captureWarn(() => { cfg = loadOrgConfig(dir); });
+  assert.deepEqual(cfg, {}, "still fail-open");
+  assert.match(warnings.join("\n"), /could not be loaded/, "the operator must be told");
+  assert.match(warnings.join("\n"), /NOT enrolled/, "and told what it means");
+});

package/lib/org/doctor.mjs

@@ -190,6 +190,70 @@ export async function checkOrgConnectivity(o = {}) {
     results.push({ level: "warn", msg: `pairing probe inconclusive (${chan.error?.code || "?"}: ${chan.error?.message || "no detail"})` });
   }
 
+  // ── 3b. INBOUND PATH probe — can this agent actually RECEIVE a message? ───
+  //
+  // Pairing proves the key is bound to a member. It does NOT prove the agent
+  // can hear anything, and those are different failures with the same healthy
+  // appearance. In production an enrolled, beating, correctly-paired agent was
+  // deaf for hours: the inbound cadence read org config from the wrong file, and
+  // the history call sent `channel` where hq validates `channelId`. Doctor was
+  // green throughout, because nothing exercised the receive path.
+  //
+  // So exercise it: read history from a real channel the agent belongs to. That
+  // single call covers the param contract, the read scope, and the ACL. A
+  // BAD_REQUEST here means protocol drift between this SDK and the server —
+  // the class of bug that leaves a fresh machine silently mute.
+  if (chan.ok) {
+    const rooms = chan.result && (Array.isArray(chan.result.channels) ? chan.result.channels : Array.isArray(chan.result) ? chan.result : []);
+    const probeRoom = (rooms || []).map((c) => c && (c.id || c.channelId)).find(Boolean);
+    if (!probeRoom) {
+      results.push({ level: "warn", msg: "inbound probe skipped — this member is in no channels yet" });
+    } else {
+      const hist = await call("messaging.history", { channelId: probeRoom, limit: 1 }, callOpts);
+      if (hist.ok) {
+        results.push({ level: "ok", msg: "inbound path works (messaging.history readable)" });
+      } else if (hist.error && hist.error.code === "BAD_REQUEST") {
+        results.push({
+          level: "fail",
+          msg:
+            `inbound path BROKEN — messaging.history rejected this SDK's params ` +
+            `(${hist.error.message || "BAD_REQUEST"}). The agent cannot read messages ` +
+            `sent to it. This is SDK/server protocol drift: upgrade with ` +
+            `\`npm update @cohortapp/agent-sdk && npx @cohortapp/agent-sdk upgrade\``,
+        });
+      } else {
+        results.push({
+          level: "warn",
+          msg: `inbound probe inconclusive (${hist.error?.code || "?"}: ${hist.error?.message || "no detail"})`,
+        });
+      }
+    }
+  }
+
+  // ── 3c. Is org enrolment visible to the DAEMON's config loader? ───────────
+  //
+  // The org client reads config/org.yaml; the cadence guards read the agent cfg.
+  // When those disagree the agent enrols successfully and still ignores every
+  // inbound event, because each org-facing guard bails out with "org messaging
+  // not configured". Assert the daemon's own view here rather than the client's.
+  try {
+    const { loadOrgConfig: loadOrg } = await import("./client.mjs");
+    const daemonView = loadOrg(agentRoot);
+    if (!daemonView || !daemonView.org || !daemonView.org.cohort) {
+      results.push({
+        level: "fail",
+        msg:
+          "org enrolment is NOT visible to the daemon's config loader — every " +
+          "org-facing cadence (messaging-inbound, brand-steward, …) will silently " +
+          "do nothing. Check config/org.yaml exists and js-yaml is installed.",
+      });
+    } else {
+      results.push({ level: "ok", msg: "org enrolment visible to the daemon cadences" });
+    }
+  } catch (err) {
+    results.push({ level: "warn", msg: `daemon org-config check failed (${err && err.message})` });
+  }
+
   // ── 4/5. workspace mailbox ───────────────────────────────────────────────
   const orgmailGate = existsSync(join(agentRoot, "config", "orgmail.yaml"));
   if (orgmailGate) {

package/lib/org/doctor.test.mjs

@@ -62,6 +62,8 @@ function stubFetch(routes) {
 }
 
 const DIR_OK = { status: 200, body: { members: [] }, headers: { "x-org-protocol": String(PROTOCOL_VERSION) } };
+const HISTORY_OK = { status: 200, body: { ok: true, result: { messages: [] } } };
+const HISTORY_BAD_PARAMS = { status: 400, body: { ok: false, error: { code: "BAD_REQUEST", message: "channelId: Required" } } };
 const CHANNELS_OK = { status: 200, body: { ok: true, result: { channels: [{ id: "c1" }, { id: "c2" }] } } };
 
 const levelsOf = (rs) => rs.map((r) => r.level);
@@ -80,10 +82,17 @@ test("probe 1: not enrolled → single ok line, no network", async () => {
 
 test("probe 2: happy path — reachable + latency + aligned protocol header + paired", async () => {
   const r = root();
-  const f = stubFetch({ "/api/v1/directory": DIR_OK, "/api/v1/messaging.channels": CHANNELS_OK });
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/messaging.history": HISTORY_OK,
+  });
   let t = 1000;
   const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {}, now: () => (t += 40) });
-  assert.deepEqual(levelsOf(rs), ["ok", "ok", "ok", "ok"]);
+  // …reachable, protocol, paired, INBOUND PATH, daemon-visible org config.
+  assert.deepEqual(levelsOf(rs), ["ok", "ok", "ok", "ok", "ok", "ok"]);
+  assert.match(msgs(rs), /inbound path works/);
+  assert.match(msgs(rs), /visible to the daemon cadences/);
   assert.match(msgs(rs), /directory \d+ms/);
   assert.match(msgs(rs), /protocol version aligned/);
   assert.match(msgs(rs), /paired to a workforce member \(2 channel\(s\)\)/);
@@ -210,3 +219,23 @@ test("no orgmail gate file → no mailbox probe at all", async () => {
   assert.ok(!f.calls.some((c) => c.url.includes("email.inbox")));
   rmSync(r, { recursive: true, force: true });
 });
+
+test("inbound probe FAILS loudly when the server rejects this SDK's params", () => {
+  // The real incident: fetchHistory sent `channel`, hq validates `channelId`,
+  // so the agent could not read a single message sent to it — while every other
+  // doctor line stayed green. Protocol drift must be a FAIL, not a shrug.
+  const r = root();
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/messaging.history": HISTORY_BAD_PARAMS,
+  });
+  return checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} }).then((rs) => {
+    const bad = rs.find((x) => /inbound path BROKEN/.test(x.msg));
+    assert.ok(bad, "a rejected inbound probe must surface");
+    assert.equal(bad.level, "fail");
+    assert.match(bad.msg, /protocol drift/);
+    assert.match(bad.msg, /upgrade/);
+    rmSync(r, { recursive: true, force: true });
+  });
+});

package/lib/org/mesh.mjs

@@ -331,6 +331,34 @@ async function beatOnce(ctx) {
     logWarn(`presence beat failed (${err && err.message}) — org may be down, continuing standalone`);
     return [];
   }
+
+  // A REJECTED beat is not a thrown beat. `presenceBeat` RESOLVES with a res
+  // FRAME — {ok:false,error:{code,message}} — for 401/403/404/500 alike, so the
+  // catch above only ever sees transport failures. Without this, a beat the
+  // server refuses is indistinguishable from one it accepted: nothing is logged,
+  // extractDirectives yields [], and the agent looks perfectly healthy while it
+  // is not in the mesh at all. Observed in the wild: an empty token produced a
+  // silent 401 on every beat for the life of the process.
+  //
+  // WARN ONLY — do NOT return early. An error frame is also how the kill switch
+  // arrives for a DEACTIVATED token: the server refuses the beat and rides
+  // `directive: "halt"` on the error. Returning here would drop exactly the
+  // signal that must never be dropped, so the directive walk below still runs.
+  //
+  // Logged, not thrown: the loop stays fail-open by design (the org being down
+  // must never take the daemon down). Being LOUD is the fix, not dying.
+  if (frame && frame.ok === false) {
+    const code = (frame.error && frame.error.code) || "UNKNOWN";
+    const msg = (frame.error && frame.error.message) || "";
+    logWarn(
+      `presence beat REJECTED by the org (${code}${msg ? `: ${msg}` : ""}) — ` +
+      `this agent is NOT in the mesh and will not receive directives` +
+      (code === "UNAUTHORIZED"
+        ? `. Check COHORT_API_KEY in .env is present and paired`
+        : ""),
+    );
+  }
+
   const directives = extractDirectives(frame);
   for (const d of directives) {
     try { await handleDirective(d, ctx); } catch { /* each directive is independently fail-open */ }

package/lib/org/mesh.test.mjs

@@ -216,6 +216,61 @@ test("org unreachable: presence beat that rejects never throws (fail-open)", asy
   handle.stop();
 });
 
+test("a REJECTED beat (error frame, not a throw) is loudly warned, not silently ignored", async () => {
+  const root = tmpRepo();
+  // A refused beat resolves with an error FRAME — it does not throw — so the
+  // fail-open catch above never sees it. Before this was handled, an agent with
+  // a bad/empty token 401'd on every beat for the life of the process while
+  // logging nothing: it was not in the mesh, could not receive `halt`, and
+  // looked perfectly healthy.
+  const client = fakeClient({
+    beatFrames: [{ ok: false, error: { code: "UNAUTHORIZED", message: "bad key" } }],
+  });
+
+  const warnings = [];
+  const realWarn = console.warn;
+  console.warn = (...a) => { warnings.push(a.join(" ")); };
+  let directives;
+  try {
+    const handle = await connectOrgMesh({
+      agentRoot: root, cfg: cfgEnabled(), client,
+      setInterval: () => ({ unref() {} }),
+    });
+    directives = await _internals.beatOnce(handle._ctx);
+    handle.stop();
+  } finally {
+    console.warn = realWarn;
+  }
+
+  assert.deepEqual(directives, [], "a rejected beat yields no directives");
+  const warned = warnings.join("\n");
+  assert.match(warned, /REJECTED/, "the rejection must be logged, not swallowed");
+  assert.match(warned, /UNAUTHORIZED/, "the error code must reach the operator");
+  assert.match(warned, /COHORT_API_KEY/, "an auth failure must name the likely cause");
+});
+
+test("an accepted beat logs no rejection warning", async () => {
+  const root = tmpRepo();
+  const client = fakeClient({ beatFrames: [{ ok: true, result: { directives: [] } }] });
+  const warnings = [];
+  const realWarn = console.warn;
+  console.warn = (...a) => { warnings.push(a.join(" ")); };
+  try {
+    const handle = await connectOrgMesh({
+      agentRoot: root, cfg: cfgEnabled(), client,
+      setInterval: () => ({ unref() {} }),
+    });
+    await _internals.beatOnce(handle._ctx);
+    handle.stop();
+  } finally {
+    console.warn = realWarn;
+  }
+  assert.ok(
+    !warnings.join("\n").includes("REJECTED"),
+    "a healthy beat must not cry wolf",
+  );
+});
+
 test("registration failure at boot is swallowed; the mesh still comes up", async () => {
   const root = tmpRepo();
   const client = fakeClient();