@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/mandate/cache.mjs

@@ -0,0 +1,162 @@
+/**
+ * lib/mandate/cache.mjs — the local mandate cache + the staleness ladder.
+ *
+ * hq owns the MANDATE (what outcomes exist, who owns them, what the target is);
+ * the agent owns the PLAN. The plan is compiled locally from a CACHED mandate, so
+ * a partitioned agent keeps working from cache on a defined ramp instead of going
+ * dark. This module is that cache and that ramp (SPEC §2.3 / §6.4).
+ *
+ *   state/mandate/cache.json  →  { version, checksum, body, fetchedAt, source }
+ *
+ * `source` is load-bearing and is NOT cosmetic:
+ *   "server"  — fetched from hq via mandate.get (adopted, authoritative)
+ *   "local"   — derived locally from charter/strategy/archetype, every objective
+ *               state:'proposed'. Proposed objectives compile NO obligations and
+ *               admit NO backlog; the agent runs exactly today's archetype
+ *               cadences until a human adopts in hq.
+ *
+ * Staleness tiers (SPEC §6.4) — degradation is a ramp, not a cliff:
+ *   fresh    (<24h)  full REACT / full SCHEDULE / full OUTCOME
+ *   aging    (24-72h) full / full / OUTCOME suspended
+ *   stale    (>72h)  offline_safe REACT only / inline+guarded SCHEDULE / suspended
+ *   expired  (>7d)   nothing but one drift record per day
+ *
+ * Pure + injectable: the clock arrives as a parameter, never `Date.now()` inside
+ * a decision function, so the ladder is testable and deterministic.
+ *
+ * @module lib/mandate/cache
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+
+/** Relative path of the cache (git-ignored runtime state). */
+export const CACHE_REL = join("state", "mandate", "cache.json");
+
+/** Staleness tier boundaries, in seconds. */
+export const TIERS = Object.freeze({ fresh: 24 * 3600, aging: 72 * 3600, stale: 7 * 24 * 3600 });
+
+/** Absolute cache path for an agent root. */
+export function cachePath(agentRoot) {
+  return join(agentRoot, CACHE_REL);
+}
+
+/** Canonical JSON (stable key order) — the checksum + hash substrate. */
+export function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value === undefined ? null : value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+}
+
+/** sha256 of the canonicalised value. */
+export function checksumOf(value) {
+  return createHash("sha256").update(canonical(value)).digest("hex");
+}
+
+/**
+ * Write the cache atomically.
+ * @param {string} agentRoot
+ * @param {{version?:number, body:object, source?:string, fetchedAt?:string}} snapshot
+ * @param {object} [deps] - { writeFileSync, mkdirSync, renameSync, now }
+ * @returns {object} the persisted record
+ */
+export function writeCache(agentRoot, snapshot = {}, deps = {}) {
+  const wr = deps.writeFileSync || writeFileSync;
+  const mk = deps.mkdirSync || mkdirSync;
+  const mv = deps.renameSync || renameSync;
+  const now = typeof deps.now === "function" ? deps.now() : new Date().toISOString();
+  const body = snapshot.body || {};
+  const record = {
+    version: Number.isFinite(snapshot.version) ? snapshot.version : 0,
+    checksum: snapshot.checksum || checksumOf(body),
+    source: snapshot.source || "local",
+    fetchedAt: snapshot.fetchedAt || now,
+    body,
+  };
+  const p = cachePath(agentRoot);
+  mk(join(agentRoot, "state", "mandate"), { recursive: true });
+  const tmp = `${p}.${process.pid}.tmp`;
+  wr(tmp, JSON.stringify(record, null, 2) + "\n", "utf-8");
+  mv(tmp, p);
+  return record;
+}
+
+/**
+ * Read the cache. Returns null when absent; a PARSE FAILURE is returned as a
+ * degraded record (never silently null) so callers can log the difference
+ * between "never fetched" and "corrupt on disk".
+ * @returns {object|null}
+ */
+export function readCache(agentRoot, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const rd = deps.readFileSync || readFileSync;
+  const p = cachePath(agentRoot);
+  if (!ex(p)) return null;
+  try {
+    const doc = JSON.parse(rd(p, "utf-8"));
+    return doc && typeof doc === "object" ? doc : { corrupt: true, reason: "cache is not an object", body: {} };
+  } catch (e) {
+    return { corrupt: true, reason: e && e.message ? e.message : String(e), body: {} };
+  }
+}
+
+/**
+ * Seconds since the cache was fetched. `Infinity` when never fetched.
+ * @param {object|null} record @param {number|string|Date} nowMs
+ */
+export function staleSeconds(record, nowMs = Date.now()) {
+  if (!record || !record.fetchedAt) return Infinity;
+  const then = Date.parse(record.fetchedAt);
+  const now = typeof nowMs === "number" ? nowMs : Date.parse(String(nowMs));
+  if (!Number.isFinite(then) || !Number.isFinite(now)) return Infinity;
+  return Math.max(0, (now - then) / 1000);
+}
+
+/**
+ * The staleness tier for a cache record.
+ * @returns {"fresh"|"aging"|"stale"|"expired"}
+ */
+export function stalenessTier(record, nowMs = Date.now()) {
+  const s = staleSeconds(record, nowMs);
+  if (s < TIERS.fresh) return "fresh";
+  if (s < TIERS.aging) return "aging";
+  if (s < TIERS.stale) return "stale";
+  return "expired";
+}
+
+/**
+ * What a given tier permits. The loops consult this rather than re-deriving the
+ * ramp; that is why the ladder can only be wrong in one place.
+ * @param {string} tier
+ * @returns {{react:"full"|"offline_safe"|"none", schedule:"full"|"guarded"|"none", outcome:"full"|"suspended"}}
+ */
+export function permissionsForTier(tier) {
+  switch (tier) {
+    case "fresh": return { react: "full", schedule: "full", outcome: "full" };
+    case "aging": return { react: "full", schedule: "full", outcome: "suspended" };
+    case "stale": return { react: "offline_safe", schedule: "guarded", outcome: "suspended" };
+    default: return { react: "none", schedule: "none", outcome: "suspended" };
+  }
+}
+
+/** Are the adopted objectives in this cache usable to compile obligations? */
+export function adoptedObjectives(record) {
+  const body = (record && record.body) || {};
+  const list = Array.isArray(body.objectives) ? body.objectives : [];
+  return list.filter((o) => o && o.state === "active");
+}
+
+/** Every objective in the cache, adopted or not (the proposal surface). */
+export function allObjectives(record) {
+  const body = (record && record.body) || {};
+  return Array.isArray(body.objectives) ? body.objectives : [];
+}
+
+export default {
+  CACHE_REL, TIERS, cachePath, canonical, checksumOf, writeCache, readCache,
+  staleSeconds, stalenessTier, permissionsForTier, adoptedObjectives, allObjectives,
+};

