@cohortapp/agent-sdk 2.3.0

package/lib/charter.mjs

@@ -0,0 +1,256 @@
+/**
+ * charter.mjs — operating-charter skeleton builder.
+ *
+ * Renders a complete, enterprise-grade operating charter (Markdown) from a
+ * resolved archetype profile (lib/archetype.mjs) + the agent's identity
+ * (config/agent.json). The output is deterministic and structurally complete on
+ * its own — towers, decision-rights matrix, autonomy bands, escalation, KPI
+ * tree, stakeholder map, operating principles, and a 30/60/90 scaffold all flow
+ * from the profile. The init wizard then ENRICHES the company-specific slots
+ * (concrete purpose, named stakeholders, real KPI targets, a real first-90)
+ * from the gathered context pack — but even un-enriched this is a real charter,
+ * not a placeholder.
+ *
+ * Pure (no I/O). The caller stamps any date/identity. ESM.
+ *
+ * @module charter
+ */
+
+"use strict";
+
+const AUTHORITY_LABEL = {
+  owns: "Owns",
+  recommends: "Recommends",
+  escalates: "Escalates",
+  informed: "Informed",
+};
+
+function mdEscape(s) {
+  return String(s == null ? "" : s).replace(/\|/g, "\\|");
+}
+
+function bulletList(items, fallback) {
+  const arr = Array.isArray(items) ? items.filter(Boolean) : [];
+  if (arr.length === 0) return fallback ? `- ${fallback}` : "- _(to be defined during init enrichment)_";
+  return arr.map((x) => `- ${x}`).join("\n");
+}
+
+/**
+ * Build the operating charter Markdown from a resolved profile + identity.
+ *
+ * @param {object} profile - resolved archetype profile (lib/archetype.mjs)
+ * @param {object} identity - config/agent.json (fullName, title, company, principal, …)
+ * @param {object} [opts] @param {string} [opts.date] ISO date string for the header
+ * @returns {string} charter Markdown
+ */
+export function buildCharterSkeleton(profile, identity, opts = {}) {
+  if (!profile || !identity) throw new Error("buildCharterSkeleton: requires (profile, identity)");
+  const id = identity;
+  const principal = id.principal || {};
+  const date = opts.date || "";
+  const L = [];
+
+  L.push(`# Operating Charter — ${id.fullName || "Unconfigured Agent"}`);
+  L.push("");
+  L.push(`> Generated by Maestro from the \`${profile.function} × ${profile.altitude}\` archetype.${date ? ` ${date}.` : ""}`);
+  L.push("> Company-specific sections are enriched at init from the gathered context pack.");
+  L.push("");
+  L.push(`- **Role:** ${id.title || profile.label}`);
+  L.push(`- **Archetype:** ${profile.label} — \`${profile.function}\` × \`${profile.altitude}\``);
+  L.push(`- **Operating posture:** ${profile.posture || "—"}`);
+  if (principal.fullName) L.push(`- **Principal:** ${principal.fullName}${principal.title ? `, ${principal.title}` : ""}`);
+  if (id.company) L.push(`- **Company:** ${id.company}`);
+  L.push("");
+
+  // --- Purpose & Mandate ---
+  L.push("## 1. Purpose & Mandate");
+  L.push("");
+  L.push(`As ${id.title || profile.label}${id.company ? ` at ${id.company}` : ""}, this agent owns **${profile.domain || profile.label}**. ${profile.posture || ""}`.trim());
+  L.push("");
+  L.push("_Mandate (enrich at init): the specific charge the principal is giving this agent, and the outcomes it is accountable for._");
+  L.push("");
+
+  // --- Control Towers ---
+  L.push("## 2. Control Towers");
+  L.push("");
+  L.push("The standing areas of responsibility this agent monitors and manages.");
+  L.push("");
+  L.push("| # | Tower | Focus |");
+  L.push("| - | ----- | ----- |");
+  (profile.towers || []).forEach((t, i) => {
+    L.push(`| ${i + 1} | ${mdEscape(t.name)} | ${mdEscape(t.focus || "")} |`);
+  });
+  L.push("");
+
+  // --- Decision Rights ---
+  L.push("## 3. Decision Rights");
+  L.push("");
+  L.push(`Authority by scope, calibrated to the **${profile.altitude}** altitude. "Owns" = decides and acts; "Recommends" = proposes, principal decides; "Escalates" = must route up; "Informed" = kept in the loop.`);
+  L.push("");
+  L.push("| Scope | Authority |");
+  L.push("| ----- | --------- |");
+  (profile.decisionRights || []).forEach((d) => {
+    L.push(`| ${mdEscape(d.scope)} | ${AUTHORITY_LABEL[d.authority] || d.authority} |`);
+  });
+  L.push("");
+
+  // --- Autonomy Model ---
+  const a = profile.autonomy || {};
+  L.push("## 4. Autonomy Model");
+  L.push("");
+  L.push(`Default posture: **${a.default || "draft"}**.`);
+  L.push("");
+  L.push("**Green — act autonomously**");
+  L.push(bulletList(a.green));
+  L.push("");
+  L.push("**Amber — approval preferred**");
+  L.push(bulletList(a.amber));
+  L.push("");
+  L.push("**Red — explicit approval required**");
+  L.push(bulletList(a.red));
+  L.push("");
+
+  // --- Escalation ---
+  const esc = profile.escalation || {};
+  L.push("## 5. Escalation Protocol");
+  L.push("");
+  L.push(`Escalates to: ${(esc.to || []).join(", ") || "the principal"}.`);
+  L.push("");
+  L.push("Escalation triggers:");
+  L.push(bulletList(esc.triggers, "Any binding, irreversible, or beyond-mandate decision"));
+  L.push("");
+
+  // --- KPI Tree ---
+  L.push("## 6. KPI Tree");
+  L.push("");
+  L.push(`KPI altitude: **${profile.kpiAltitude || "operational"}**. Targets are set at init against company baselines.`);
+  L.push("");
+  (profile.kpiCategories || []).forEach((k) => {
+    L.push(`### ${k.name}`);
+    L.push(bulletList((k.examples || []).map((e) => `${e} — _target: TBD at init_`)));
+    L.push("");
+  });
+
+  // --- Stakeholder Map ---
+  L.push("## 7. Stakeholder Map");
+  L.push("");
+  L.push("| Stakeholder | Typical relationship | Named contact (enrich at init) |");
+  L.push("| ----------- | -------------------- | ------------------------------ |");
+  (profile.stakeholderSlots || []).forEach((s) => {
+    L.push(`| ${mdEscape(s.role)} | ${mdEscape(s.typicalRelationship || "")} | _TBD_ |`);
+  });
+  L.push("");
+
+  // --- Operating Principles ---
+  L.push("## 8. Operating Principles");
+  L.push("");
+  L.push(bulletList(profile.operatingPrinciples));
+  L.push("");
+
+  // --- First 90 Days ---
+  L.push("## 9. First 90 Days");
+  L.push("");
+  L.push("_Enriched at init from the seeded backlog (see `state/backlog/wbs.yaml`)._");
+  L.push("");
+  L.push("### First 30 days — establish");
+  L.push("- Stand up the operating cadence and instrument the control towers.");
+  L.push("");
+  L.push("### Days 31–60 — execute");
+  L.push("- Drive the priority streams to their first milestones.");
+  L.push("");
+  L.push("### Days 61–90 — compound");
+  L.push("- Systematise what works; report outcomes against the KPI tree.");
+  L.push("");
+
+  L.push("---");
+  L.push("");
+  L.push(`_Tone & communication follow \`policies/communication-style.md\`. This charter is generated from the archetype library; regenerate with \`maestro\` after an archetype or identity change._`);
+  L.push("");
+
+  return L.join("\n");
+}
+
+/** Title-case a section `kind` token (e.g. "decision_rights" → "Decision Rights"). */
+function titleizeKind(kind) {
+  return String(kind || "")
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Render the operating charter Markdown FROM a Cohort-authored CharterDTO — the
+ * org source of truth. When a member's charter exists in Cohort
+ * (config/agent.json `charter` = { approvedByLine, gatesText, sections }), this
+ * is what `scripts/setup/generate-charter.mjs` writes, IN PLACE OF the archetype
+ * skeleton (buildCharterSkeleton). The agent thus operates on the charter its org
+ * authored, not a locally-synthesised one.
+ *
+ * Sections are rendered in `order`. Each section's heading is its `title` (or a
+ * title-cased `kind`), followed by its verbatim `body`. The approvedBy line and
+ * gates text are appended as their own blocks. Pure (no I/O).
+ *
+ * @param {object} charter - { approvedByLine?, gatesText?, sections:[{kind,order,title,body}] }
+ * @param {object} identity - config/agent.json (fullName, title, company, principal, …)
+ * @param {object} [opts] @param {string} [opts.date] ISO date string for the header
+ * @returns {string} charter Markdown
+ */
+export function renderCohortCharter(charter, identity, opts = {}) {
+  if (!charter || typeof charter !== "object") throw new Error("renderCohortCharter: requires a charter");
+  const id = identity || {};
+  const principal = id.principal || {};
+  const date = opts.date || "";
+  const L = [];
+
+  L.push(`# Operating Charter — ${id.fullName || "Unconfigured Agent"}`);
+  L.push("");
+  L.push(`> Authored in Cohort (org source of truth) and rendered by Maestro.${date ? ` ${date}.` : ""}`);
+  L.push("");
+  if (id.title) L.push(`- **Role:** ${id.title}`);
+  if (principal.fullName) L.push(`- **Principal:** ${principal.fullName}${principal.title ? `, ${principal.title}` : ""}`);
+  if (id.company) L.push(`- **Company:** ${id.company}`);
+  if (charter.approvedByLine) L.push(`- **Approved by:** ${charter.approvedByLine}`);
+  L.push("");
+
+  const sections = (Array.isArray(charter.sections) ? charter.sections.slice() : [])
+    .filter((s) => s && typeof s === "object")
+    .sort((a, b) => (Number(a.order) || 0) - (Number(b.order) || 0));
+  for (const s of sections) {
+    const heading = (s.title && String(s.title).trim()) || titleizeKind(s.kind) || "Section";
+    L.push(`## ${heading}`);
+    L.push("");
+    const body = s.body == null ? "" : String(s.body).trim();
+    L.push(body || "_(no content)_");
+    L.push("");
+  }
+
+  if (charter.gatesText && String(charter.gatesText).trim()) {
+    L.push("## Gates");
+    L.push("");
+    L.push(String(charter.gatesText).trim());
+    L.push("");
+  }
+
+  L.push("---");
+  L.push("");
+  L.push(`_Source of truth: the member's charter in Cohort. Regenerate with \`maestro\` after the org updates it._`);
+  L.push("");
+
+  return L.join("\n");
+}
+
+/**
+ * True if a charter body still contains unfilled placeholders that should be
+ * enriched before it is considered init-complete (used by the doctor gate).
+ *
+ * @param {string} body @returns {string[]} the placeholder markers found
+ */
+export function findCharterPlaceholders(body) {
+  if (typeof body !== "string") return [];
+  const markers = [];
+  if (/\{\{[^}]+\}\}/.test(body)) markers.push("unresolved {{token}}");
+  if (/\bTBD\b/.test(body)) markers.push("TBD");
+  if (/_\(to be defined during init enrichment\)_/.test(body)) markers.push("undefined autonomy/escalation band");
+  return [...new Set(markers)];
+}

