@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/identity/persona.mjs

@@ -0,0 +1,247 @@
+/**
+ * persona.mjs — renders an agent's identity into the block that leads every
+ * LLM prompt the agent runs under.
+ *
+ * WHY THIS EXISTS
+ *   The daemon used to build its preamble by scraping four prose sections out of
+ *   the agent's CLAUDE.md (`extractPreamble` in scripts/daemon/prompt-builder.mjs).
+ *   That had two failure modes, both of which we hit in production:
+ *
+ *     1. A freshly-scaffolded repo has "*Configured by `maestro setup`*" sitting
+ *        in those sections. The model was handed a near-empty identity and fell
+ *        back to the generic-assistant register it ships with — introducing and
+ *        signing itself as "an AI assistant working on behalf of <principal>",
+ *        deferring on matters inside its own mandate, and writing to colleagues
+ *        as a support function rather than as the person holding the role.
+ *
+ *     2. Everything the org actually knows about the member — title, seniority
+ *        band, background, tone of voice, responsibilities, operating principles,
+ *        charter — is pulled from the Cohort server into config/agent.json by
+ *        lib/setup/enroll-from-cohort.mjs, and was then read by NOTHING on the
+ *        prompt path. A fully-enrolled agent got no more persona than an empty one.
+ *
+ *   This module closes both. It renders config/agent.json (+ config/company.json)
+ *   — the source of truth, kept in sync with Cohort — into a persona block, and
+ *   the prompt builder prepends it unconditionally. Identity now degrades
+ *   gracefully instead of silently: an unconfigured field is omitted, not faked.
+ *
+ * SCOPE — what this module does NOT do
+ *   It does not touch the AI-disclosure truthfulness invariant. An agent that is
+ *   sincerely asked whether it is an AI still answers plainly, and
+ *   policies/ai-disclosure.yaml remains the authority on that. What changes here
+ *   is that the agent stops volunteering a standing disclaimer on work nobody
+ *   asked to have disclaimed. Honesty on demand, not self-deprecation by default.
+ *   See `voiceRules()` — the honesty bullet is deliberately part of the block,
+ *   not an afterthought bolted on elsewhere.
+ *
+ * Pure-function core (`renderPersona`) so it is testable without a filesystem;
+ * `loadPersonaBlock` does the I/O and never throws.
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * Human-readable gloss for each archetype altitude band (archetypes/altitudes/).
+ * Used to tell the model what standing the seat carries, because a title string
+ * alone ("SVP AI Systems & Agent Platform") does not reliably convey it.
+ */
+const ALTITUDE_STANDING = Object.freeze({
+  founder:
+    "You are a founder. You set direction rather than wait for it, and you carry final say on most things short of the board.",
+  "c-suite":
+    "You sit on the executive team. You own your function end to end and are expected to take positions, not to relay options upward.",
+  svp:
+    "You are a senior vice president. You run your area with real independence — you decide within it and escalate only what genuinely crosses another owner's remit.",
+  vp:
+    "You are a vice president. You own your area's outcomes and make the calls inside it; you bring your principal decisions, not questions.",
+  "senior-manager":
+    "You are a senior manager. You own delivery in your area and decide the how; you agree the what with your principal.",
+});
+
+/** Trim to a string, or "" for anything nullish/non-scalar. */
+function s(v) {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "string") return v.trim();
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return "";
+}
+
+/** Normalise to a clean string[] — drops blanks, coerces scalars, ignores junk. */
+function list(v) {
+  if (!Array.isArray(v)) return [];
+  return v.map(s).filter(Boolean);
+}
+
+/**
+ * Free-prose persona/background, wherever the org happens to have put it.
+ * Cohort profile sections land in `persona`; older configs used `bio`/`background`.
+ * @param {object} a config/agent.json
+ * @returns {string}
+ */
+function personaProse(a) {
+  return s(a.persona) || s(a.background) || s(a.bio) || "";
+}
+
+/**
+ * The reporting line, phrased as a peer relationship rather than a service one.
+ * Returns "" when no principal is configured — better silent than invented.
+ * @param {object} a config/agent.json
+ * @returns {string}
+ */
+function reportingLine(a) {
+  const p = a.principal && typeof a.principal === "object" ? a.principal : {};
+  const name = s(p.fullName) || s(p.firstName);
+  if (!name) return "";
+  const title = s(p.title);
+  return title ? `You report to ${name}, ${title}.` : `You report to ${name}.`;
+}
+
+/**
+ * The voice rules — the behavioural half of the block, and the reason it exists.
+ *
+ * These are phrased as standing facts about who the agent is rather than as
+ * prohibitions, because a negative instruction ("don't call yourself an AI")
+ * tends to be obeyed literally and narrowly while the underlying deferential
+ * register survives. The final bullet preserves the non-overridable truthfulness
+ * invariant from policies/ai-disclosure.yaml in the same breath — the agent is
+ * senior AND honest, and neither is traded for the other.
+ *
+ * @param {object} a config/agent.json
+ * @returns {string[]} bullet lines
+ */
+function voiceRules(a) {
+  const principal = a.principal && typeof a.principal === "object" ? a.principal : {};
+  const pName = s(principal.firstName) || s(principal.fullName);
+  // Only claim a reporting line when one is actually configured. Asserting
+  // "you report to your principal" at an agent with no principal on record
+  // invents a relationship and re-introduces the deference we are removing.
+  const reportsClause = pName
+    ? ` You report to ${pName} the way any senior colleague reports to their manager, and you do not preface your work with that fact.`
+    : "";
+
+  return [
+    "You hold this role. Write as the person who holds it — with the judgement, standing and directness the title carries. You are a full member of this team, not a service attached to it.",
+    `Do not introduce, describe or sign yourself as an assistant, a bot, an AI helper, or as "working on behalf of" someone.${reportsClause}`,
+    "Do not position yourself as junior to whoever you are writing to, including your principal or the CEO. State what you did, what you found, and what you recommend. Ask for a decision only when the decision is genuinely theirs to make.",
+    "Do not thank people for their patience, apologise for taking up their time, or hedge a finding you are confident in. Colleagues at your level do not do this, and it reads as a tell.",
+    "Disagree when you disagree, and say so first rather than burying it under agreement. A concern you soften into politeness is a concern you failed to raise.",
+    "Being straight about what you are is not negotiable and does not conflict with any of the above: if someone sincerely asks whether they are dealing with an AI, say so plainly and without drama. That is a direct answer to a direct question — not a standing disclaimer you attach to your own work.",
+  ];
+}
+
+/**
+ * Render the persona block from resolved config. Pure — no I/O, never throws.
+ *
+ * Every section is conditional: a field the org has not filled in is omitted
+ * rather than rendered as a placeholder, so a partially-enrolled agent gets a
+ * shorter block instead of a block full of "unconfigured".
+ *
+ * @param {object} agentCfg  parsed config/agent.json
+ * @param {object} [companyCfg] parsed config/company.json
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeVoiceRules=true] emit the "How you write" section
+ * @returns {string} the persona block, or "" when there is no identity at all
+ */
+export function renderPersona(agentCfg, companyCfg = {}, opts = {}) {
+  const a = agentCfg && typeof agentCfg === "object" ? agentCfg : {};
+  const co = companyCfg && typeof companyCfg === "object" ? companyCfg : {};
+  const { includeVoiceRules = true } = opts;
+
+  const name = s(a.fullName) || [s(a.firstName), s(a.lastName)].filter(Boolean).join(" ").trim();
+  const title = s(a.title);
+  const company = s(a.company) || s(co.name);
+
+  // No name and no title means nothing has been configured — emit nothing and
+  // let the caller fall back rather than render a hollow "You are ." line.
+  if (!name && !title) return "";
+
+  const out = [];
+  out.push("## Who you are");
+  out.push("");
+
+  const opener = [name, title && `${title}`].filter(Boolean).join(", ");
+  out.push(company ? `You are ${opener} at ${company}.` : `You are ${opener}.`);
+
+  const standing = ALTITUDE_STANDING[s(a.altitude)];
+  if (standing) out.push(standing);
+
+  const reports = reportingLine(a);
+  if (reports) out.push(reports);
+
+  const desc = s(a.companyDescription) || s(co.description);
+  if (desc) {
+    out.push("");
+    out.push(desc);
+  }
+
+  const prose = personaProse(a);
+  if (prose) {
+    out.push("");
+    out.push("### Background");
+    out.push("");
+    out.push(prose);
+  }
+
+  const responsibilities = list(a.responsibilities);
+  if (responsibilities.length) {
+    out.push("");
+    out.push("### What you own");
+    out.push("");
+    for (const r of responsibilities) out.push(`- ${r}`);
+  }
+
+  const principles = list(a.operatingPrinciples);
+  if (principles.length) {
+    out.push("");
+    out.push("### How you operate");
+    out.push("");
+    for (const p of principles) out.push(`- ${p}`);
+  }
+
+  const comms = a.communication && typeof a.communication === "object" ? a.communication : {};
+  const defaultTone = s(comms.defaultTone);
+  const externalTone = s(comms.externalTone);
+  if (defaultTone || externalTone) {
+    out.push("");
+    out.push("### Your register");
+    out.push("");
+    if (defaultTone) out.push(`- Default tone: ${defaultTone}`);
+    if (externalTone) out.push(`- With people outside ${company || "the company"}: ${externalTone}`);
+  }
+
+  if (includeVoiceRules) {
+    out.push("");
+    out.push("### How you write and carry yourself");
+    out.push("");
+    for (const rule of voiceRules(a)) out.push(`- ${rule}`);
+  }
+
+  return out.join("\n").trim();
+}
+
+/**
+ * Read config/agent.json + config/company.json from an agent repo and render the
+ * persona block. Fail-open: any read/parse error yields "" so a malformed config
+ * degrades the prompt rather than taking the daemon down.
+ *
+ * @param {string} agentRoot absolute path to the agent repo
+ * @param {object} [opts] forwarded to renderPersona
+ * @returns {string}
+ */
+export function loadPersonaBlock(agentRoot, opts = {}) {
+  const read = (rel) => {
+    try {
+      return JSON.parse(readFileSync(join(agentRoot, rel), "utf-8"));
+    } catch {
+      return {};
+    }
+  };
+  try {
+    return renderPersona(read("config/agent.json"), read("config/company.json"), opts);
+  } catch {
+    return "";
+  }
+}
+
+export const _test = { ALTITUDE_STANDING, personaProse, reportingLine, voiceRules, list };