package/lib/mandate/derive.mjs

@@ -0,0 +1,317 @@
+/**
+ * lib/mandate/derive.mjs — derive a PROPOSED objective tree for this seat.
+ *
+ * This is the "what is this agent actually for" step of init (SPEC §5.5). It is
+ * deterministic and offline: prose → structured mandate happens ONCE, here, from
+ * artefacts the agent already has, in the SPEC's precedence order:
+ *
+ *   1. hq `charter.sections` PILLAR / CAPABILITY entries   (config/agent.json)
+ *   2. `org-context.json` strategy streams                 (the org's own plan)
+ *   3. `profile.kpiCategories` from the archetype          (the role's KPI tree)
+ *   4. `config/priorities.yaml`                            (the seat's own list)
+ *
+ * Every node comes out `state:'proposed'`. **Nothing is adopted here** — an agent
+ * may propose an objective but a human/manager adopts it in hq, and
+ * `mandate.adopt` refuses when the actor is the objective's owner. That is the
+ * anti-Goodhart law: a seat cannot define, measure and be graded on the same
+ * number. Proposed objectives compile no obligations, so until adoption the
+ * agent runs exactly today's archetype cadences.
+ *
+ * SENSORS are chosen from the capability manifest, never invented: a metric is
+ * bound to a `reachable:true` capability or it is proposed with
+ * `sensor.source:"human"` and flagged. An objective with an unreachable sensor
+ * is a measurement debt the operator can see, not a silent no-op.
+ *
+ * PURE: no fs, no network, no clock, no randomness. Same inputs → same tree.
+ *
+ * @module lib/mandate/derive
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+
+/** Objective kinds (mirrors hq's ObjectiveKind enum). */
+export const OBJECTIVE_KINDS = Object.freeze(["PILLAR", "OBJECTIVE", "GOAL"]);
+/** Metric directions (mirrors hq's MetricDirection enum). */
+export const DIRECTIONS = Object.freeze(["up", "down", "hold", "band"]);
+/** Review/measure rhythms we know how to schedule. */
+export const CADENCES = Object.freeze(["weekly", "monthly", "quarterly"]);
+
+/**
+ * Metric-keyword → candidate sensor capabilities, most specific first. The
+ * derivation walks this table and takes the FIRST capability that is reachable
+ * in the manifest; nothing else picks sensors, so the mapping is auditable in
+ * one place.
+ * @type {Array<{re:RegExp, caps:string[], params?:object, direction?:string, unit?:string}>}
+ */
+export const SENSOR_HINTS = Object.freeze([
+  { re: /(pipeline|deal|bookings|revenue|win rate|arr|mrr)/i, caps: ["crm_list_deals", "crm_next_best_action"], params: { stage: "open" }, unit: "x", direction: "up" },
+  { re: /(runway|burn|cash|invoice|billing|tax|spend|cost)/i, caps: ["books_reports", "books_invoices"], unit: "months", direction: "up" },
+  { re: /(commitment|action item|follow-?through|closure|backlog|task|execution)/i, caps: ["board_ready", "task_update"], unit: "%", direction: "up" },
+  { re: /(decision|governance|approval)/i, caps: ["decision_list", "approval_wait"], unit: "days", direction: "down" },
+  { re: /(meeting|calendar|cadence|agenda)/i, caps: ["calendar_list", "meetings_recap_file"], unit: "%", direction: "up" },
+  { re: /(inbox|email|response|reply|correspondence)/i, caps: ["email_inbox", "email_triage"], unit: "hours", direction: "down" },
+  { re: /(message|channel|comms|alignment|broadcast)/i, caps: ["messaging_history", "messaging_channels"], unit: "%", direction: "up" },
+  { re: /(escalation|blocker|risk|incident)/i, caps: ["crm_list_escalations", "escalation_raise"], unit: "count", direction: "down" },
+  { re: /(directory|contact|crm hygiene|record)/i, caps: ["directory_list_captures", "directory_search"], unit: "%", direction: "up" },
+  { re: /(knowledge|memory|documentation|institutional)/i, caps: ["knowledge_search", "files_list"], unit: "%", direction: "up" },
+  { re: /(brand|design|template|asset)/i, caps: ["design_list_templates", "design_foundation"], unit: "%", direction: "up" },
+]);
+
+/** Default review rhythm per objective kind. */
+const DEFAULT_CADENCE = { PILLAR: "quarterly", OBJECTIVE: "weekly", GOAL: "monthly" };
+
+/** Deterministic, stable, url-safe slug. Collisions are disambiguated by caller. */
+export function slug(text, max = 48) {
+  const s = String(text || "")
+    .toLowerCase()
+    .replace(/^\s*\d+[).:\-]\s*/, "")       // strip "1) " / "3. " list prefixes
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, max)
+    .replace(/-+$/g, "");
+  return s || `k-${createHash("sha256").update(String(text || "")).digest("hex").slice(0, 8)}`;
+}
+
+/** First sentence / clause of a body, for a short objective title. */
+export function firstClause(body, max = 120) {
+  const t = String(body || "").replace(/\s+/g, " ").trim().replace(/^\d+[).:\-]\s*/, "");
+  const cut = t.split(/(?<=[.;—])\s/)[0] || t;
+  return cut.length > max ? `${cut.slice(0, max - 1).trimEnd()}…` : cut;
+}
+
+/**
+ * Pick a sensor for a metric from the capability manifest.
+ * @param {string} text  the objective/metric text to classify
+ * @param {Set<string>} reachable  reachable capability ids
+ * @returns {{capability:string|null, params?:object, source:"method"|"human", unit?:string, direction?:string, considered:string[]}}
+ */
+export function pickSensor(text, reachable = new Set()) {
+  for (const hint of SENSOR_HINTS) {
+    if (!hint.re.test(String(text || ""))) continue;
+    const cap = hint.caps.find((c) => reachable.has(c));
+    if (cap) {
+      const s = { capability: cap, source: "method", considered: hint.caps.slice() };
+      if (hint.params) s.params = hint.params;
+      if (hint.unit) s.unit = hint.unit;
+      if (hint.direction) s.direction = hint.direction;
+      return s;
+    }
+    // Matched a family but nothing in it is reachable — that is a measurement
+    // debt, and it must be visible rather than silently downgraded.
+    return { capability: null, source: "human", considered: hint.caps.slice(), unit: hint.unit, direction: hint.direction };
+  }
+  return { capability: null, source: "human", considered: [] };
+}
+
+/**
+ * Derive the proposed objective tree.
+ *
+ * @param {object} input
+ * @param {Array<{kind:string, order?:number, title?:string, body:string, id?:string}>} [input.charterSections]
+ * @param {object} [input.strategy]        org-context.json `strategy`
+ * @param {Array<{id:string,name:string,examples?:string[]}>} [input.kpiCategories]  archetype profile
+ * @param {Array<{id?:string,title?:string,text?:string}>} [input.priorities]        config/priorities.yaml
+ * @param {object} [input.manifest]        capability manifest (for sensor binding)
+ * @param {string} [input.memberId]
+ * @param {object} [input.overrides]       key → { target, tolerance, cadence, unit, direction, metric }
+ * @returns {{objectives:object[], degradations:object[], counts:object}}
+ */
+export function deriveMandate(input = {}) {
+  const charterSections = Array.isArray(input.charterSections) ? input.charterSections : [];
+  const kpiCategories = Array.isArray(input.kpiCategories) ? input.kpiCategories : [];
+  const priorities = Array.isArray(input.priorities) ? input.priorities : [];
+  const strategy = input.strategy && typeof input.strategy === "object" ? input.strategy : null;
+  const overrides = input.overrides && typeof input.overrides === "object" ? input.overrides : {};
+  const reachable = reachableSet(input.manifest);
+
+  const objectives = [];
+  const degradations = [];
+  const used = new Set();
+
+  /** Reserve a unique key. */
+  const key = (base) => {
+    let k = slug(base);
+    let n = 2;
+    while (used.has(k)) k = `${slug(base)}-${n++}`;
+    used.add(k);
+    return k;
+  };
+
+  // ── 1. PILLARs from the charter ─────────────────────────────────────────
+  const pillars = charterSections
+    .filter((s) => s && (String(s.kind).toUpperCase() === "PILLAR" || String(s.kind).toUpperCase() === "CAPABILITY"))
+    .slice()
+    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+
+  for (const s of pillars) {
+    const text = firstClause(s.title || s.body);
+    const k = key(text);
+    objectives.push({
+      key: k,
+      kind: "PILLAR",
+      text,
+      parentKey: null,
+      charterSectionId: s.id || null,
+      state: "proposed",
+      direction: "up",
+      weight: 1,
+      cadence: DEFAULT_CADENCE.PILLAR,
+      sensor: null,
+      source: { origin: "charter", ref: s.id || `order:${s.order ?? 0}` },
+    });
+  }
+  if (pillars.length === 0) {
+    degradations.push({ kind: "no_charter_pillars", reason: "config/agent.json has no charter.sections of kind PILLAR/CAPABILITY — objectives will have no charter provenance" });
+  }
+
+  /** Attach an objective to the most textually-related pillar, else the first. */
+  const pillarKeys = objectives.filter((o) => o.kind === "PILLAR").map((o) => ({ key: o.key, text: o.text }));
+  const parentFor = (text) => {
+    if (!pillarKeys.length) return null;
+    const t = String(text || "").toLowerCase();
+    let best = null;
+    let bestScore = 0;
+    for (const p of pillarKeys) {
+      const score = overlapScore(t, p.text.toLowerCase());
+      if (score > bestScore) { bestScore = score; best = p.key; }
+    }
+    return bestScore > 0 ? best : pillarKeys[0].key;
+  };
+
+  // ── 2. OBJECTIVEs from the org's strategy streams ───────────────────────
+  for (const stream of strategyStreams(strategy)) {
+    const text = firstClause(stream.title || stream.name || stream.code);
+    const k = key(text);
+    const sensor = pickSensor(`${text} ${stream.detail || ""}`, reachable);
+    objectives.push(buildObjective({ k, text, parentKey: parentFor(text), sensor, cadence: "weekly", origin: "strategy", ref: stream.code || stream.id || text, overrides }));
+    if (sensor.source === "human") degradations.push({ kind: "no_reachable_sensor", key: k, reason: `no reachable capability measures "${text}" (considered: ${sensor.considered.join(", ") || "none"})` });
+  }
+
+  // ── 3. OBJECTIVEs from the archetype's KPI categories ───────────────────
+  for (const cat of kpiCategories) {
+    if (!cat || !cat.id) continue;
+    const text = cat.name || cat.id;
+    const example = Array.isArray(cat.examples) && cat.examples.length ? cat.examples[0] : "";
+    const k = key(cat.id);
+    const sensor = pickSensor(`${text} ${example}`, reachable);
+    objectives.push(buildObjective({
+      k, text, parentKey: parentFor(`${text} ${example}`), sensor, cadence: "weekly",
+      origin: "archetype", ref: `kpiCategory:${cat.id}`, metric: example ? slug(example).replace(/-/g, "_") : undefined, overrides,
+    }));
+    if (sensor.source === "human") degradations.push({ kind: "no_reachable_sensor", key: k, reason: `no reachable capability measures "${text}" (considered: ${sensor.considered.join(", ") || "none"})` });
+  }
+  if (kpiCategories.length === 0) {
+    degradations.push({ kind: "no_kpi_categories", reason: "archetype profile carried no kpiCategories — the mandate has no role-derived objectives" });
+  }
+
+  // ── 4. GOALs from the seat's own priorities ─────────────────────────────
+  for (const p of priorities) {
+    const text = firstClause(p && (p.title || p.text || p.id));
+    if (!text) continue;
+    const k = key(text);
+    const sensor = pickSensor(text, reachable);
+    const parent = parentFor(text);
+    objectives.push(buildObjective({ k, text, parentKey: parent, sensor, cadence: "monthly", origin: "priorities", ref: (p && p.id) || text, kind: "GOAL", overrides }));
+  }
+
+  const counts = {
+    pillars: objectives.filter((o) => o.kind === "PILLAR").length,
+    objectives: objectives.filter((o) => o.kind === "OBJECTIVE").length,
+    goals: objectives.filter((o) => o.kind === "GOAL").length,
+    withMethodSensor: objectives.filter((o) => o.sensor && o.sensor.source === "method").length,
+    proposed: objectives.length,
+  };
+
+  return { objectives, degradations, counts };
+}
+
+/**
+ * Wrap the derived tree in the mandate BODY shape the cache + compiler consume.
+ * @param {object} o - { memberId, objectives, budgetCentsPerPeriod?, collaborators?, reactsTo? }
+ */
+export function toMandateBody(o = {}) {
+  return {
+    memberId: o.memberId || null,
+    objectives: Array.isArray(o.objectives) ? o.objectives : [],
+    budgetCentsPerPeriod: Number.isFinite(o.budgetCentsPerPeriod) ? o.budgetCentsPerPeriod : 500,
+    collaborators: Array.isArray(o.collaborators) ? o.collaborators : [],
+    reactsTo: Array.isArray(o.reactsTo) ? o.reactsTo : [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function buildObjective({ k, text, parentKey, sensor, cadence, origin, ref, metric, kind = "OBJECTIVE", overrides = {} }) {
+  const ov = overrides[k] || {};
+  const obj = {
+    key: k,
+    kind,
+    text,
+    parentKey: parentKey || null,
+    charterSectionId: null,
+    state: "proposed",
+    metric: ov.metric || metric || `${k.replace(/-/g, "_")}`,
+    unit: ov.unit || sensor.unit || null,
+    direction: DIRECTIONS.includes(ov.direction) ? ov.direction : (sensor.direction || "up"),
+    baseline: Number.isFinite(ov.baseline) ? ov.baseline : null,
+    target: Number.isFinite(ov.target) ? ov.target : null,
+    tolerance: Number.isFinite(ov.tolerance) ? ov.tolerance : 0,
+    weight: Number.isFinite(ov.weight) ? ov.weight : 1,
+    cadence: CADENCES.includes(ov.cadence) ? ov.cadence : cadence,
+    sensor: sensor.capability
+      ? { capability: sensor.capability, params: sensor.params || {}, source: "method" }
+      : { capability: null, params: {}, source: "human", considered: sensor.considered || [] },
+    source: { origin, ref: String(ref || "") },
+  };
+  return obj;
+}
+
+/** Reachable capability ids from a manifest (empty set when none). */
+function reachableSet(manifest) {
+  const out = new Set();
+  if (!manifest) return out;
+  // Tolerate every shape the manifest legitimately arrives in. `buildInventory`
+  // returns `{entries:[…]}`, but a bare entry ARRAY is the shape the spec's
+  // state-file table describes and the shape a hand-written fixture reaches for
+  // — and `[].entries` is Array.prototype.entries, a FUNCTION, so the naive
+  // `manifest.entries || []` walk threw "function is not iterable" and took the
+  // whole derivation down with it. A Set of ids is accepted too, since that is
+  // what `pickSensor` itself takes.
+  if (manifest instanceof Set) return new Set(manifest);
+  const list = Array.isArray(manifest)
+    ? manifest
+    : Array.isArray(manifest.entries)
+      ? manifest.entries
+      : [];
+  for (const e of list) {
+    if (!e) continue;
+    if (typeof e === "string") { out.add(e); continue; }
+    if (e.reachable) out.add(e.id);
+  }
+  return out;
+}
+
+/** Strategy streams, tolerating the several shapes org-context has carried. */
+function strategyStreams(strategy) {
+  if (!strategy) return [];
+  const raw = Array.isArray(strategy.streams) ? strategy.streams
+    : Array.isArray(strategy.workstreams) ? strategy.workstreams
+      : [];
+  return raw.filter((s) => s && (s.title || s.name || s.code || s.id));
+}
+
+/** Cheap token-overlap score (deterministic; stopwords dropped). */
+const STOP = new Set(["the", "a", "an", "and", "or", "of", "to", "for", "with", "on", "in", "own", "every", "its"]);
+function overlapScore(a, b) {
+  const ta = new Set(String(a).split(/[^a-z0-9]+/).filter((w) => w.length > 3 && !STOP.has(w)));
+  const tb = new Set(String(b).split(/[^a-z0-9]+/).filter((w) => w.length > 3 && !STOP.has(w)));
+  let n = 0;
+  for (const w of ta) if (tb.has(w)) n++;
+  return n;
+}
+
+export default { deriveMandate, toMandateBody, pickSensor, slug, firstClause, SENSOR_HINTS, OBJECTIVE_KINDS, DIRECTIONS, CADENCES };