@cohortapp/agent-sdk 2.3.0

package/lib/setup/context-pack.test.mjs

@@ -0,0 +1,89 @@
+/**
+ * context-pack.test.mjs — deterministic context gathering (lib/setup/context-pack.mjs).
+ * Run: `node --test lib/setup/context-pack.test.mjs`
+ * @module lib/setup/context-pack.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildContextPack, gatherContextPack, readContextPack, CONTEXT_PACK_REL } from "./context-pack.mjs";
+
+function tmpRoot() {
+  const r = mkdtempSync(join(tmpdir(), "maestro-ctx-"));
+  mkdirSync(join(r, "config"), { recursive: true });
+  return r;
+}
+
+test("buildContextPack merges identity + company + docs + readme", () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify({
+    firstName: "Jacob", title: "VP Eng", function: "technical-leader", altitude: "vp", company: "Acme",
+  }));
+  writeFileSync(join(root, "config/company.json"), JSON.stringify({
+    name: "Acme", website: "https://acme.com", products: ["Widget"], strategicPriorities: ["Grow"],
+  }));
+  mkdirSync(join(root, "docs/company-context"), { recursive: true });
+  writeFileSync(join(root, "docs/company-context/overview.md"), "# Acme\nWe build widgets.");
+  writeFileSync(join(root, "docs/company-context/ignore.png"), "binary");
+  writeFileSync(join(root, "README.md"), "Acme agent repo");
+
+  const pack = buildContextPack(root);
+  assert.equal(pack.identity.firstName, "Jacob");
+  assert.equal(pack.identity.function, "technical-leader");
+  assert.equal(pack.company.name, "Acme");
+  assert.deepEqual(pack.company.products, ["Widget"]);
+  assert.equal(pack.contextDocs.length, 1, "only .md/.txt docs included");
+  assert.match(pack.contextDocs[0].excerpt, /widgets/);
+  assert.match(pack.readmeExcerpt, /Acme agent repo/);
+});
+
+test("gatherContextPack writes state/setup/context-pack.json", () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify({ firstName: "Mara" }));
+  const pack = gatherContextPack(root);
+  assert.ok(existsSync(join(root, CONTEXT_PACK_REL)));
+  const back = readContextPack(root);
+  assert.equal(back.identity.firstName, "Mara");
+  assert.equal(pack.identity.firstName, "Mara");
+});
+
+test("buildContextPack tolerates missing files (no throw)", () => {
+  const root = tmpRoot();
+  const pack = buildContextPack(root);
+  assert.equal(pack.identity.firstName, "");
+  assert.deepEqual(pack.contextDocs, []);
+});
+
+test("buildContextPack omits orgContext when no org-context cache exists", () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify({ firstName: "Solo" }));
+  const pack = buildContextPack(root);
+  assert.equal("orgContext" in pack, false, "a standalone agent's pack shape is unchanged");
+});
+
+test("buildContextPack folds a bounded org-context excerpt in when enrolled (finding: fetched context shapes nothing)", () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify({ firstName: "Robin" }));
+  writeFileSync(join(root, "config/org-context.json"), JSON.stringify({
+    fetchedAt: "2026-07-03T00:00:00Z",
+    profile: { slug: "robin", title: "VP Ops", escalationPath: "→ COO", autonomyLevel: "high", reports: [{ member: { slug: "kai", displayName: "Kai" } }] },
+    strategy: { northStar: "Own the fund's operating substrate", levers: [{ label: "Automate ops" }], streams: [{ code: "S1", name: "Go-live", mission: "Ship v1" }] },
+    decisions: [{ title: "Adopt Postgres" }],
+    board: [{ title: "Wire the ready feed" }],
+  }));
+  const pack = buildContextPack(root);
+  assert.ok(pack.orgContext, "orgContext excerpt is present when the cache exists");
+  assert.equal(pack.orgContext.self.slug, "robin");
+  assert.equal(pack.orgContext.self.escalationPath, "→ COO");
+  assert.equal(pack.orgContext.strategy.northStar, "Own the fund's operating substrate");
+  assert.deepEqual(pack.orgContext.strategy.levers, ["Automate ops"]);
+  assert.equal(pack.orgContext.strategy.streams[0].code, "S1");
+  assert.deepEqual(pack.orgContext.reports, ["Kai"]);
+  assert.deepEqual(pack.orgContext.adoptedDecisions, ["Adopt Postgres"]);
+  assert.deepEqual(pack.orgContext.readyBoard, ["Wire the ready feed"]);
+});

package/lib/setup/enrich.mjs

@@ -0,0 +1,277 @@
+/**
+ * lib/setup/enrich.mjs — the bounded LLM enrichment function.
+ *
+ * The deterministic spine generates structurally-complete skeletons with
+ * company-specific "slots" left as placeholders (TBD / {{tokens}} / empty prose
+ * arrays). `enrichField` fills ONE enumerated prose unit by spawning a single
+ * `claude --print` with a field-allowlist contract:
+ *
+ *   system = communication-style rules + "fill ONLY these JSON keys"
+ *   input  = archetype profile + context pack + the skeleton + the placeholder list
+ *   output = strict JSON containing only the allowlisted keys
+ *
+ * Output is validated (right keys, non-empty, no residual {{}}, no banned
+ * phrases from policies/communication-style.md). On any failure — bad JSON,
+ * wrong keys, banned phrase, spawn error — the skeleton is LEFT UNTOUCHED, the
+ * field is marked `pending`, and the function returns without throwing
+ * (fail-open, per design principle 2).
+ *
+ * Enumerated enrichable units ONLY (design §4):
+ *   agent.persona | agent.responsibilities | agent.operatingPrinciples
+ *   company.description | charter.companySlots | backlog.companySlots
+ *
+ * The actual `claude --print` spawn is injected via `opts.spawn` so tests stay
+ * hermetic; production uses resolveClaudeBin()+daemonClaudeArgs()+execFile.
+ *
+ * @module lib/setup/enrich
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { resolveClaudeBin, daemonClaudeArgs } from "../claude-bin.mjs";
+import { mergeAgentJson, readAgentJson } from "./sot.mjs";
+import { readContextPack } from "./context-pack.mjs";
+import { markEnrich } from "./state.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = join(HERE, "..", "..");
+
+/** Banned AI-tell phrases (mirrors policies/communication-style.md §Default tone). */
+export const BANNED_PHRASES = [
+  "i'm here to help",
+  "let me know if you need anything else",
+  "i hope this helps",
+  "feel free to ask if you have any questions",
+  "as an ai",
+  "as a language model",
+  "certainly!",
+  "absolutely!",
+  "great question!",
+  "here's a comprehensive overview",
+  "i'd be happy to",
+];
+
+/**
+ * The allowlist of enrichable units and the agent.json keys each owns.
+ * `kind: "agentJson"` units write prose directly into config/agent.json;
+ * `kind: "regen"` units enrich a sibling file then re-run a generator (handled
+ * by the caller/section — here we only validate + persist the JSON-shaped ones).
+ */
+export const ENRICHABLE = {
+  "agent.persona": { kind: "agentJson", keys: ["persona"], type: "string" },
+  "agent.responsibilities": { kind: "agentJson", keys: ["responsibilities"], type: "string[]" },
+  "agent.operatingPrinciples": { kind: "agentJson", keys: ["operatingPrinciples"], type: "string[]" },
+  "company.description": { kind: "companyJson", keys: ["description"], type: "string" },
+  // Charter company-slots: the model fills the concrete mandate, a KPI-target
+  // phrasing, and a default stakeholder-contact phrasing; the enrich section
+  // substitutes these into the deterministic charter body (clearing TBD slots).
+  "charter.companySlots": { kind: "charter", keys: ["mandate", "kpiTarget", "stakeholderContact"], type: "string" },
+  "backlog.companySlots": { kind: "regen", keys: ["focus"], type: "string" },
+};
+
+function containsBanned(text) {
+  const low = String(text).toLowerCase();
+  return BANNED_PHRASES.find((p) => low.includes(p)) || null;
+}
+
+function hasResidualToken(text) {
+  return /\{\{[^}]+\}\}/.test(String(text));
+}
+
+/**
+ * Validate a parsed enrichment object against a unit spec. Returns
+ * { ok, value?, reason? }. `value` is the cleaned, validated payload for the
+ * unit's keys.
+ * @param {object} parsed
+ * @param {{keys:string[], type:string}} spec
+ */
+export function validateEnrichment(parsed, spec) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { ok: false, reason: "output was not a JSON object" };
+  }
+  const out = {};
+  for (const key of spec.keys) {
+    if (!(key in parsed)) return { ok: false, reason: `missing key "${key}"` };
+    const v = parsed[key];
+    if (spec.type === "string[]") {
+      if (!Array.isArray(v) || v.length === 0) return { ok: false, reason: `"${key}" must be a non-empty array` };
+      for (const item of v) {
+        if (typeof item !== "string" || !item.trim()) return { ok: false, reason: `"${key}" has an empty entry` };
+        if (hasResidualToken(item)) return { ok: false, reason: `"${key}" has a residual {{token}}` };
+        const banned = containsBanned(item);
+        if (banned) return { ok: false, reason: `"${key}" contains banned phrase: ${banned}` };
+      }
+      out[key] = v.map((s) => s.trim());
+    } else {
+      if (typeof v !== "string" || !v.trim()) return { ok: false, reason: `"${key}" must be a non-empty string` };
+      if (hasResidualToken(v)) return { ok: false, reason: `"${key}" has a residual {{token}}` };
+      const banned = containsBanned(v);
+      if (banned) return { ok: false, reason: `"${key}" contains banned phrase: ${banned}` };
+      out[key] = v.trim();
+    }
+  }
+  return { ok: true, value: out };
+}
+
+/** Extract the first balanced JSON object from possibly-noisy model output. */
+export function parseStrictJson(raw) {
+  if (typeof raw !== "string") return null;
+  const text = raw.trim();
+  // Prefer a fenced ```json block if present.
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fence ? fence[1].trim() : text;
+  // Try direct parse first.
+  try { return JSON.parse(candidate); } catch { /* fall through */ }
+  // Otherwise grab the outermost {...}.
+  const start = candidate.indexOf("{");
+  const end = candidate.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    try { return JSON.parse(candidate.slice(start, end + 1)); } catch { /* nope */ }
+  }
+  return null;
+}
+
+/** Read the communication-style policy once for the system prompt. */
+function commStyleRules() {
+  const p = join(MAESTRO_ROOT, "policies", "communication-style.md");
+  try { return readFileSync(p, "utf-8").slice(0, 4000); } catch { return ""; }
+}
+
+/**
+ * Build the system + user prompt for a unit. Exposed for testing.
+ * @param {string} unit
+ * @param {object} pack context pack
+ * @param {object} skeleton current agent.json (or relevant slice)
+ */
+export function buildPrompt(unit, pack, skeleton) {
+  const spec = ENRICHABLE[unit];
+  const keys = spec ? spec.keys : [];
+  const system = [
+    "You write company-specific prose for an autonomous enterprise AI agent.",
+    "Voice & tone rules you MUST obey (from policies/communication-style.md):",
+    commStyleRules(),
+    "",
+    `Output a single strict JSON object containing ONLY these keys: ${JSON.stringify(keys)}.`,
+    "No prose outside the JSON. No markdown fences. No extra keys.",
+    "Do not include any {{template tokens}}. Do not use assistant-y filler.",
+  ].join("\n");
+  const user = [
+    `Enrich the field unit "${unit}" for this agent.`,
+    `Archetype: ${pack && pack.identity ? `${pack.identity.function} × ${pack.identity.altitude}` : "(unknown)"}`,
+    `Identity: ${JSON.stringify(pack && pack.identity ? pack.identity : {})}`,
+    `Company: ${JSON.stringify(pack && pack.company ? pack.company : {})}`,
+    pack && pack.contextDocs && pack.contextDocs.length
+      ? `Context docs:\n${pack.contextDocs.map((d) => `- ${d.name}: ${d.excerpt.slice(0, 500)}`).join("\n")}`
+      : "Context docs: (none)",
+    `Current skeleton slice: ${JSON.stringify(skeleton)}`,
+    `Return JSON with keys ${JSON.stringify(keys)} only.`,
+  ].join("\n\n");
+  return { system, user };
+}
+
+/**
+ * Default spawn: one `claude --print`, returning stdout (or rejecting on error).
+ * @param {{system:string, user:string}} prompt
+ * @param {object} opts
+ * @returns {Promise<string>}
+ */
+function defaultSpawn(prompt, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const bin = resolveClaudeBin();
+    const args = [
+      "--print",
+      ...daemonClaudeArgs(),
+      "--model", opts.model || "claude-sonnet-4-6",
+      "--append-system-prompt", prompt.system,
+      prompt.user,
+    ];
+    execFile(bin, args, { encoding: "utf-8", timeout: opts.timeoutMs || 60000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+      if (err) return reject(err);
+      resolve(stdout || "");
+    });
+  });
+}
+
+/**
+ * Enrich a single field unit. Fail-open: returns a result object, never throws.
+ *
+ * @param {string} agentRoot
+ * @param {string} unit  one of ENRICHABLE keys
+ * @param {object} [opts]
+ * @param {(prompt:object, opts:object)=>Promise<string>} [opts.spawn]  injectable spawn (for tests)
+ * @param {boolean} [opts.persist=true]  write the validated value into agent.json
+ * @returns {Promise<{unit:string, status:'enriched'|'pending'|'skipped', reason?:string, value?:object}>}
+ */
+export async function enrichField(agentRoot, unit, opts = {}) {
+  const spec = ENRICHABLE[unit];
+  if (!spec) {
+    return { unit, status: "skipped", reason: `unit "${unit}" is not enrichable` };
+  }
+  const persist = opts.persist !== false;
+  const record = (status, reason) => { try { markEnrich(agentRoot, unit, { status, reason }); } catch { /* fail-open */ } };
+
+  let raw;
+  try {
+    const pack = readContextPack(agentRoot) || {};
+    const skeleton = sliceSkeleton(agentRoot, spec);
+    const prompt = buildPrompt(unit, pack, skeleton);
+    const spawn = opts.spawn || defaultSpawn;
+    raw = await spawn(prompt, opts);
+  } catch (e) {
+    record("pending", `spawn failed: ${e && e.message ? e.message : e}`);
+    return { unit, status: "pending", reason: "spawn failed" };
+  }
+
+  const parsed = parseStrictJson(raw);
+  if (!parsed) {
+    record("pending", "could not parse strict JSON");
+    return { unit, status: "pending", reason: "unparseable output" };
+  }
+  const v = validateEnrichment(parsed, spec);
+  if (!v.ok) {
+    record("pending", v.reason);
+    return { unit, status: "pending", reason: v.reason };
+  }
+
+  if (persist && spec.kind === "agentJson") {
+    try { mergeAgentJson(agentRoot, v.value); }
+    catch (e) { record("pending", `persist failed: ${e && e.message ? e.message : e}`); return { unit, status: "pending", reason: "persist failed" }; }
+  } else if (persist && spec.kind === "companyJson") {
+    try { mergeCompanyJson(agentRoot, v.value); }
+    catch (e) { record("pending", `persist failed: ${e && e.message ? e.message : e}`); return { unit, status: "pending", reason: "persist failed" }; }
+  }
+  // kind:"regen" units return the value; the caller folds it into the relevant
+  // generator input + re-runs the generator (the regen path is section-owned).
+
+  record("enriched");
+  return { unit, status: "enriched", value: v.value };
+}
+
+/** The slice of the SoT relevant to a unit (keeps the prompt small + focused). */
+function sliceSkeleton(agentRoot, spec) {
+  if (spec.kind === "companyJson") {
+    try { const p = join(agentRoot, "config", "company.json"); return existsSync(p) ? JSON.parse(readFileSync(p, "utf-8")) : {}; }
+    catch { return {}; }
+  }
+  const id = readAgentJson(agentRoot) || {};
+  const out = {};
+  for (const k of spec.keys) out[k] = id[k];
+  // include identity context the model needs
+  out._identity = { firstName: id.firstName, title: id.title, function: id.function, altitude: id.altitude, company: id.company };
+  return out;
+}
+
+function mergeCompanyJson(agentRoot, patch) {
+  const p = join(agentRoot, "config", "company.json");
+  const cur = existsSync(p) ? JSON.parse(readFileSync(p, "utf-8")) : {};
+  const merged = { ...cur, ...patch };
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+  renameSync(tmp, p);
+  return merged;
+}

