@cohortapp/agent-sdk 2.6.1 → 2.7.0

package/bin/maestro.mjs

@@ -785,6 +785,43 @@ function isPruneExcluded(repoRel) {
   return PRUNE_EXCLUDE_PREFIXES.some((p) => repoRel.startsWith(p));
 }
 
+// Record of what the framework actually delivered to THIS machine, written at
+// the end of every non-dry upgrade. Per-machine state, hence .maestro/.
+//
+// Prune needs to answer "did the framework once ship this file?", and git
+// cannot answer it. A tracked-and-clean file absent from upstream is EITHER a
+// framework file deleted upstream OR a file the operator wrote and committed
+// themselves — the two are byte-for-byte indistinguishable in git status.
+// Getting that wrong destroys operator work: the first cut of this pass
+// proposed deleting an agent's pre-commit secret-scan hook (protecting a live
+// org credential) and its hand-authored workflows, purely because the SDK had
+// never shipped them.
+//
+// So provenance is recorded explicitly. Prune considers a file only if the
+// PREVIOUS manifest lists it — proof this machine received it from the SDK.
+// A machine with no manifest yet prunes nothing and starts clean from the next
+// upgrade; that is the safe direction to fail.
+const SHIPPED_MANIFEST_REL = ".maestro/shipped-manifest.json";
+
+function loadShippedManifest(cwd) {
+  try {
+    const raw = JSON.parse(readFileSync(join(cwd, SHIPPED_MANIFEST_REL), "utf-8"));
+    if (Array.isArray(raw?.files)) return new Set(raw.files);
+  } catch {
+    // Absent or unreadable — caller treats this as "provenance unknown".
+  }
+  return null;
+}
+
+function writeShippedManifest(cwd, files) {
+  const dst = join(cwd, SHIPPED_MANIFEST_REL);
+  mkdirSync(dirname(dst), { recursive: true });
+  writeFileSync(
+    dst,
+    JSON.stringify({ version: 1, files: [...files].sort() }, null, 2) + "\n",
+  );
+}
+
 function sha256File(p) {
   return createHash("sha256").update(readFileSync(p)).digest("hex");
 }
@@ -1174,6 +1211,8 @@ Per-file behaviour:
   const ignoredFiles = [];
   const prunedFiles = [];
   const pruneKeptFiles = [];