package/lib/charter.test.mjs

@@ -0,0 +1,89 @@
+/**
+ * charter.test.mjs — tests for the operating-charter skeleton builder.
+ * Run: `node --test lib/charter.test.mjs`
+ * @module charter.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveArchetype } from "./archetype.mjs";
+import { buildCharterSkeleton, findCharterPlaceholders, renderCohortCharter } from "./charter.mjs";
+
+const IDENTITY = {
+  firstName: "Jacob", fullName: "Jacob Chen", title: "VP, Engineering", company: "Acme",
+  principal: { fullName: "Dana Reyes", title: "CEO" },
+};
+
+test("buildCharterSkeleton renders a complete charter from the profile", async () => {
+  const profile = await resolveArchetype({ function: "technical-leader", altitude: "vp" });
+  const md = buildCharterSkeleton(profile, IDENTITY, { date: "2026-06-01" });
+
+  assert.match(md, /# Operating Charter — Jacob Chen/);
+  assert.match(md, /\*\*Role:\*\* VP, Engineering/);
+  assert.match(md, /Dana Reyes, CEO/);
+  // towers from the function overlay
+  assert.match(md, /Platform & Architecture/);
+  // decision-rights matrix with altitude authorities
+  assert.match(md, /## 3\. Decision Rights/);
+  assert.match(md, /Escalates/);
+  // autonomy bands
+  assert.match(md, /Green — act autonomously/);
+  assert.match(md, /Red — explicit approval required/);
+  // KPI tree + stakeholders + principles + 90-day
+  assert.match(md, /## 6\. KPI Tree/);
+  assert.match(md, /## 7\. Stakeholder Map/);
+  assert.match(md, /Technical rigour over speed/); // a function principle
+  assert.match(md, /## 9\. First 90 Days/);
+});
+
+test("a C-suite charter differs from a senior-manager charter (altitude shows through)", async () => {
+  const cSuite = buildCharterSkeleton(await resolveArchetype({ function: "technical-leader", altitude: "c-suite" }), IDENTITY);
+  const srMgr = buildCharterSkeleton(await resolveArchetype({ function: "technical-leader", altitude: "senior-manager" }), IDENTITY);
+  assert.notEqual(cSuite, srMgr); // same function, different altitude → different charter
+});
+
+test("findCharterPlaceholders flags un-enriched markers (KPI targets are TBD pre-init)", async () => {
+  const profile = await resolveArchetype({ function: "commercial-leader", altitude: "svp" });
+  const md = buildCharterSkeleton(profile, IDENTITY);
+  assert.ok(findCharterPlaceholders(md).includes("TBD"));
+  // a fully-enriched body has no markers
+  assert.deepEqual(findCharterPlaceholders("# Charter\nAll concrete, no placeholders."), []);
+  assert.ok(findCharterPlaceholders("see {{agent.firstName}}").includes("unresolved {{token}}"));
+});
+
+test("buildCharterSkeleton requires both arguments", () => {
+  assert.throws(() => buildCharterSkeleton(null, IDENTITY), /requires/);
+});
+
+// --- charter source-of-truth: render FROM a Cohort-authored CharterDTO -------
+
+const ORG_CHARTER = {
+  approvedByLine: "Approved by Dana Reyes, CEO — 2026-06-01",
+  gatesText: "Irreversible spend > $25k escalates to the principal.",
+  sections: [
+    { kind: "decision_rights", order: 2, title: null, body: "Owns the deploy cadence; recommends headcount." },
+    { kind: "purpose", order: 1, title: "Purpose & Mandate", body: "Own platform reliability and developer velocity." },
+  ],
+};
+
+test("renderCohortCharter renders sections in order with the authored bodies", () => {
+  const md = renderCohortCharter(ORG_CHARTER, IDENTITY, { date: "2026-06-01" });
+  assert.match(md, /# Operating Charter — Jacob Chen/);
+  assert.match(md, /Authored in Cohort \(org source of truth\)/);
+  assert.match(md, /Approved by Dana Reyes, CEO — 2026-06-01/);
+  // section 1 (order 1) renders before section 2 (order 2)
+  const iPurpose = md.indexOf("Purpose & Mandate");
+  const iRights = md.indexOf("Decision Rights"); // title null → title-cased kind
+  assert.ok(iPurpose > 0 && iRights > iPurpose, "sections render in `order`");
+  assert.match(md, /Own platform reliability and developer velocity\./);
+  assert.match(md, /Owns the deploy cadence; recommends headcount\./);
+  // gates block
+  assert.match(md, /## Gates/);
+  assert.match(md, /Irreversible spend > \$25k escalates/);
+});
+
+test("renderCohortCharter requires a charter object", () => {
+  assert.throws(() => renderCohortCharter(null, IDENTITY), /requires/);
+});

package/lib/claude-bin.mjs

@@ -0,0 +1,134 @@
+/**
+ * Maestro — Claude CLI binary resolver.
+ *
+ * Shared utility for every code path that spawns `claude --print`.
+ * launchd's bare environment does NOT include ~/.local/bin or homebrew
+ * paths, so a plain `spawn('claude', …)` from a daemon-spawned process
+ * fails with ENOENT — even though the operator's interactive shell finds
+ * it without trouble.
+ *
+ * Caller sites:
+ *   - scripts/daemon/dispatcher.mjs   (reactive: replies to Slack/Gmail/etc)
+ *   - scripts/daemon/responder.mjs    (quick replies + holding messages)
+ *   - scripts/daemon/cadence-consumer.mjs (scheduled cadence ticks)
+ *   - scripts/poller/intra-session-check.mjs
+ *   - any other module that spawns claude from a non-interactive context
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+let _resolved = null;
+
+/**
+ * Is `p` a regular file that is safe to execute as this agent? An attacker who
+ * can rewrite the resolved binary — or point $CLAUDE_BIN at one they control —
+ * gets code execution as the agent on the next spawn, which on an unattended
+ * 24/7 Mac mini is a realistic local-persistence vector. We therefore require
+ * the file to exist, be a regular file, not be group/world-writable, and be
+ * owned by this user or root. (M2)
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function isSafeExecutable(p) {
+  try {
+    const st = statSync(p);
+    if (!st.isFile()) return false;
+    // Reject group- or world-writable binaries (someone other than the owner
+    // could swap the executable out from under us).
+    if (st.mode & 0o022) return false;
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (uid !== null && st.uid !== uid && st.uid !== 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the absolute path to the Claude CLI. Searches, in order:
+ *   1. $CLAUDE_BIN env var (if set + executable on disk)
+ *   2. ~/.local/bin/claude       (default Claude Code install location)
+ *   3. /opt/homebrew/bin/claude  (Apple Silicon homebrew)
+ *   4. /usr/local/bin/claude     (Intel homebrew)
+ *   5. /usr/bin/claude
+ *
+ * Falls back to bare "claude" so the spawn's own error stays informative
+ * if nothing on the search path exists.
+ */
+export function resolveClaudeBin() {
+  if (_resolved) return _resolved;
+  const envOverride = process.env.CLAUDE_BIN;
+  // The env override is the highest-trust candidate, so it gets the full
+  // safety check (M2). If it is set but unsafe/missing, we log and fall
+  // through to the known-good fixed locations rather than trusting it.
+  if (envOverride) {
+    if (isSafeExecutable(envOverride)) { _resolved = envOverride; return envOverride; }
+    console.error(
+      `[claude-bin] Ignoring CLAUDE_BIN=${envOverride}: not a safe, owner-only, ` +
+      `non-writable executable. Falling back to default search paths.`
+    );
+  }
+  const candidates = [
+    join(homedir(), ".local/bin/claude"),
+    "/opt/homebrew/bin/claude",
+    "/usr/local/bin/claude",
+    "/usr/bin/claude",
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) { _resolved = c; return c; }
+  }
+  // Last resort: bare name (lets the OS PATH + spawn error stay informative).
+  // Do NOT memoize this — if the CLI gets installed later, a long-lived daemon
+  // should pick it up on the next call rather than caching the fallback. (L28)
+  return "claude";
+}
+
+/**
+ * Default args every daemon-spawned `claude --print` should receive on
+ * top of the prompt + model selection. Currently:
+ *
+ *   --strict-mcp-config
+ *     Skip every globally-installed Claude Code MCP plugin (Serena,
+ *     Playwright, etc). Daemon spawns don't need IDE-grade code
+ *     intelligence; they need to write a Slack reply / draft an email
+ *     / classify an item. Loading MCPs wastes 3-5s per spawn AND opens
+ *     a browser dashboard tab per session (Serena does this).
+ *
+ *   --bare                                                   (opt-in via DAEMON_BARE_MODE=1)
+ *     Skip hooks, LSP, plugin sync, auto-memory, keychain reads. Even
+ *     more minimal. Use when you specifically want a stateless spawn —
+ *     but it disables Keychain OAuth, so MAESTRO_PREFER_SUBSCRIPTION_AUTH
+ *     callers should NOT set this.
+ *
+ * Operators who want full MCP support on daemon spawns can set
+ * DAEMON_LOAD_MCPS=1 in .env; the spawn sites will skip these flags.
+ */
+export function daemonClaudeArgs() {
+  if (process.env.DAEMON_LOAD_MCPS === "1") return [];
+  const args = ["--strict-mcp-config"];
+  if (process.env.DAEMON_BARE_MODE === "1") args.unshift("--bare");
+  return args;
+}
+
+/**
+ * Build a PATH suitable for child processes spawned from a daemon.
+ * launchd strips PATH down to /usr/bin:/bin; this returns a string that
+ * preserves the caller's PATH if set, then appends the locations claude
+ * subsessions might need to find node, jq, gh, etc.
+ */
+export function augmentedPath() {
+  return [
+    process.env.PATH || "",
+    `${homedir()}/.local/bin`,
+    "/opt/homebrew/bin",
+    "/opt/homebrew/sbin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+  ].filter(Boolean).join(":");
+}

package/lib/claude-bin.test.mjs

@@ -0,0 +1,75 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isSafeExecutable, augmentedPath, daemonClaudeArgs } from "./claude-bin.mjs";
+
+function tmp() {
+  return mkdtempSync(join(tmpdir(), "claude-bin-test-"));
+}
+
+test("isSafeExecutable accepts an owner-only, non-writable regular file", () => {
+  const dir = tmp();
+  try {
+    const p = join(dir, "claude");
+    writeFileSync(p, "#!/bin/sh\n");
+    chmodSync(p, 0o755);
+    assert.equal(isSafeExecutable(p), true);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("isSafeExecutable rejects a world-writable file (swap vector)", () => {
+  const dir = tmp();
+  try {
+    const p = join(dir, "claude");
+    writeFileSync(p, "#!/bin/sh\n");
+    chmodSync(p, 0o757); // world-writable
+    assert.equal(isSafeExecutable(p), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("isSafeExecutable rejects a group-writable file", () => {
+  const dir = tmp();
+  try {
+    const p = join(dir, "claude");
+    writeFileSync(p, "#!/bin/sh\n");
+    chmodSync(p, 0o775); // group-writable
+    assert.equal(isSafeExecutable(p), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("isSafeExecutable rejects a nonexistent path without throwing", () => {
+  assert.equal(isSafeExecutable("/nope/does/not/exist/claude"), false);
+});
+
+test("isSafeExecutable rejects a directory", () => {
+  const dir = tmp();
+  try {
+    assert.equal(isSafeExecutable(dir), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("augmentedPath includes common bin locations and preserves existing PATH", () => {
+  const p = augmentedPath();
+  assert.ok(p.includes("/usr/bin"));
+  assert.ok(p.includes("/opt/homebrew/bin"));
+});
+
+test("daemonClaudeArgs returns strict-mcp-config by default", () => {
+  const prev = process.env.DAEMON_LOAD_MCPS;
+  delete process.env.DAEMON_LOAD_MCPS;
+  try {
+    assert.deepEqual(daemonClaudeArgs(), ["--strict-mcp-config"]);
+  } finally {
+    if (prev !== undefined) process.env.DAEMON_LOAD_MCPS = prev;
+  }
+});