package/lib/setup/enrich.test.mjs

@@ -0,0 +1,115 @@
+/**
+ * enrich.test.mjs — bounded LLM enrichment (lib/setup/enrich.mjs).
+ * The claude spawn is injected (fake) so the test is hermetic — no network.
+ * Run: `node --test lib/setup/enrich.test.mjs`
+ * @module lib/setup/enrich.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  enrichField, validateEnrichment, parseStrictJson, buildPrompt, ENRICHABLE, BANNED_PHRASES,
+} from "./enrich.mjs";
+import { gatherContextPack } from "./context-pack.mjs";
+import { readAgentJson } from "./sot.mjs";
+import { loadProgress } from "./state.mjs";
+
+function tmpRoot() {
+  const r = mkdtempSync(join(tmpdir(), "maestro-enrich-"));
+  mkdirSync(join(r, "config"), { recursive: true });
+  writeFileSync(join(r, "config/agent.json"), JSON.stringify({
+    firstName: "Jacob", title: "VP Eng", function: "technical-leader", altitude: "vp", company: "Acme",
+    responsibilities: [], operatingPrinciples: [],
+  }, null, 2));
+  writeFileSync(join(r, "config/company.json"), JSON.stringify({ name: "Acme", description: "" }, null, 2));
+  gatherContextPack(r);
+  return r;
+}
+
+test("parseStrictJson handles fenced and raw JSON and noisy output", () => {
+  assert.deepEqual(parseStrictJson('{"a":1}'), { a: 1 });
+  assert.deepEqual(parseStrictJson("```json\n{\"a\":2}\n```"), { a: 2 });
+  assert.deepEqual(parseStrictJson("Sure!\n{\"a\":3}\nthanks"), { a: 3 });
+  assert.equal(parseStrictJson("no json here"), null);
+});
+
+test("validateEnrichment enforces keys, types, tokens, banned phrases", () => {
+  const spec = ENRICHABLE["agent.responsibilities"];
+  assert.equal(validateEnrichment({ responsibilities: ["Own platform reliability"] }, spec).ok, true);
+  assert.equal(validateEnrichment({ wrong: [] }, spec).ok, false);
+  assert.equal(validateEnrichment({ responsibilities: [] }, spec).ok, false);
+  assert.equal(validateEnrichment({ responsibilities: ["see {{x}}"] }, spec).ok, false);
+  const banned = validateEnrichment({ responsibilities: ["As an AI, I will help"] }, spec);
+  assert.equal(banned.ok, false);
+  assert.match(banned.reason, /banned phrase/);
+});
+
+test("buildPrompt requests only the unit's keys", () => {
+  const p = buildPrompt("agent.persona", { identity: {}, company: {} }, { persona: "" });
+  assert.match(p.system, /\["persona"\]/);
+  assert.match(p.user, /agent\.persona/);
+});
+
+test("enrichField writes validated prose into agent.json (faked spawn)", async () => {
+  const root = tmpRoot();
+  const fakeSpawn = async () => JSON.stringify({ responsibilities: ["Run the platform org", "Own delivery confidence"] });
+  const res = await enrichField(root, "agent.responsibilities", { spawn: fakeSpawn });
+  assert.equal(res.status, "enriched");
+  const cfg = readAgentJson(root);
+  assert.deepEqual(cfg.responsibilities, ["Run the platform org", "Own delivery confidence"]);
+  // other keys untouched
+  assert.equal(cfg.firstName, "Jacob");
+  // ledger updated
+  assert.equal(loadProgress(root).enrich["agent.responsibilities"].status, "enriched");
+});
+
+test("enrichField is fail-open on bad JSON — leaves skeleton, marks pending", async () => {
+  const root = tmpRoot();
+  const before = readAgentJson(root);
+  const fakeSpawn = async () => "definitely not json";
+  const res = await enrichField(root, "agent.persona", { spawn: fakeSpawn });
+  assert.equal(res.status, "pending");
+  assert.deepEqual(readAgentJson(root), before, "agent.json unchanged on failure");
+  assert.equal(loadProgress(root).enrich["agent.persona"].status, "pending");
+});
+
+test("enrichField is fail-open on spawn throw (no network)", async () => {
+  const root = tmpRoot();
+  const fakeSpawn = async () => { throw new Error("ENOENT claude"); };
+  const res = await enrichField(root, "agent.operatingPrinciples", { spawn: fakeSpawn });
+  assert.equal(res.status, "pending");
+  assert.match(res.reason, /spawn failed/);
+});
+
+test("enrichField rejects a banned-phrase response (stays pending)", async () => {
+  const root = tmpRoot();
+  const fakeSpawn = async () => JSON.stringify({ persona: "I'm here to help with anything you need." });
+  const res = await enrichField(root, "agent.persona", { spawn: fakeSpawn });
+  assert.equal(res.status, "pending");
+  assert.match(res.reason, /banned phrase/);
+});
+
+test("enrichField writes company.description for companyJson unit", async () => {
+  const root = tmpRoot();
+  const fakeSpawn = async () => JSON.stringify({ description: "Acme builds developer tooling for fintechs." });
+  const res = await enrichField(root, "company.description", { spawn: fakeSpawn });
+  assert.equal(res.status, "enriched");
+  const co = JSON.parse(readFileSync(join(root, "config/company.json"), "utf-8"));
+  assert.match(co.description, /developer tooling/);
+});
+
+test("enrichField skips unknown units", async () => {
+  const root = tmpRoot();
+  const res = await enrichField(root, "not.a.unit", { spawn: async () => "{}" });
+  assert.equal(res.status, "skipped");
+});
+
+test("BANNED_PHRASES includes the canonical AI-tells", () => {
+  assert.ok(BANNED_PHRASES.includes("as an ai"));
+  assert.ok(BANNED_PHRASES.includes("i'd be happy to"));
+});