+  // What upstream ships right now — becomes this machine's provenance record.
+  const shippedNow = new Set();
 
   for (const { path: relRoot, mode } of UPGRADE_PATHS) {
     const srcRoot = join(MAESTRO_ROOT, relRoot);
@@ -1185,6 +1224,9 @@ Per-file behaviour:
       const relFromRoot = relative(srcRoot, srcFile);
       const dstFile = join(dstRoot, relFromRoot);
       const repoRel = relative(cwd, dstFile).split(sep).join("/");
+      // Recorded regardless of what we then decide to do with the file: the
+      // manifest answers "does the framework ship this?", not "did we write it?"
+      shippedNow.add(repoRel);
 
       const isIgnored = matchesIgnore(repoRel, ignorePatterns);
 
@@ -1287,10 +1329,15 @@ Per-file behaviour:
   //
   // Removals are backed up under .maestro/backup/ exactly like a forced
   // overwrite, so a prune is always reversible.
+  const priorManifest = loadShippedManifest(cwd);
+
   if (flags.noPrune) {
     log("Prune skipped (--no-prune): upstream-deleted files left in place.");
   } else if (!inGit) {
     warn("Prune skipped: not a git repo, so pristine framework files can't be told from yours.");
+  } else if (!priorManifest) {
+    log("Prune skipped: no shipped-manifest yet, so framework files can't be told from your own.");
+    log(`Recording one now (${SHIPPED_MANIFEST_REL}); prune takes effect from the next upgrade.`);
   } else {
     for (const { path: relRoot, mode } of UPGRADE_PATHS) {
       // merge-mode roots hold deliberately-local files — nothing to reconcile.
@@ -1313,6 +1360,15 @@ Per-file behaviour:
           continue;
         }
 
+        // Provenance gate: unless a previous upgrade recorded delivering this
+        // file, it is the operator's until proven otherwise. See the note on
+        // SHIPPED_MANIFEST_REL — this is what stops prune eating hand-authored
+        // scripts, workflows and policies that merely sit under a smart root.
+        if (!priorManifest.has(repoRel)) {
+          if (flags.verbose) console.log(`  · ${repoRel} (never shipped by the framework — yours)`);
+          continue;
+        }
+
         if (matchesIgnore(repoRel, ignorePatterns)) {
           counts.ignored++;
           ignoredFiles.push(repoRel);
@@ -1341,6 +1397,18 @@ Per-file behaviour:
     }
   }
 
+  // Record provenance for the next run. Written even when nothing was pruned —
+  // it is what makes the FOLLOWING upgrade able to prune safely. Never written
+  // on a dry run, so --dry-run stays genuinely side-effect-free.
+  if (!flags.dryRun) {
+    try {
+      writeShippedManifest(cwd, shippedNow);
+    } catch (err) {
+      // Non-fatal: a missing manifest costs pruning, not correctness.
+      warn(`Could not write ${SHIPPED_MANIFEST_REL}: ${err.message}`);
+    }
+  }
+
   // Ensure standard runtime directories exist.
   const ensureDirs = [
     "state/handoffs", "state/huddle", "state/indexes", "state/rag",

package/bin/maestro.test.mjs

@@ -1160,7 +1160,7 @@ test("doctor surfaces the new framework systems (org / secrets / diagnostics)",
  * Agent repo carrying `orphans` — paths upstream does not ship. Written before
  * the commit so git sees them as tracked and clean (prune's precondition).
  */
-async function makeAgentWithOrphans(orphans) {
+async function makeAgentWithOrphans(orphans, opts = {}) {
   const root = await tmpRoot("maestro-orphan");
   mkdirSync(join(root, "config"), { recursive: true });
   writeFileSync(join(root, "CLAUDE.md"), "# agent\n");
@@ -1170,6 +1170,17 @@ async function makeAgentWithOrphans(orphans) {
     mkdirSync(dirname(join(root, rel)), { recursive: true });
     writeFileSync(join(root, rel), body);
   }
+  // Provenance: prune only touches files a PREVIOUS upgrade recorded shipping.
+  // Without this the orphans are indistinguishable from operator-authored work
+  // and prune correctly refuses to act — so every prune test must seed it.
+  if (opts.seedManifest !== false) {
+    mkdirSync(join(root, ".maestro"), { recursive: true });
+    writeFileSync(
+      join(root, ".maestro/shipped-manifest.json"),
+      JSON.stringify({ version: 1, files: Object.keys(orphans).sort() }, null, 2) + "\n",
+    );
+  }
+
   execFileSync("git", ["init", "-q"], { cwd: root });
   execFileSync("git", ["add", "-A"], { cwd: root });
   execFileSync(
@@ -1322,3 +1333,72 @@ test("upgrade prune never removes machine-generated launchd plists", async () =>
     await fsp.rm(root, { recursive: true, force: true });
   }
 });
+
+test("upgrade prune spares operator-authored files the framework never shipped", async () => {
+  // The hazard that forced the provenance manifest. scripts/ is a smart root,
+  // so an operator's own committed script there is tracked, clean and absent
+  // upstream — every signal git can offer says "orphan". On a real agent
+  // machine this set included the pre-commit hook guarding a live org
+  // credential. Provenance, not cleanliness, is what makes prune safe.
+  const mine = "scripts/pre-commit-secret-scan.sh";
+  const root = await makeAgentWithOrphans({
+    [mine]: "#!/bin/sh\nexit 0\n",
+    [ORPHAN]: "export const gone = 1;\n",
+  });
+  try {
+    // Manifest records ONLY the framework file — the operator's script was
+    // never delivered by the SDK, so it must not be a prune candidate.
+    writeFileSync(
+      join(root, ".maestro/shipped-manifest.json"),
+      JSON.stringify({ version: 1, files: [ORPHAN] }, null, 2) + "\n",
+    );
+    execFileSync("git", ["add", "-A"], { cwd: root });
+    execFileSync(
+      "git",
+      ["-c", "user.email=test@test", "-c", "user.name=test", "commit", "-q", "-m", "manifest"],
+      { cwd: root },
+    );
+
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(existsSync(join(root, mine)), "a file the framework never shipped is the operator's");
+    assert.ok(!existsSync(join(root, ORPHAN)), "the genuinely-shipped orphan should still prune");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade prunes nothing on a machine with no shipped-manifest, then records one", async () => {
+  const root = await makeAgentWithOrphans({ [ORPHAN]: "export const gone = 1;\n" }, { seedManifest: false });
+  try {
+    const first = runCli(["upgrade"], root);
+    assert.equal(first.status, 0, first.stderr);
+    assert.ok(
+      existsSync(join(root, ORPHAN)),
+      "with no provenance record, prune must do nothing rather than guess",
+    );
+    assert.ok(
+      existsSync(join(root, ".maestro/shipped-manifest.json")),
+      "the first run must record provenance so the next one can prune",
+    );
+    const manifest = JSON.parse(readFileSync(join(root, ".maestro/shipped-manifest.json"), "utf-8"));
+    assert.ok(manifest.files.includes("scripts/daemon/responder.mjs"), "manifest lists shipped files");
+    assert.ok(!manifest.files.includes(ORPHAN), "manifest must not list what upstream doesn't ship");
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("upgrade --dry-run writes no shipped-manifest", async () => {
+  const root = await makeAgentWithOrphans({}, { seedManifest: false });
+  try {
+    const r = runCli(["upgrade", "--dry-run"], root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(
+      !existsSync(join(root, ".maestro/shipped-manifest.json")),
+      "--dry-run must stay side-effect-free, including provenance",
+    );
+  } finally {
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scripts/daemon/responder-history.test.mjs

@@ -0,0 +1,169 @@
+/**
+ * responder.test.mjs — conversation history behind holding messages / quick replies.
+ * Run: node --test scripts/daemon/responder.test.mjs
+ *
+ * `loadConversationHistory` used to build its candidate directories as
+ * `memory/interactions/slack/<id>` unconditionally, and its writer
+ * (`logInteraction`) early-returns for any service that is not Slack. A Cohort
+ * DM therefore had nothing written and nothing to read, so every holding
+ * message for Cohort was generated from the current message alone. A bare "?"
+ * produced "What's on your mind?" — indistinguishable from amnesia, and the
+ * CEO read it as exactly that (2026-08-13, dm-h001-a016).
+ *
+ * Cohort has an authoritative `messaging.history`. These tests pin that the
+ * cohort branch reads it, orders it oldest-first, and NEVER throws — the
+ * holding path must degrade to "no history" rather than take the send down.
+ */
+"use strict";
+
+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";
+
+import { loadConversationHistory } from "./responder.mjs";
+
+const cohortItem = {
+  sender: "Dana Okafor",
+  service: "cohort",
+  channel: "dm-h001-a016",
+  channel_id: "cmql1802601iihhzpf774vwbk",
+  content: "?",
+};
+
+// Newest-first, the way messaging.history actually returns it.
+const HISTORY = [
+  { id: "m3", createdAt: "2026-08-13T05:47:51Z", authorName: "Dana Okafor", body: "with that in mind, fix these issues you just noted please" },
+  { id: "m2", createdAt: "2026-08-12T13:52:53Z", authorName: "Isla Roselli", body: "Both are merged. #19 went in as 94f227c4." },
+  { id: "m1", createdAt: "2026-08-12T13:47:30Z", authorName: "Dana Okafor", body: "why haven't you merged? please go ahead" },
+];
+
+test("cohort: reads messaging.history and renders it oldest-first", async () => {
+  const seen = [];
+  const text = await loadConversationHistory(cohortItem, {
+    fetchHistory: async (params, o) => {
+      seen.push({ params, hasCfg: Boolean(o && o.cfg) });
+      return HISTORY;
+    },
+    loadOrgConfig: () => ({ org: { cohort: { enabled: true, base: "https://x", token: "t" } } }),
+  });
+
+  assert.ok(text, "expected a transcript, got null");
+  assert.match(text, /Dana Okafor: why haven't you merged/);
+  assert.match(text, /Isla Roselli: Both are merged/);
+  assert.match(text, /Dana Okafor: with that in mind/);
+
+  // Oldest-first: the model reads a conversation, not a reversed one.
+  assert.ok(
+    text.indexOf("why haven't you merged") < text.indexOf("with that in mind"),
+    "history must be rendered oldest-first",
+  );
+
+  // The channel it asks for is the item's channel_id, and cfg is ALWAYS passed:
+  // fetchHistory() fails open to [] when cfg is omitted, which is silently
+  // indistinguishable from an empty channel. That is the bug this file exists for.
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0].params.channel, "cmql1802601iihhzpf774vwbk");
+  assert.equal(seen[0].hasCfg, true, "cfg must be passed or fetchHistory returns [] silently");
+});
+
+test("cohort: an empty channel is null, not an empty transcript", async () => {
+  const text = await loadConversationHistory(cohortItem, {
+    fetchHistory: async () => [],
+    loadOrgConfig: () => ({}),
+  });
+  assert.equal(text, null);
+});
+
+test("cohort: a failing history call degrades to null and never throws", async () => {
+  const text = await loadConversationHistory(cohortItem, {
+    fetchHistory: async () => { throw new Error("cohort unreachable"); },
+    loadOrgConfig: () => ({}),
+  });
+  assert.equal(text, null);
+});
+
+test("cohort: the current message is not fed back as its own history", async () => {
+  const text = await loadConversationHistory(
+    { ...cohortItem, message_id: "m3" },
+    {
+      fetchHistory: async () => HISTORY,
+      loadOrgConfig: () => ({}),
+    },
+  );
+  assert.ok(text);
+  assert.doesNotMatch(text, /with that in mind/, "the inbound message itself must be excluded");
+});
+
+test("slack: still reads the local interaction mirror", async () => {
+  const root = mkdtempSync(join(tmpdir(), "maestro-responder-"));
+  const dir = join(root, "memory", "interactions", "slack", "D099N1JGKRQ");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "2026-08-13.jsonl"),
+    [
+      JSON.stringify({ ts: "2026-08-13T05:00:00Z", from: "Dana Okafor", content: "ship it" }),
+      JSON.stringify({ ts: "2026-08-13T05:01:00Z", from: "agent", content: "shipped" }),
+    ].join("\n"),
+  );
+
+  const text = await loadConversationHistory(
+    { sender: "Dana Okafor", service: "slack", channel: "D099N1JGKRQ", content: "?" },
+    { agentRepoDir: root },
+  );
+
+  assert.ok(text, "expected the slack mirror to still be read");
+  assert.match(text, /Dana Okafor: ship it/);
+  assert.match(text, /agent: shipped/);
+});
+
+test("cohort: falls back to the local mirror when the server is unreachable", async () => {
+  // Isla's original returned null outright for Cohort when messaging.history
+  // failed. Falling through to the mirror means a transient API blip degrades
+  // to cached context instead of to none — the mirror is a poor source of
+  // truth but a perfectly good backstop.
+  const root = mkdtempSync(join(tmpdir(), "maestro-responder-"));
+  const dir = join(root, "memory", "interactions", "cohort", "chan-1");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "2026-08-13.jsonl"),
+    JSON.stringify({ ts: "2026-08-13T05:00:00Z", from: "Dana Okafor", content: "cached line" }),
+  );
+
+  const text = await loadConversationHistory(
+    { sender: "Dana Okafor", service: "cohort", channel: "chan-1", content: "?" },
+    {
+      agentRepoDir: root,
+      loadOrgConfig: () => ({}),
+      fetchHistory: async () => { throw new Error("network down"); },
+    },
+  );
+
+  assert.ok(text, "a server failure must not erase locally cached context");
+  assert.match(text, /Dana Okafor: cached line/);
+});
+
+test("cohort: server history wins over the local mirror", async () => {
+  const root = mkdtempSync(join(tmpdir(), "maestro-responder-"));
+  const dir = join(root, "memory", "interactions", "cohort", "chan-1");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "2026-08-13.jsonl"),
+    JSON.stringify({ ts: "2026-08-13T05:00:00Z", from: "stale", content: "outdated mirror line" }),
+  );
+
+  const text = await loadConversationHistory(
+    { sender: "Dana Okafor", service: "cohort", channel: "chan-1", content: "?" },
+    {
+      agentRepoDir: root,
+      loadOrgConfig: () => ({}),
+      fetchHistory: async () => ([
+        { id: "m2", authorName: "Dana Okafor", body: "authoritative line", createdAt: "2026-08-13T06:00:00Z" },
+      ]),
+    },
+  );
+
+  assert.match(text, /authoritative line/, "the server is the source of truth");
+  assert.doesNotMatch(text, /outdated mirror line/, "the stale mirror must not be mixed in");
+});

package/scripts/daemon/responder.mjs

@@ -523,23 +523,105 @@ function loadUserProfile(sender) {
 // Load recent conversation history for context
 // ---------------------------------------------------------------------------
 
+/** Cohort's message ids as this item carries them, so history can drop itself. */
+function inboundMessageIds(item) {
+  const ids = new Set();
+  const add = (v) => { if (v) ids.add(String(v)); };
+  add(item.message_id);
+  // Inbox filenames prefix the service: "cohort-cmsr45u91…" → "cmsr45u91…".
+  if (item.id) { add(item.id); add(String(item.id).replace(/^[a-z]+-/, "")); }
+  // raw_ref is "cohort:dm:<messageId>:<seq>".
+  const m = typeof item.raw_ref === "string" ? item.raw_ref.match(/^cohort:[^:]+:([^:]+)/) : null;
+  if (m) add(m[1]);
+  return ids;
+}
+
+const COHORT_HISTORY_LIMIT = 12;
+const COHORT_HISTORY_CHARS = 400;
+
+/**
+ * Cohort history straight from the server, via the same `messaging.history` the
+ * replies are posted to.
+ *
+ * The local mirror below is a cache the agent populates itself, so it carries
+ * context only if the agent has already been talking AND logging correctly.
+ * When the write half broke (logInteraction early-returned for every non-Slack
+ * service), the read half silently returned nothing, memory/interactions/ was
+ * never even created, and holding messages were composed from the inbound
+ * message alone — a bare "?" came back as "What's on your mind?" mid-thread.
+ *
+ * Asking the authority that stores the message removes that coupling: a fresh
+ * agent, or one whose mirror was wiped, still answers with full context.
+ *
+ * Fails open to null on every path. No amount of history is worth failing a send.
+ */
+async function loadCohortHistory(item, deps = {}) {
+  const channel = item.channel_id || item.channel || "";
+  if (!channel) return null;
+
+  try {
+    const fetchHistory = deps.fetchHistory
+      || (await import("../../lib/org/messaging.mjs")).fetchHistory;
+    const loadOrgConfig = deps.loadOrgConfig
+      || (await import("../../lib/org/client.mjs")).loadOrgConfig;
+    const agentRoot = deps.agentRepoDir || process.env.AGENT_ROOT || process.env.AGENT_DIR || AGENT_REPO_DIR;
+
+    // cfg is mandatory. configFromAgent() reads base+token ONLY from the object
+    // handed in — it never loads config/org.yaml — so omitting it returns a
+    // fail-open [] that looks exactly like an empty channel.
+    const messages = await fetchHistory(
+      { channel, limit: COHORT_HISTORY_LIMIT + 1 },
+      { cfg: loadOrgConfig(agentRoot), agentRoot },
+    );
+    if (!Array.isArray(messages) || messages.length === 0) return null;
+
+    const self = inboundMessageIds(item);
+    const rows = messages
+      .filter((m) => m && !self.has(String(m.id)))
+      .slice(0, COHORT_HISTORY_LIMIT)
+      .reverse() // messaging.history is newest-first; a conversation reads the other way
+      .map((m) => {
+        const from = m.authorName || m.author?.name || m.authorId || "unknown";
+        const text = String(m.body ?? m.content ?? "").trim();
+        return `[${m.createdAt || ""}] ${from}: ${text.substring(0, COHORT_HISTORY_CHARS)}`;
+      });
+
+    return rows.length > 0 ? rows.join("\n") : null;
+  } catch (err) {
+    console.warn(`[responder] cohort history unavailable for ${item.sender}: ${err.message}`);
+    return null;
+  }
+}
+
 /**
  * The reader half of `logInteraction`. It looked ONLY under
  * `memory/interactions/slack/…`, so even once a Cohort exchange was written it
  * would not have been found. Both halves are now keyed on the item's service.
+ *
+ * Cohort asks the server first (see loadCohortHistory) and falls back to the
+ * local mirror, so a transient API failure degrades to cached context rather
+ * than to none.
  */
-function loadConversationHistory(item) {
+export async function loadConversationHistory(item, deps = {}) {
   if (!item || !item.sender || !item.service) return null;
 
   const service = String(item.service);
+
+  if (service === "cohort") {
+    const remote = await loadCohortHistory(item, deps);
+    if (remote) return remote;
+  }
+  // Test seam: the mirror's location is a parameter, so a test can point at a
+  // tmpdir instead of mutating process.env for the whole worker.
+  const repoDir = deps.agentRepoDir || AGENT_REPO_DIR;
   const senderSlug = item.sender.replace(/\s+/g, "-").toLowerCase();
   const channelId = service === "slack"
     ? resolveSlackChannel(item)
     : (item.channel_id || item.channel || null);
 
   const candidateDirs = [];
-  if (channelId) candidateDirs.push(join(AGENT_REPO_DIR, "memory", "interactions", service, String(channelId)));
-  candidateDirs.push(join(AGENT_REPO_DIR, "memory", "interactions", service, `dm-${senderSlug}`));
+  if (channelId) candidateDirs.push(join(repoDir, "memory", "interactions", service, String(channelId)));
+  candidateDirs.push(join(repoDir, "memory", "interactions", service, `dm-${senderSlug}`));
 
   const entries = [];
   for (const dir of candidateDirs) {
@@ -621,7 +703,7 @@ Keep responses focused — 1-4 sentences for simple items, up to a short paragra
 Match the sender's tone and urgency level.
 ${profile ? `\nSender profile:\n${profile}` : ""}`;
 
-  const conversationHistory = loadConversationHistory(item);
+  const conversationHistory = await loadConversationHistory(item);
 
   const userContent = [
     `From: ${item.sender} (${item.sender_privilege || "unknown"})`,