@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/plan/compile.mjs

@@ -0,0 +1,510 @@
+/**
+ * lib/plan/compile.mjs — the PLAN COMPILER (SPEC §5.6).
+ *
+ * `(mandate, capabilityManifest, archetypeProfile, orgContext) → obligations[]`
+ *
+ * This is the load-bearing function of the whole design and it is deliberately
+ * BORING: a pure, deterministic, offline reduction over structured JSON. Not an
+ * LLM pass over prose (that makes `obligationsHash` non-deterministic and
+ * manufactures phantom drift), and not a server planning service (that makes a
+ * partitioned agent go dark). Same inputs → byte-identical output, forever.
+ *
+ * Emission rules, in order:
+ *   1. the 19 STANDARD_CADENCES        → SCHEDULE, origin "standard",
+ *                                        triggers copied VERBATIM so existing
+ *                                        launchd plists do not churn
+ *   2. archetype recurring workflows
+ *      + ALTITUDE_CADENCES             → SCHEDULE, origin "archetype"
+ *   3. each ADOPTED objective w/ sensor → SCHEDULE `schedule.measure.<key>`
+ *                                        + OUTCOME `outcome.<key>`
+ *   4. each adopted objective with a
+ *      REVIEWER collaborator           → SCHEDULE `schedule.review.<key>`
+ *   5. mandate `reactsTo[]` + the four
+ *      standard directTo sources        → REACT
+ *
+ * Then, for every obligation: `uses[]` is resolved against the capability
+ * manifest and `allowed_tools[]` is COMPUTED from `uses[]`. That is what closes
+ * the "archetype cadences get {mode, prompt} and a --dangerously-skip-permissions
+ * session" hole — a plan-derived cadence gets a tool scope by construction.
+ *
+ * PROPOSED objectives compile NOTHING. Until a human adopts in hq, the agent runs
+ * exactly today's standard + archetype cadences, which is why this ships
+ * incrementally instead of lockstep.
+ *
+ * Nothing here reads the filesystem, the clock, the network, or Math.random.
+ *
+ * @module lib/plan/compile
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+import { canonical } from "../mandate/cache.mjs";
+
+/** Bump when emission rules change — it is part of `inputsHash`. */
+export const COMPILER_VERSION = 1;
+
+/** Read primitives every session-spawning obligation may use. */
+export const BASELINE_TOOLS = Object.freeze(["Read", "Grep", "Glob", "LS"]);
+
+/**
+ * Capabilities each STANDARD cadence genuinely needs. Single-sourced here so the
+ * emitted `allowedTools` is auditable in one place instead of drifting across
+ * the registry. Entries absent from this table (the deterministic inline
+ * cadences) legitimately need no tools and spawn no session.
+ */
+export const STANDARD_CADENCE_USES = Object.freeze({
+  "inbox-processor": ["email_inbox", "email_triage", "messaging_history", "task_create"],
+  "backlog-executor": ["board_ready", "board_claim", "board_complete", "task_update"],
+  "meeting-prep": ["calendar_list", "calendar_get", "knowledge_search"],
+  "meeting-action-capture": ["meetings_recap_file", "task_create"],
+  "daily-morning-brief": ["calendar_list", "email_inbox", "board_ready"],
+  "daily-midday-sweep": ["board_ready", "messaging_history"],
+  "daily-evening-wrap": ["board_ready", "task_update", "knowledge_append"],
+  "quarterly-self-assessment": ["knowledge_search", "memory_author"],
+  "org-pulse": ["org_snapshot", "org_events_tail"],
+  "dynamic-jobs": ["task_create", "task_update"],
+  "messaging-inbound": ["messaging_channels", "messaging_history", "messaging_send"],
+  "directory-hygiene": [
+    "directory_search", "directory_list_people", "directory_list_captures",
+    "directory_list_merges", "directory_propose_capture", "directory_propose_merge",
+  ],
+  "brand-steward": ["design_foundation", "design_list_templates"],
+});
+
+/**
+ * The four EXISTING `directTo` sources the SSE lane already classifies. These
+ * become REACT obligations for every agent so a directed event always has a
+ * matching obligation (an unmatched T0/T1 event is drift, not routine).
+ */
+export const STANDARD_REACTS = Object.freeze([
+  { key: "react.email.received", topic: "email", kind: "received", uses: ["email_message", "email_thread", "email_send"], offline_safe: false, mode: "escalate" },
+  { key: "react.handoff.offered", topic: "handoff", kind: "offered", uses: ["board_ready", "board_claim"], offline_safe: true, mode: "escalate" },
+  { key: "react.task.assigned", topic: "task", kind: "assigned", uses: ["board_ready", "board_claim", "task_update"], offline_safe: true, mode: "escalate" },
+  { key: "react.approval.requested", topic: "approval", kind: "requested", uses: ["approval_wait", "decision_list"], offline_safe: true, mode: "escalate" },
+]);
+
+/** Deterministic tie-break rank for an obligation key. */
+export function rankOf(key) {
+  return createHash("sha256").update(String(key)).digest("hex");
+}
+
+/** sha256 of a canonical value. */
+function sha(value) {
+  return createHash("sha256").update(typeof value === "string" ? value : canonical(value)).digest("hex");
+}
+
+/**
+ * Map a capability id onto the session tool name the `--allowedTools` flag and
+ * the cadence registry understand.
+ * @param {string} id @returns {string|null}
+ */
+export function toolNameFor(id) {
+  const s = String(id || "");
+  if (s.startsWith("builtin:")) return s.slice("builtin:".length);
+  if (s.startsWith("skill:")) return "Skill";
+  if (s.startsWith("workflow:") || s.startsWith("subagent:")) return "Task";
+  if (s.startsWith("mcp:")) return `mcp__${s.slice("mcp:".length)}__*`;
+  return s || null;
+}
+
+/** allowed_tools[] computed from uses[] — never hand-listed. */
+export function allowedToolsFor(uses, { baseline = BASELINE_TOOLS } = {}) {
+  const out = new Set(baseline);
+  for (const u of uses || []) {
+    const t = toolNameFor(u);
+    if (t) out.add(t);
+  }
+  return [...out].sort();
+}
+
+/** Union of the blast-radius classes of the cited capabilities. */
+export function actionClassesFor(uses, manifest) {
+  const byId = new Map((((manifest && manifest.entries) || [])).map((e) => [e.id, e]));
+  const out = new Set();
+  for (const u of uses || []) {
+    const e = byId.get(u);
+    if (e && e.blastRadius && e.blastRadius !== "internal") out.add(e.blastRadius);
+  }
+  return [...out].sort();
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic slot solver
+// ---------------------------------------------------------------------------
+
+/** Candidate slot spaces per review rhythm. Deterministic + ordered. */
+function candidates(cadence) {
+  const out = [];
+  if (cadence === "weekly") {
+    for (let wd = 1; wd <= 5; wd++) for (let h = 9; h <= 16; h++) for (const m of [0, 30]) out.push({ weekday: wd, hour: h, minute: m });
+  } else if (cadence === "monthly") {
+    for (let d = 1; d <= 5; d++) for (let h = 9; h <= 15; h++) out.push({ day: d, hour: h, minute: 0 });
+  } else if (cadence === "quarterly") {
+    for (let h = 9; h <= 15; h++) out.push({ day: 1, hour: h, minute: 0 });
+  } else {
+    for (let h = 8; h <= 17; h++) for (const m of [0, 30]) out.push({ hour: h, minute: m });
+  }
+  return out;
+}
+
+/** A slot's identity for concurrency accounting. */
+function slotKey(c) {
+  return `${c.weekday ?? "-"}:${c.day ?? "-"}:${c.hour}:${c.minute}`;
+}
+
+/**
+ * Pick a calendar slot deterministically: start from an offset derived from
+ * sha256(key), scan the candidate space in order, skip slots the principal is
+ * busy in and slots already at the concurrency cap. Same inputs → same schedule;
+ * a different mandate (different keys) → a different schedule. This REPLACES the
+ * old `slotOf(id)` hash-stagger, which knew nothing about the calendar.
+ *
+ * @param {string} key
+ * @param {string} cadence  weekly|monthly|quarterly|daily
+ * @param {{busy?:Set<string>, taken?:Map<string,number>, concurrency?:number}} state
+ * @returns {{calendar:object, collided:boolean}}
+ */
+export function solveSlot(key, cadence, state = {}) {
+  const busy = state.busy instanceof Set ? state.busy : new Set();
+  const taken = state.taken instanceof Map ? state.taken : new Map();
+  const cap = Number.isFinite(state.concurrency) ? state.concurrency : 2;
+
+  const space = candidates(cadence);
+  const start = parseInt(rankOf(key).slice(0, 8), 16) % space.length;
+  let fallback = null;
+  for (let i = 0; i < space.length; i++) {
+    const c = space[(start + i) % space.length];
+    const sk = slotKey(c);
+    if (fallback === null) fallback = c;
+    if (busy.has(`${c.weekday ?? "*"}:${c.hour}`)) continue;
+    if ((taken.get(sk) || 0) >= cap) continue;
+    taken.set(sk, (taken.get(sk) || 0) + 1);
+    return { calendar: c, collided: i !== 0 };
+  }
+  // Every slot is busy or capped — take the deterministic fallback and let the
+  // caller record the drift rather than silently dropping the obligation.
+  const sk = slotKey(fallback);
+  taken.set(sk, (taken.get(sk) || 0) + 1);
+  return { calendar: fallback, collided: true, saturated: true };
+}
+
+/** Busy windows from the principal's calendar events (weekday:hour keys). */
+export function busyWindows(events = []) {
+  const out = new Set();
+  for (const e of events || []) {
+    if (!e) continue;
+    const wd = Number.isFinite(e.weekday) ? e.weekday : null;
+    const h = Number.isFinite(e.hour) ? e.hour : null;
+    if (h === null) continue;
+    out.add(`${wd ?? "*"}:${h}`);
+    if (wd !== null) out.add(`*:${h}`);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The compiler
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile the plan.
+ *
+ * @param {object} input
+ * @param {object} input.mandate           the cached mandate BODY ({objectives, budgetCentsPerPeriod, reactsTo, collaborators})
+ * @param {number} [input.mandateVersion]
+ * @param {object} input.manifest          the capability manifest
+ * @param {object} [input.profile]         resolved archetype profile (for the hash + altitude)
+ * @param {object} [input.orgContext]      org-context.json (strategy is part of the hash)
+ * @param {object[]} input.standardCadences   lib/cadences.STANDARD_CADENCES
+ * @param {object[]} [input.archetypeCadences] resolved function+altitude cadences (scope !== "standard")
+ * @param {object[]} [input.calendarEvents]  [{weekday,hour}] busy windows
+ * @param {number} [input.concurrency=2]
+ * @returns {{obligations:object[], inputsHash:string, obligationsHash:string, compilerVersion:number, mandateVersion:number, drift:object[], counts:object}}
+ */
+export function compilePlan(input = {}) {
+  const mandate = input.mandate && typeof input.mandate === "object" ? input.mandate : {};
+  const manifest = input.manifest || { entries: [] };
+  const reachable = new Set(((manifest.entries) || []).filter((e) => e && e.reachable).map((e) => e.id));
+  const standardCadences = Array.isArray(input.standardCadences) ? input.standardCadences : [];
+  const archetypeCadences = Array.isArray(input.archetypeCadences) ? input.archetypeCadences : [];
+  const drift = [];
+  const obligations = [];
+
+  const defaultBudget = Number.isFinite(mandate.budgetCentsPerPeriod) ? mandate.budgetCentsPerPeriod : 500;
+  const seatEnvelope = Number.isFinite(input.seatBudgetCents) ? input.seatBudgetCents : defaultBudget * 20;
+
+  /** Keep only reachable capabilities; record the rest as drift. */
+  const resolveUses = (wanted, obKey) => {
+    const kept = [];
+    for (const id of wanted || []) {
+      if (reachable.has(id)) kept.push(id);
+      else drift.push({ kind: "unreachable_capability", key: obKey, detail: { capability: id } });
+    }
+    return kept;
+  };
+
+  const push = (ob) => {
+    ob.allowed_tools = ob.mode === "inline" ? [] : allowedToolsFor(ob.uses);
+    ob.action_classes = actionClassesFor(ob.uses, manifest);
+    obligations.push(ob);
+    return ob;
+  };
+
+  // ── 1. standard cadences — triggers copied VERBATIM ─────────────────────
+  for (const c of standardCadences) {
+    if (!c || !c.id) continue;
+    const key = `schedule.${c.id}`;
+    const uses = resolveUses(STANDARD_CADENCE_USES[c.id] || [], key);
+    push({
+      key,
+      kind: "SCHEDULE",
+      cadence_id: c.id,
+      scope: "standard",
+      source: { origin: "standard", ref: c.id },
+      mode: c.mode || "escalate",
+      prompt: c.prompt || null,
+      guard_module: null,
+      schedule: c.interval != null ? { interval: c.interval } : { calendar: { ...c.calendar } },
+      uses,
+      budget_cents_per_period: defaultBudget,
+      offline_safe: c.mode === "inline",
+      status: "active",
+    });
+  }
+
+  // ── 2. archetype + altitude cadences ────────────────────────────────────
+  for (const c of archetypeCadences) {
+    if (!c || !c.id) continue;
+    if (c.scope === "standard") continue; // already emitted verbatim above
+    const key = `schedule.${c.id}`;
+    if (obligations.some((o) => o.key === key)) continue;
+    const uses = resolveUses(usesForArchetypeCadence(c, reachable), key);
+    push({
+      key,
+      kind: "SCHEDULE",
+      cadence_id: c.id,
+      scope: c.scope || "archetype",
+      source: { origin: "archetype", ref: c.id },
+      mode: c.mode || "escalate",
+      prompt: c.prompt || `schedules/triggers/${c.id}.md`,
+      guard_module: null,
+      schedule: c.interval != null ? { interval: c.interval } : { calendar: { ...c.calendar } },
+      uses,
+      cadence: c.cadence || null,
+      purpose: c.purpose || "",
+      budget_cents_per_period: defaultBudget,
+      offline_safe: false,
+      status: "active",
+    });
+  }
+
+  // ── 3/4. adopted objectives → measure + outcome (+ review) ──────────────
+  const adopted = (Array.isArray(mandate.objectives) ? mandate.objectives : [])
+    .filter((o) => o && o.state === "active" && o.kind !== "PILLAR");
+  const proposedCount = (Array.isArray(mandate.objectives) ? mandate.objectives : []).filter((o) => o && o.state === "proposed").length;
+
+  // Budget envelope: highest-weight objectives get the envelope first; the rest
+  // are emitted SUSPENDED with an explicit breach record. Never a silent drop.
+  const ordered = adopted.slice().sort((a, b) => (b.weight || 1) - (a.weight || 1) || rankOf(a.key).localeCompare(rankOf(b.key)));
+  const slotState = { busy: busyWindows(input.calendarEvents), taken: new Map(), concurrency: input.concurrency };
+  let spent = 0;
+
+  for (const obj of ordered) {
+    const okey = String(obj.key || "");
+    if (!okey) { drift.push({ kind: "schedule_missing", key: null, detail: { reason: "adopted objective has no key" } }); continue; }
+
+    const sensorOk = obj.sensor && obj.sensor.source === "method" && obj.sensor.capability && reachable.has(obj.sensor.capability);
+    if (!sensorOk) {
+      drift.push({
+        kind: obj.sensor && obj.sensor.capability ? "unreachable_capability" : "stale_sensor",
+        key: `outcome.${okey}`,
+        detail: { objectiveKey: okey, sensor: (obj.sensor && obj.sensor.capability) || null, source: (obj.sensor && obj.sensor.source) || "none" },
+      });
+      continue; // an OUTCOME without a reachable method sensor is not emitted
+    }
+
+    const budget = Number.isFinite(obj.budgetCentsPerPeriod) ? obj.budgetCentsPerPeriod : defaultBudget;
+    const withinEnvelope = spent + budget <= seatEnvelope;
+    if (!withinEnvelope) drift.push({ kind: "budget_breach", key: `outcome.${okey}`, detail: { seatEnvelope, spent, requested: budget } });
+    else spent += budget;
+    const status = withinEnvelope ? "active" : "suspended";
+
+    const measureKey = `schedule.measure.${okey}`;
+    const measureUses = resolveUses([obj.sensor.capability], measureKey);
+    const slot = solveSlot(measureKey, obj.cadence || "weekly", slotState);
+    if (slot.saturated) drift.push({ kind: "schedule_missing", key: measureKey, detail: { reason: "no free calendar slot; placed deterministically anyway" } });
+    push({
+      key: measureKey,
+      kind: "SCHEDULE",
+      cadence_id: `measure-${okey}`,
+      scope: "mandate",
+      source: { origin: "mandate", ref: obj.id || okey, charter_section: obj.charterSectionId || null },
+      objective_id: obj.id || okey,
+      mode: "guarded",
+      prompt: `schedules/triggers/measure-${okey}.md`,
+      guard_module: "lib/goals/loop.mjs",
+      schedule: { calendar: slot.calendar },
+      cadence: obj.cadence || "weekly",
+      uses: measureUses,
+      budget_cents_per_period: budget,
+      offline_safe: true,
+      status,
+    });
+
+    push({
+      key: `outcome.${okey}`,
+      kind: "OUTCOME",
+      scope: "mandate",
+      source: { origin: "mandate", ref: obj.id || okey, charter_section: obj.charterSectionId || null },
+      objective_id: obj.id || okey,
+      metric: obj.metric || okey.replace(/-/g, "_"),
+      target: Number.isFinite(obj.target) ? obj.target : null,
+      direction: obj.direction || "up",
+      tolerance: Number.isFinite(obj.tolerance) ? obj.tolerance : 0,
+      cadence: obj.cadence || "weekly",
+      sensor: { capability: obj.sensor.capability, params: obj.sensor.params || {}, source: "method" },
+      collaborators: Array.isArray(obj.collaborators) ? obj.collaborators : [],
+      mode: "guarded",
+      uses: measureUses,
+      budget_cents_per_period: budget,
+      offline_safe: true,
+      status,
+    });
+
+    const reviewers = (Array.isArray(obj.collaborators) ? obj.collaborators : []).filter((c) => c && String(c.role).toUpperCase() === "REVIEWER");
+    if (reviewers.length) {
+      const reviewKey = `schedule.review.${okey}`;
+      const reviewUses = resolveUses(["board_ready", "messaging_send"], reviewKey);
+      const rslot = solveSlot(reviewKey, obj.cadence || "weekly", slotState);
+      push({
+        key: reviewKey,
+        kind: "SCHEDULE",
+        cadence_id: `review-${okey}`,
+        scope: "mandate",
+        source: { origin: "mandate", ref: obj.id || okey, charter_section: obj.charterSectionId || null },
+        objective_id: obj.id || okey,
+        mode: "escalate",
+        prompt: `schedules/triggers/review-${okey}.md`,
+        guard_module: null,
+        schedule: { calendar: rslot.calendar },
+        cadence: obj.cadence || "weekly",
+        collaborators: reviewers,
+        uses: reviewUses,
+        budget_cents_per_period: budget,
+        offline_safe: false,
+        status,
+      });
+    }
+  }
+
+  // ── 5. REACT obligations ────────────────────────────────────────────────
+  const reacts = [
+    ...STANDARD_REACTS.map((r) => ({ ...r, origin: "react-standard" })),
+    ...(Array.isArray(mandate.reactsTo) ? mandate.reactsTo : []).map((r) => ({
+      key: r && r.key ? String(r.key) : `react.${(r && r.topic) || "unknown"}.${(r && r.kind) || "any"}`,
+      topic: r && r.topic,
+      kind: r && r.kind,
+      predicate: r && r.predicate,
+      uses: (r && r.uses) || [],
+      offline_safe: !!(r && r.offlineSafe),
+      mode: (r && r.mode) || "escalate",
+      origin: "mandate",
+      objective_id: r && r.objectiveId,
+    })),
+  ];
+  for (const r of reacts) {
+    if (!r.topic) continue;
+    if (obligations.some((o) => o.key === r.key)) continue;
+    const uses = resolveUses(r.uses, r.key);
+    push({
+      key: r.key,
+      kind: "REACT",
+      scope: r.origin === "mandate" ? "mandate" : "standard",
+      source: { origin: r.origin, ref: `${r.topic}.${r.kind || "*"}` },
+      objective_id: r.objective_id || null,
+      trigger: { topic: r.topic, kind: r.kind || null, predicate: r.predicate || null },
+      mode: r.mode,
+      uses,
+      budget_cents_per_period: defaultBudget,
+      offline_safe: !!r.offline_safe,
+      status: "active",
+    });
+  }
+
+  // Stable output order: kind rank, then key.
+  const kindRank = { SCHEDULE: 0, OUTCOME: 1, REACT: 2 };
+  obligations.sort((a, b) => (kindRank[a.kind] - kindRank[b.kind]) || a.key.localeCompare(b.key));
+
+  const inputsHash = sha([
+    canonical(mandate),
+    canonical(stripVolatile(manifest)),
+    sha(canonical(input.profile || null)),
+    canonical((input.orgContext && input.orgContext.strategy) || null),
+    `compiler:${COMPILER_VERSION}`,
+  ].join(""));
+
+  const obligationsHash = sha(canonical(obligations.map(identityOf)));
+
+  const counts = {
+    SCHEDULE: obligations.filter((o) => o.kind === "SCHEDULE").length,
+    OUTCOME: obligations.filter((o) => o.kind === "OUTCOME").length,
+    REACT: obligations.filter((o) => o.kind === "REACT").length,
+    total: obligations.length,
+    adoptedObjectives: adopted.length,
+    proposedObjectives: proposedCount,
+    suspended: obligations.filter((o) => o.status !== "active").length,
+  };
+
+  return {
+    obligations,
+    inputsHash,
+    obligationsHash,
+    compilerVersion: COMPILER_VERSION,
+    mandateVersion: Number.isFinite(input.mandateVersion) ? input.mandateVersion : 0,
+    drift,
+    counts,
+  };
+}
+
+/** The identity-bearing projection an obligationsHash is taken over. */
+function identityOf(ob) {
+  return {
+    key: ob.key,
+    kind: ob.kind,
+    status: ob.status,
+    schedule: ob.schedule || null,
+    trigger: ob.trigger || null,
+    objective_id: ob.objective_id || null,
+    uses: ob.uses || [],
+    allowed_tools: ob.allowed_tools || [],
+    mode: ob.mode || null,
+  };
+}
+
+/** Drop probe timestamps so a re-probe that changed nothing changes no hash. */
+function stripVolatile(manifest) {
+  return {
+    schemaVersion: manifest && manifest.schemaVersion,
+    checksum: manifest && manifest.checksum,
+    entries: (((manifest && manifest.entries) || [])).map((e) => ({ id: e.id, plane: e.plane, kind: e.kind, reachable: !!e.reachable, blastRadius: e.blastRadius || null })),
+  };
+}
+
+/** Best-effort capability set for a non-standard cadence (reachable-filtered). */
+function usesForArchetypeCadence(c, reachable) {
+  const text = `${c.id} ${c.purpose || ""}`.toLowerCase();
+  const guesses = [];
+  if (/review|memo|priorit|execution|operating/.test(text)) guesses.push("board_ready", "knowledge_search", "task_update");
+  if (/runway|burn|invest|capital|cost/.test(text)) guesses.push("books_reports");
+  if (/board|investor|stakeholder/.test(text)) guesses.push("knowledge_search", "files_list");
+  if (/commitment|sweep|action/.test(text)) guesses.push("board_ready", "task_update");
+  if (/inbox|mail/.test(text)) guesses.push("email_inbox", "email_triage");
+  if (!guesses.length) guesses.push("knowledge_search");
+  return [...new Set(guesses)].filter((g) => reachable.has(g));
+}
+
+export default {
+  COMPILER_VERSION, BASELINE_TOOLS, STANDARD_CADENCE_USES, STANDARD_REACTS,
+  compilePlan, solveSlot, busyWindows, allowedToolsFor, actionClassesFor, toolNameFor, rankOf,
+};