@cohortapp/agent-sdk 2.3.0

package/lib/rate-guard.mjs

@@ -0,0 +1,246 @@
+/**
+ * lib/rate-guard.mjs — cross-session 429 circuit breaker (WS4).
+ *
+ * Every spawn source (dispatcher, cadence consumer) consults ONE shared,
+ * file-backed breaker per provider before launching a `claude --print`
+ * sub-session. When a provider returns 429 / "rate limit" / "overloaded",
+ * the breaker opens for a decorrelated-jitter backoff window so all sources
+ * back off together instead of each discovering the limit independently and
+ * hammering the API.
+ *
+ * State lives at `state/rate-limits/<provider>.json`:
+ *   {
+ *     "openUntil":       <epoch ms — breaker stays open until this time>,
+ *     "consecutive429":  <count of back-to-back rate-limit hits>,
+ *     "lastBackoffMs":   <the most recent backoff window in ms>,
+ *     "updatedAt":       <ISO ts of the last mutation>
+ *   }
+ *
+ * Backoff is "decorrelated jitter" (AWS architecture blog): each new backoff
+ * is a uniform random pick in [base, prevBackoff * 3], capped at 15 min. This
+ * spreads retries out far better than pure exponential and avoids a thundering
+ * herd when many sources share the file.
+ *
+ * Design constraints (CLAUDE.md): ESM, Node built-ins only, everything
+ * injectable so tests are hermetic — `deps` may override the clock (`now`),
+ * the RNG (`rng`), and the state directory (`stateDir`).
+ *
+ * Invariant: this module NEVER throws on I/O failure. A breaker that can't
+ * read its file fails OPEN-FOR-WORK (allowed:true) — we'd rather risk one
+ * extra spawn than block all work because a state file is briefly unreadable.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Tunables (env-overridable for ops; tests inject via deps instead)
+// ---------------------------------------------------------------------------
+
+const ONE_SECOND = 1000;
+const FIFTEEN_MINUTES = 15 * 60 * 1000;
+
+/** Floor of every backoff window. */
+export const RATE_BASE_BACKOFF_MS = num(process.env.RATE_BASE_BACKOFF_MS, ONE_SECOND);
+/** Hard ceiling on any single backoff window. */
+export const RATE_MAX_BACKOFF_MS = num(process.env.RATE_MAX_BACKOFF_MS, FIFTEEN_MINUTES);
+/** Multiplier applied to the previous backoff to size the next jitter range. */
+export const RATE_BACKOFF_FACTOR = num(process.env.RATE_BACKOFF_FACTOR, 3);
+
+function num(v, dflt) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+function resolveStateDir(deps) {
+  if (deps && deps.stateDir) return resolve(deps.stateDir);
+  const root =
+    (deps && deps.agentRoot) ||
+    process.env.AGENT_ROOT ||
+    process.env.AGENT_DIR ||
+    process.cwd();
+  return join(resolve(root), "state", "rate-limits");
+}
+
+function providerPath(provider, deps) {
+  const safe = sanitizeProvider(provider);
+  return join(resolveStateDir(deps), `${safe}.json`);
+}
+
+/** Keep provider keys filesystem-safe + collision-resistant. */
+export function sanitizeProvider(provider) {
+  const p = String(provider || "anthropic").trim().toLowerCase();
+  const cleaned = p.replace(/[^a-z0-9._-]/g, "-");
+  return cleaned || "anthropic";
+}
+
+// ---------------------------------------------------------------------------
+// Injected primitives
+// ---------------------------------------------------------------------------
+
+function clock(deps) {
+  return deps && typeof deps.now === "function" ? deps.now : Date.now;
+}
+
+/** Default RNG → uniform float in [0, 1). Injectable for deterministic tests. */
+function rng(deps) {
+  if (deps && typeof deps.rng === "function") return deps.rng;
+  return () => {
+    // crypto-grade uniform in [0,1) without pulling Math.random (deterministic
+    // tests always inject their own rng anyway).
+    const buf = randomBytes(6); // 48 bits of entropy
+    let n = 0;
+    for (const b of buf) n = n * 256 + b;
+    return n / 2 ** 48;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// State read/write
+// ---------------------------------------------------------------------------
+
+const EMPTY_STATE = { openUntil: 0, consecutive429: 0, lastBackoffMs: 0 };
+
+/**
+ * Read a provider's breaker state. Returns a normalized object; missing or
+ * corrupt files yield the empty (closed) state. Never throws.
+ */
+export function readState(provider, deps) {
+  const p = providerPath(provider, deps);
+  if (!existsSync(p)) return { ...EMPTY_STATE };
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"));
+    return {
+      openUntil: numOr0(raw.openUntil),
+      consecutive429: numOr0(raw.consecutive429),
+      lastBackoffMs: numOr0(raw.lastBackoffMs),
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : undefined,
+    };
+  } catch {
+    return { ...EMPTY_STATE };
+  }
+}
+
+function numOr0(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Atomically persist breaker state. Best-effort; never throws. */
+function writeState(provider, state, deps) {
+  const p = providerPath(provider, deps);
+  try {
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${Date.now()}.${randomBytes(2).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify({ ...state, updatedAt: new Date(clock(deps)()).toISOString() }, null, 2) + "\n");
+    try {
+      renameSync(tmp, p);
+    } catch (err) {
+      try { unlinkSync(tmp); } catch { /* */ }
+      throw err;
+    }
+  } catch {
+    /* best-effort: a breaker we can't persist degrades to in-memory only */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Is the breaker for `provider` currently allowing spawns?
+ *
+ * @param {string} provider
+ * @param {object} [deps]  { now?, rng?, stateDir?, agentRoot? }
+ * @returns {{ allowed: boolean, retryAt: number|null, openUntil: number }}
+ *   allowed:false → a spawn must be deferred/requeued until retryAt (epoch ms).
+ */
+export function checkRateLimit(provider, deps) {
+  const now = clock(deps)();
+  const state = readState(provider, deps);
+  if (state.openUntil > now) {
+    return { allowed: false, retryAt: state.openUntil, openUntil: state.openUntil };
+  }
+  return { allowed: true, retryAt: null, openUntil: 0 };
+}
+
+/**
+ * Record a rate-limit hit for `provider`: bump the consecutive counter and
+ * open the breaker for a fresh decorrelated-jitter backoff window.
+ *
+ * @returns {{ openUntil:number, backoffMs:number, consecutive429:number }}
+ */
+export function recordRateLimit(provider, deps) {
+  const now = clock(deps)();
+  const prev = readState(provider, deps);
+  const backoffMs = decorrelatedBackoff(prev.lastBackoffMs, deps);
+  const next = {
+    openUntil: now + backoffMs,
+    consecutive429: prev.consecutive429 + 1,
+    lastBackoffMs: backoffMs,
+  };
+  writeState(provider, next, deps);
+  return { openUntil: next.openUntil, backoffMs, consecutive429: next.consecutive429 };
+}
+
+/**
+ * Record a clean success — closes the breaker and resets backoff so the next
+ * incident starts from the base window again.
+ */
+export function recordSuccess(provider, deps) {
+  // Only rewrite if there is something to clear (avoids churning the file on
+  // every successful spawn).
+  const prev = readState(provider, deps);
+  if (prev.openUntil === 0 && prev.consecutive429 === 0 && prev.lastBackoffMs === 0) {
+    return { ...EMPTY_STATE };
+  }
+  const cleared = { ...EMPTY_STATE };
+  writeState(provider, cleared, deps);
+  return cleared;
+}
+
+/**
+ * Decorrelated-jitter backoff: uniform random in
+ *   [RATE_BASE_BACKOFF_MS, prevBackoff * RATE_BACKOFF_FACTOR], capped at
+ *   RATE_MAX_BACKOFF_MS. With prev=0 the range is [base, base].
+ *
+ * Exported so tests can assert the bounds with an injected rng.
+ */
+export function decorrelatedBackoff(prevBackoffMs, deps) {
+  const base = RATE_BASE_BACKOFF_MS;
+  const prev = numOr0(prevBackoffMs);
+  const hi = Math.max(base, prev * RATE_BACKOFF_FACTOR);
+  const r = rng(deps)();
+  const clampedR = r < 0 ? 0 : r >= 1 ? 0.999999 : r;
+  const span = hi - base;
+  const pick = base + clampedR * span;
+  return Math.min(RATE_MAX_BACKOFF_MS, Math.round(pick));
+}
+
+/**
+ * Does this stderr/text look like a provider rate-limit / overload signal?
+ * Matched case-insensitively against the spawn's captured stderr by every
+ * source, so one breaker covers them all.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function classifyStderr(text) {
+  if (!text || typeof text !== "string") return false;
+  return /\b429\b|rate[\s_-]?limit|overloaded|too many requests/i.test(text);
+}
+
+export const _internals = { RATE_BASE_BACKOFF_MS, RATE_MAX_BACKOFF_MS, RATE_BACKOFF_FACTOR };

package/lib/rate-guard.test.mjs

@@ -0,0 +1,201 @@
+/**
+ * rate-guard.test.mjs — node:test coverage for the shared 429 breaker.
+ *
+ * Everything is hermetic: the state dir is an isolated tmpdir per test, and
+ * the clock + rng are injected so backoff windows are deterministic.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  checkRateLimit,
+  recordRateLimit,
+  recordSuccess,
+  decorrelatedBackoff,
+  classifyStderr,
+  readState,
+  sanitizeProvider,
+  RATE_BASE_BACKOFF_MS,
+  RATE_MAX_BACKOFF_MS,
+  RATE_BACKOFF_FACTOR,
+} from "./rate-guard.mjs";
+
+async function makeStateDir() {
+  const path = join(tmpdir(), `rate-guard-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+async function rm(path) { try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ } }
+
+// Fixed-clock helper.
+function fixedClock(t) { return () => t; }
+
+// ---------------------------------------------------------------------------
+// classifyStderr
+// ---------------------------------------------------------------------------
+
+test("classifyStderr matches 429 / rate limit / overloaded variants", () => {
+  assert.equal(classifyStderr("HTTP 429 Too Many Requests"), true);
+  assert.equal(classifyStderr("Error: rate limit exceeded"), true);
+  assert.equal(classifyStderr("rate-limit hit"), true);
+  assert.equal(classifyStderr("the model is Overloaded right now"), true);
+  assert.equal(classifyStderr("too many requests, slow down"), true);
+  // Negatives
+  assert.equal(classifyStderr("connection refused"), false);
+  assert.equal(classifyStderr("permission denied"), false);
+  assert.equal(classifyStderr(""), false);
+  assert.equal(classifyStderr(null), false);
+  // 429 must be a word boundary, not part of a longer number
+  assert.equal(classifyStderr("error code 14290 unrelated"), false);
+});
+
+// ---------------------------------------------------------------------------
+// breaker open/close
+// ---------------------------------------------------------------------------
+
+test("breaker starts closed (allows) when no state file exists", async () => {
+  const dir = await makeStateDir();
+  try {
+    const r = checkRateLimit("anthropic", { stateDir: dir });
+    assert.equal(r.allowed, true);
+    assert.equal(r.retryAt, null);
+  } finally { await rm(dir); }
+});
+
+test("recordRateLimit opens the breaker so the next check is gated", async () => {
+  const dir = await makeStateDir();
+  try {
+    const t0 = 1_000_000;
+    // Deterministic rng → pick the high end of the range.
+    const rec = recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.999999 });
+    assert.ok(rec.backoffMs >= RATE_BASE_BACKOFF_MS);
+    assert.equal(rec.openUntil, t0 + rec.backoffMs);
+    assert.equal(rec.consecutive429, 1);
+
+    // A check WHILE the window is open is gated.
+    const mid = checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 10) });
+    assert.equal(mid.allowed, false);
+    assert.equal(mid.retryAt, rec.openUntil);
+
+    // A check AFTER the window closes is allowed again.
+    const after = checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(rec.openUntil + 1) });
+    assert.equal(after.allowed, true);
+  } finally { await rm(dir); }
+});
+
+test("recordSuccess closes the breaker and resets backoff", async () => {
+  const dir = await makeStateDir();
+  try {
+    const t0 = 5_000_000;
+    recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.5 });
+    // While open, gated.
+    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 5) }).allowed, false);
+    // Success clears it.
+    recordSuccess("anthropic", { stateDir: dir, now: fixedClock(t0 + 6) });
+    const s = readState("anthropic", { stateDir: dir });
+    assert.equal(s.openUntil, 0);
+    assert.equal(s.consecutive429, 0);
+    assert.equal(s.lastBackoffMs, 0);
+    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 7) }).allowed, true);
+  } finally { await rm(dir); }
+});
+
+// ---------------------------------------------------------------------------
+// decorrelated backoff bounds
+// ---------------------------------------------------------------------------
+
+test("decorrelatedBackoff stays within [base, prev*factor] and respects rng extremes", () => {
+  // First hit (prev=0): range collapses to [base, base].
+  assert.equal(decorrelatedBackoff(0, { rng: () => 0 }), RATE_BASE_BACKOFF_MS);
+  assert.equal(decorrelatedBackoff(0, { rng: () => 0.999999 }), RATE_BASE_BACKOFF_MS);
+
+  // Subsequent hit: prev=10s, factor default 3 → range [base, 30s].
+  const prev = 10_000;
+  const lo = decorrelatedBackoff(prev, { rng: () => 0 });
+  const hi = decorrelatedBackoff(prev, { rng: () => 0.999999 });
+  assert.equal(lo, RATE_BASE_BACKOFF_MS);
+  assert.ok(hi <= prev * RATE_BACKOFF_FACTOR);
+  assert.ok(hi >= lo);
+  // A mid pick lands strictly inside the range.
+  const mid = decorrelatedBackoff(prev, { rng: () => 0.5 });
+  assert.ok(mid > lo && mid < hi, `mid ${mid} should be inside (${lo}, ${hi})`);
+});
+
+test("decorrelatedBackoff caps at RATE_MAX_BACKOFF_MS", () => {
+  // Huge prev would blow past 15min; the cap clamps it.
+  const capped = decorrelatedBackoff(RATE_MAX_BACKOFF_MS * 100, { rng: () => 0.999999 });
+  assert.equal(capped, RATE_MAX_BACKOFF_MS);
+});
+
+test("consecutive hits grow the backoff window (decorrelated escalation)", async () => {
+  const dir = await makeStateDir();
+  try {
+    let t = 0;
+    // Always pick the top of the range so growth is monotonic and assertable.
+    const deps = { stateDir: dir, now: () => t, rng: () => 0.999999 };
+    const w1 = recordRateLimit("anthropic", deps).backoffMs;
+    t += w1 + 1;
+    const w2 = recordRateLimit("anthropic", deps).backoffMs;
+    t += w2 + 1;
+    const w3 = recordRateLimit("anthropic", deps).backoffMs;
+    assert.ok(w2 >= w1, `w2 ${w2} should be >= w1 ${w1}`);
+    assert.ok(w3 >= w2, `w3 ${w3} should be >= w2 ${w2}`);
+    assert.equal(readState("anthropic", { stateDir: dir }).consecutive429, 3);
+  } finally { await rm(dir); }
+});
+
+// ---------------------------------------------------------------------------
+// shared file — one breaker for all sources
+// ---------------------------------------------------------------------------
+
+test("the breaker is a single shared file: one source opens it, another sees it", async () => {
+  const dir = await makeStateDir();
+  try {
+    const t0 = 9_000_000;
+    // "dispatcher" records the hit…
+    const rec = recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.7 });
+    // …and the "cadence-consumer" (separate caller, same provider+dir) is gated.
+    const consumerView = checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 1) });
+    assert.equal(consumerView.allowed, false);
+    assert.equal(consumerView.retryAt, rec.openUntil);
+    // The file physically exists on disk under the shared dir.
+    assert.ok(existsSync(join(dir, "anthropic.json")));
+    const persisted = JSON.parse(readFileSync(join(dir, "anthropic.json"), "utf-8"));
+    assert.equal(persisted.openUntil, rec.openUntil);
+  } finally { await rm(dir); }
+});
+
+test("different providers have independent breakers", async () => {
+  const dir = await makeStateDir();
+  try {
+    const t0 = 2_000_000;
+    recordRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0), rng: () => 0.9 });
+    // moonshot is untouched → still allowed.
+    assert.equal(checkRateLimit("moonshot", { stateDir: dir, now: fixedClock(t0 + 1) }).allowed, true);
+    // anthropic is gated.
+    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: fixedClock(t0 + 1) }).allowed, false);
+  } finally { await rm(dir); }
+});
+
+test("sanitizeProvider keeps keys filesystem-safe", () => {
+  assert.equal(sanitizeProvider("Anthropic"), "anthropic");
+  assert.equal(sanitizeProvider("open/router"), "open-router");
+  assert.equal(sanitizeProvider(""), "anthropic");
+  assert.equal(sanitizeProvider(undefined), "anthropic");
+});
+
+test("readState tolerates a corrupt file (fails closed-to-empty, never throws)", async () => {
+  const dir = await makeStateDir();
+  try {
+    await fsp.writeFile(join(dir, "anthropic.json"), "{ not json");
+    const s = readState("anthropic", { stateDir: dir });
+    assert.deepEqual(s, { openUntil: 0, consecutive429: 0, lastBackoffMs: 0 });
+    // And a check on corrupt state allows work (fail-open-for-work).
+    assert.equal(checkRateLimit("anthropic", { stateDir: dir }).allowed, true);
+  } finally { await rm(dir); }
+});

package/lib/render.mjs

@@ -0,0 +1,112 @@
+/**
+ * render.mjs — the {{agent.*}} template substitution engine.
+ *
+ * Framework-shipped operational prompts (triggers, agent definitions, skills,
+ * templates, daemon preambles) stay GENERIC in the repo and carry Mustache-style
+ * identity tokens. They are rendered to the running agent's identity at LOAD time
+ * — at every point a prompt body is read before being handed to a model. This is
+ * how `npm update @cohortapp/agent-sdk` keeps shipping one set of files that render
+ * to any agent, and how the identity-leak class is closed structurally: framework
+ * files never contain a real name; only generated artifacts (CLAUDE.md, charter)
+ * are baked at init.
+ *
+ * Tokens resolve dot-paths against a context of { agent, archetype }:
+ *   {{agent.fullName}}  {{agent.title}}  {{agent.principal.fullName}}
+ *   {{agent.company}}   {{archetype.label}}  {{archetype.domain}}
+ *
+ * Design contract:
+ *   - No-op on token-free text (fast path) — so wiring this in is behaviour-
+ *     preserving for any prompt that has no tokens yet (backward-safe for the
+ *     deployed fleet until it receives tokenised files).
+ *   - Unknown/unresolved tokens are LEFT VERBATIM (never silently emptied) so the
+ *     doctor/CI guard ({@link unknownTokens}) catches typos and stray braces
+ *     before they reach a model.
+ *
+ * @module render
+ */
+
+"use strict";
+
+/**
+ * The token vocabulary framework templates may use. A `{{token}}` outside this
+ * set is a typo or stray braces and is flagged by the doctor/CI guard.
+ * Mirrors the config/agent.json schema (agent.*) plus resolved-profile fields
+ * (archetype.*). Extend deliberately when the config/profile shape grows.
+ * @type {Set<string>}
+ */
+export const KNOWN_TOKENS = new Set([
+  "agent.firstName", "agent.lastName", "agent.fullName", "agent.title",
+  "agent.email", "agent.phone", "agent.slackMemberId",
+  "agent.company", "agent.companyDomain", "agent.companyDescription",
+  "agent.timezone", "agent.locale", "agent.repoSlug", "agent.machineName",
+  "agent.function", "agent.altitude", "agent.archetype",
+  "agent.principal.firstName", "agent.principal.lastName", "agent.principal.fullName",
+  "agent.principal.title", "agent.principal.email", "agent.principal.slackMemberId",
+  "archetype.label", "archetype.domain", "archetype.posture",
+  "archetype.function", "archetype.altitude",
+  "company.name", "company.legalName", "company.website", "company.domain",
+  "company.tagline", "company.description", "company.industry", "company.stage", "company.headcount",
+]);
+
+/** Matches `{{ dotted.path }}` (whitespace-tolerant). Build fresh per call. */
+function tokenRe() {
+  return /\{\{\s*([\w.]+)\s*\}\}/g;
+}
+
+/** Walk a dotted path into a context object; undefined if any segment is missing. */
+function lookup(ctx, dotted) {
+  let cur = ctx;
+  for (const part of dotted.split(".")) {
+    if (cur == null || typeof cur !== "object") return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+/**
+ * Build a render context from an agent config (config/agent.json), an optional
+ * resolved archetype profile, and an optional company config (config/company.json).
+ *
+ * @param {object} agentConfig @param {object} [profile] @param {object} [companyConfig]
+ * @returns {{ agent: object, archetype: object, company: object }}
+ */
+export function buildContext(agentConfig, profile, companyConfig) {
+  return { agent: agentConfig || {}, archetype: profile || {}, company: companyConfig || {} };
+}
+
+/**
+ * Render `{{token}}`s in `body` against `context`. No-op on token-free text.
+ * Unresolved tokens are left verbatim.
+ *
+ * @param {string} body @param {{agent?:object, archetype?:object}} context
+ * @returns {string}
+ */
+export function renderTemplate(body, context) {
+  if (typeof body !== "string" || body.indexOf("{{") === -1) return body;
+  const ctx = context || {};
+  return body.replace(tokenRe(), (m, dotted) => {
+    const v = lookup(ctx, dotted);
+    return v === undefined || v === null ? m : String(v);
+  });
+}
+
+/**
+ * All token paths present in `body` (in order, with duplicates).
+ * @param {string} body @returns {string[]}
+ */
+export function collectTokens(body) {
+  if (typeof body !== "string") return [];
+  const re = tokenRe();
+  const out = [];
+  let m;
+  while ((m = re.exec(body)) !== null) out.push(m[1]);
+  return out;
+}
+
+/**
+ * Distinct token paths in `body` that are NOT in {@link KNOWN_TOKENS}.
+ * @param {string} body @returns {string[]}
+ */
+export function unknownTokens(body) {
+  return [...new Set(collectTokens(body))].filter((t) => !KNOWN_TOKENS.has(t));
+}

package/lib/render.test.mjs

@@ -0,0 +1,68 @@
+/**
+ * render.test.mjs — tests for the {{agent.*}} template substitution engine.
+ * Run: `node --test lib/render.test.mjs`
+ * @module render.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  renderTemplate,
+  buildContext,
+  collectTokens,
+  unknownTokens,
+  KNOWN_TOKENS,
+} from "./render.mjs";
+
+const AGENT = {
+  firstName: "Jacob", fullName: "Jacob Chen", title: "VP, Engineering",
+  email: "jacob@acme.com", phone: "", company: "Acme",
+  principal: { firstName: "Dana", fullName: "Dana Reyes", title: "CEO", email: "dana@acme.com" },
+};
+const PROFILE = { label: "VP, Engineering", domain: "Engineering delivery" };
+const COMPANY = { name: "Acme Capital", website: "https://acme.com", industry: "Asset management", domain: "acme.com" };
+const CTX = buildContext(AGENT, PROFILE, COMPANY);
+
+test("renderTemplate resolves agent.*, archetype.*, and company.* dot-paths", () => {
+  assert.equal(renderTemplate("Hi, I'm {{agent.fullName}}, {{agent.title}}.", CTX), "Hi, I'm Jacob Chen, VP, Engineering.");
+  assert.equal(renderTemplate("Reports to {{agent.principal.fullName}} ({{agent.principal.title}}).", CTX), "Reports to Dana Reyes (CEO).");
+  assert.equal(renderTemplate("Domain: {{archetype.domain}}", CTX), "Domain: Engineering delivery");
+  assert.equal(renderTemplate("At {{company.name}} ({{company.industry}}) — {{company.website}}", CTX), "At Acme Capital (Asset management) — https://acme.com");
+});
+
+test("renderTemplate is a no-op on token-free text (fast path)", () => {
+  const s = "No tokens here at all.";
+  assert.equal(renderTemplate(s, CTX), s);
+  assert.equal(renderTemplate("", CTX), "");
+  assert.equal(renderTemplate(undefined, CTX), undefined);
+});
+
+test("renderTemplate leaves unresolved / unknown tokens verbatim (never silently empties)", () => {
+  assert.equal(renderTemplate("x {{agent.nope}} y", CTX), "x {{agent.nope}} y");
+  assert.equal(renderTemplate("x {{totally.bogus}} y", CTX), "x {{totally.bogus}} y");
+  // present-but-empty value (phone="") resolves to empty string, not left verbatim:
+  assert.equal(renderTemplate("p[{{agent.phone}}]", CTX), "p[]");
+});
+
+test("renderTemplate tolerates whitespace inside braces", () => {
+  assert.equal(renderTemplate("{{ agent.firstName }}", CTX), "Jacob");
+});
+
+test("collectTokens returns all token paths in order", () => {
+  assert.deepEqual(collectTokens("{{agent.fullName}} <{{agent.email}}>"), ["agent.fullName", "agent.email"]);
+  assert.deepEqual(collectTokens("none"), []);
+});
+
+test("unknownTokens flags only tokens outside the vocabulary", () => {
+  assert.deepEqual(unknownTokens("{{agent.fullName}} {{agent.principal.email}}"), []);
+  assert.deepEqual(unknownTokens("{{agent.firstname}} {{stray}}").sort(), ["agent.firstname", "stray"]);
+});
+
+test("KNOWN_TOKENS covers the documented identity vocabulary", () => {
+  for (const t of ["agent.firstName", "agent.fullName", "agent.title", "agent.email", "agent.company", "agent.principal.fullName", "archetype.label"]) {
+    assert.ok(KNOWN_TOKENS.has(t), `expected ${t} in KNOWN_TOKENS`);
+  }
+});