package/lib/identity/persona.test.mjs

@@ -0,0 +1,117 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { renderPersona, loadPersonaBlock } from "./persona.mjs";
+
+const AGENT = {
+  firstName: "Jamie",
+  lastName: "Okafor",
+  fullName: "Jamie Okafor",
+  title: "SVP AI Systems & Agent Platform",
+  altitude: "svp",
+  company: "Northwind",
+  principal: { firstName: "Robin", fullName: "Robin Vance", title: "Chief Product & Technology Officer" },
+  responsibilities: ["Agent platform reliability", "Fleet enrolment integrity"],
+  operatingPrinciples: ["Evidence over opinion"],
+  communication: { defaultTone: "warm-professional", externalTone: "formal" },
+};
+
+test("renders name, title, company and the seniority standing for the altitude band", () => {
+  const out = renderPersona(AGENT);
+  assert.match(out, /You are Jamie Okafor, SVP AI Systems & Agent Platform at Northwind\./);
+  assert.match(out, /You are a senior vice president\./);
+  assert.match(out, /You report to Robin Vance, Chief Product & Technology Officer\./);
+});
+
+test("renders responsibilities, principles and register when present", () => {
+  const out = renderPersona(AGENT);
+  assert.match(out, /### What you own/);
+  assert.match(out, /- Agent platform reliability/);
+  assert.match(out, /### How you operate/);
+  assert.match(out, /- Evidence over opinion/);
+  assert.match(out, /Default tone: warm-professional/);
+  assert.match(out, /outside Northwind: formal/);
+});
+
+// The regression this module exists for: the agent signing off as an AI
+// assistant working on behalf of its principal.
+test("instructs against assistant framing and on-behalf-of signatures", () => {
+  const out = renderPersona(AGENT);
+  assert.match(out, /Do not introduce, describe or sign yourself as an assistant/);
+  assert.match(out, /working on behalf of/); // named as the thing NOT to do
+  assert.match(out, /You report to Robin the way any senior colleague reports to their manager/);
+  assert.match(out, /full member of this team, not a service attached to it/);
+});
+
+// The truthfulness invariant in policies/ai-disclosure.yaml is locked and must
+// survive the seniority rewrite — senior AND honest, neither traded for the other.
+test("preserves the answer-truthfully-if-asked invariant", () => {
+  const out = renderPersona(AGENT);
+  assert.match(out, /sincerely asks whether they are dealing with an AI, say so plainly/);
+  assert.match(out, /not a standing disclaimer/);
+});
+
+test("omits unconfigured sections rather than rendering placeholders", () => {
+  const out = renderPersona({ fullName: "Ada Lovelace", title: "Head of Analysis" });
+  assert.match(out, /You are Ada Lovelace, Head of Analysis\./);
+  assert.doesNotMatch(out, /### What you own/);
+  assert.doesNotMatch(out, /### How you operate/);
+  assert.doesNotMatch(out, /### Your register/);
+  assert.doesNotMatch(out, /You report to/);
+  assert.doesNotMatch(out, /undefined|null|unconfigured/i);
+});
+
+test("returns empty string when there is no identity at all", () => {
+  assert.equal(renderPersona({}), "");
+  assert.equal(renderPersona(null), "");
+  assert.equal(renderPersona({ company: "Northwind" }), "");
+});
+
+test("persona prose falls back across persona → background → bio", () => {
+  assert.match(renderPersona({ ...AGENT, persona: "P-text" }), /### Background\n\nP-text/);
+  assert.match(renderPersona({ ...AGENT, background: "B-text" }), /### Background\n\nB-text/);
+  assert.match(renderPersona({ ...AGENT, bio: "Bio-text" }), /### Background\n\nBio-text/);
+});
+
+test("an unknown altitude drops the standing line without breaking the block", () => {
+  const out = renderPersona({ ...AGENT, altitude: "wizard" });
+  assert.match(out, /You are Jamie Okafor/);
+  assert.doesNotMatch(out, /senior vice president/);
+});
+
+test("company falls back to config/company.json when agent.json lacks it", () => {
+  const out = renderPersona({ fullName: "Ada Lovelace", title: "Head of Analysis" }, { name: "Northwind" });
+  assert.match(out, /Head of Analysis at Northwind\./);
+});
+
+test("includeVoiceRules:false emits identity only", () => {
+  const out = renderPersona(AGENT, {}, { includeVoiceRules: false });
+  assert.match(out, /You are Jamie Okafor/);
+  assert.doesNotMatch(out, /How you write and carry yourself/);
+});
+
+test("junk values in list fields are dropped, not rendered", () => {
+  const out = renderPersona({ ...AGENT, responsibilities: ["real", "", null, {}, 42] });
+  assert.match(out, /- real/);
+  assert.match(out, /- 42/);
+  assert.doesNotMatch(out, /\[object Object\]/);
+});
+
+test("loadPersonaBlock reads an agent repo, and fails open on a broken config", () => {
+  const dir = mkdtempSync(join(tmpdir(), "persona-"));
+  try {
+    mkdirSync(join(dir, "config"));
+    writeFileSync(join(dir, "config/agent.json"), JSON.stringify(AGENT));
+    assert.match(loadPersonaBlock(dir), /You are Jamie Okafor/);
+
+    writeFileSync(join(dir, "config/agent.json"), "{ not json");
+    assert.equal(loadPersonaBlock(dir), "");
+
+    assert.equal(loadPersonaBlock(join(dir, "nope")), "");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});