@cohortapp/agent-sdk 2.3.0

package/lib/learning/counters.mjs

@@ -0,0 +1,156 @@
+/**
+ * lib/learning/counters.mjs — file-backed nudge counters for the self-learning
+ * loop (WS3).
+ *
+ * The reflect pass (lib/learning/reflect.mjs) raises the *prior* on authoring a
+ * skill when the agent has done a lot of work without capturing one. These
+ * counters are the cheap, durable signal that feeds that nudge:
+ *
+ *   state/learning/counters.json
+ *     {
+ *       tool_uses_since_skill,   // +1 per PostToolUse beat (hook-runner)
+ *       sessions_since_skill,    // +1 per reflect run
+ *       last_skill_at,           // ISO 8601 of the last skill write
+ *       last_reflect_at          // ISO 8601 of the last reflect run
+ *     }
+ *
+ * Hard guarantees (these run inside global Claude Code hooks on EVERY session
+ * machine-wide): FAIL-OPEN — any error → best-effort no-op, never throws,
+ * never blocks a session. Writes are atomic (tmp + rename in the same dir).
+ *
+ * @module lib/learning/counters
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const COUNTERS_REL = "state/learning/counters.json";
+
+/** Absolute path of the counters file for an agent root. */
+export function countersPath(agentRoot) {
+  return join(agentRoot, COUNTERS_REL);
+}
+
+/** The zero state — what a fresh agent (or an unreadable file) reads as. */
+export function emptyCounters() {
+  return {
+    tool_uses_since_skill: 0,
+    sessions_since_skill: 0,
+    last_skill_at: null,
+    last_reflect_at: null,
+  };
+}
+
+function coerceInt(n) {
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+}
+
+/**
+ * Read the counters for an agent root. Fail-open: a missing/corrupt file reads
+ * as {@link emptyCounters}. Never throws.
+ * @param {string} agentRoot
+ * @returns {{tool_uses_since_skill:number, sessions_since_skill:number, last_skill_at:?string, last_reflect_at:?string}}
+ */
+export function readCounters(agentRoot) {
+  const base = emptyCounters();
+  if (!agentRoot) return base;
+  try {
+    const p = countersPath(agentRoot);
+    if (!existsSync(p)) return base;
+    const obj = JSON.parse(readFileSync(p, "utf8"));
+    if (!obj || typeof obj !== "object") return base;
+    return {
+      tool_uses_since_skill: coerceInt(obj.tool_uses_since_skill),
+      sessions_since_skill: coerceInt(obj.sessions_since_skill),
+      last_skill_at: typeof obj.last_skill_at === "string" ? obj.last_skill_at : null,
+      last_reflect_at: typeof obj.last_reflect_at === "string" ? obj.last_reflect_at : null,
+    };
+  } catch {
+    return base;
+  }
+}
+
+/** Atomic JSON write (tmp + rename in the same dir). Fail-open → false. */
+function writeAtomic(agentRoot, counters) {
+  try {
+    const p = countersPath(agentRoot);
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(counters, null, 2) + "\n");
+    renameSync(tmp, p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Apply `fn` to the current counters and persist the result atomically.
+ * Fail-open: returns the (attempted) next state regardless of write success.
+ * @param {string} agentRoot
+ * @param {(c:object)=>object} fn
+ * @returns {object} the next counters
+ */
+function update(agentRoot, fn) {
+  const cur = readCounters(agentRoot);
+  let next;
+  try { next = fn({ ...cur }) || cur; } catch { next = cur; }
+  if (agentRoot) writeAtomic(agentRoot, next);
+  return next;
+}
+
+/**
+ * +1 the tool-use counter. Called from the PostToolUse beat handler, so it is
+ * the hottest path here — keep it cheap and silent.
+ * @param {string} agentRoot
+ * @param {number} [by=1]
+ */
+export function bumpToolUses(agentRoot, by = 1) {
+  const inc = Number.isFinite(by) && by > 0 ? Math.floor(by) : 1;
+  return update(agentRoot, (c) => {
+    c.tool_uses_since_skill = coerceInt(c.tool_uses_since_skill) + inc;
+    return c;
+  });
+}
+
+/**
+ * +1 the sessions-reflected counter and stamp last_reflect_at. Called once per
+ * reflect run.
+ * @param {string} agentRoot
+ * @param {object} [opts] - { nowMs }
+ */
+export function bumpSessions(agentRoot, opts = {}) {
+  const ts = new Date(Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now()).toISOString();
+  return update(agentRoot, (c) => {
+    c.sessions_since_skill = coerceInt(c.sessions_since_skill) + 1;
+    c.last_reflect_at = ts;
+    return c;
+  });
+}
+
+/**
+ * Reset the "since last skill" counters and stamp last_skill_at. Called the
+ * moment a skill is created/patched so the nudge prior drops back to baseline.
+ * @param {string} agentRoot
+ * @param {object} [opts] - { nowMs }
+ */
+export function resetSkillCounters(agentRoot, opts = {}) {
+  const ts = new Date(Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now()).toISOString();
+  return update(agentRoot, (c) => {
+    c.tool_uses_since_skill = 0;
+    c.sessions_since_skill = 0;
+    c.last_skill_at = ts;
+    return c;
+  });
+}
+
+export default {
+  countersPath,
+  emptyCounters,
+  readCounters,
+  bumpToolUses,
+  bumpSessions,
+  resetSkillCounters,
+};

package/lib/learning/counters.test.mjs

@@ -0,0 +1,69 @@
+/**
+ * counters.test.mjs — nudge-counter bump/reset/read tests.
+ * Run: node --test lib/learning/counters.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  countersPath, emptyCounters, readCounters,
+  bumpToolUses, bumpSessions, resetSkillCounters,
+} from "./counters.mjs";
+
+function tmpRoot() {
+  return mkdtempSync(join(tmpdir(), "maestro-counters-"));
+}
+
+test("readCounters: fresh root reads as empty, never throws", () => {
+  const root = tmpRoot();
+  assert.deepEqual(readCounters(root), emptyCounters());
+  // No agentRoot → still empty, no throw.
+  assert.deepEqual(readCounters(null), emptyCounters());
+});
+
+test("readCounters: corrupt file fails open to empty", () => {
+  const root = tmpRoot();
+  const p = countersPath(root);
+  mkdirSync(join(root, "state", "learning"), { recursive: true });
+  writeFileSync(p, "{ not json");
+  assert.deepEqual(readCounters(root), emptyCounters());
+});
+
+test("bumpToolUses: increments and persists atomically", () => {
+  const root = tmpRoot();
+  bumpToolUses(root);
+  bumpToolUses(root, 4);
+  const c = readCounters(root);
+  assert.equal(c.tool_uses_since_skill, 5);
+  assert.ok(existsSync(countersPath(root)), "counters.json written");
+  // Round-trips through disk (not just in-memory).
+  const onDisk = JSON.parse(readFileSync(countersPath(root), "utf8"));
+  assert.equal(onDisk.tool_uses_since_skill, 5);
+});
+
+test("bumpSessions: increments + stamps last_reflect_at", () => {
+  const root = tmpRoot();
+  const nowMs = Date.parse("2026-06-09T10:00:00Z");
+  bumpSessions(root, { nowMs });
+  bumpSessions(root, { nowMs });
+  const c = readCounters(root);
+  assert.equal(c.sessions_since_skill, 2);
+  assert.equal(c.last_reflect_at, new Date(nowMs).toISOString());
+});
+
+test("resetSkillCounters: zeroes both counters + stamps last_skill_at", () => {
+  const root = tmpRoot();
+  bumpToolUses(root, 50);
+  bumpSessions(root);
+  const nowMs = Date.parse("2026-06-09T12:00:00Z");
+  resetSkillCounters(root, { nowMs });
+  const c = readCounters(root);
+  assert.equal(c.tool_uses_since_skill, 0);
+  assert.equal(c.sessions_since_skill, 0);
+  assert.equal(c.last_skill_at, new Date(nowMs).toISOString());
+});

package/lib/learning/curator-consolidate.test.mjs

@@ -0,0 +1,238 @@
+/**
+ * curator-consolidate.test.mjs — LLM skill-umbrella consolidation (WS3 phase 2).
+ * Run: node --test lib/learning/curator-consolidate.test.mjs
+ *
+ * consolidateUmbrellas() merges narrowly-overlapping agent-authored skills into
+ * ONE class-level umbrella. The LLM is a bounded, INJECTED function: a fake
+ * `spawn` returns a strict-JSON envelope; no `claude --print`, no network. We
+ * assert the full effect of a real consolidation:
+ *   - the umbrella .md is created + added to plugin.json,
+ *   - each absorbed skill is MOVED to _archive/ + dropped from plugin.json +
+ *     marked state:"archived" / absorbed_into in the sidecar,
+ *   - a consolidate row is appended to logs/audit/skills.jsonl,
+ *   - below threshold → no spawn, no writes,
+ *   - malformed / empty spawn output → fail-open no-op,
+ *   - any thrown spawn → fail-open ({umbrellas:[], error}), never throws.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { consolidateUmbrellas } from "./curator.mjs";
+import { writeSkill, readSidecar } from "./skill-writer.mjs";
+
+function tmpRoot() {
+  return mkdtempSync(join(tmpdir(), "maestro-consolidate-"));
+}
+const skillPath = (root, id) => join(root, "plugins", "agent-skills", "skills", `${id}.md`);
+const archivePath = (root, id) => join(root, "plugins", "agent-skills", "skills", "_archive", `${id}.md`);
+const pluginJson = (root) => JSON.parse(readFileSync(join(root, "plugins", "agent-skills", "plugin.json"), "utf8"));
+const auditPath = (root) => join(root, "logs", "audit", "skills.jsonl");
+function auditRows(root) {
+  if (!existsSync(auditPath(root))) return [];
+  return readFileSync(auditPath(root), "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+
+/** Seed N active (live) skills to consolidate; returns their ids. */
+function seedSkills(root, n) {
+  const ids = [];
+  for (let i = 0; i < n; i++) {
+    const w = writeSkill({
+      agentRoot: root,
+      name: `Reconcile ledger variant ${i}`,
+      description: `close the books for source ${i}`,
+      body: `# Reconcile ${i}\n1. pull export\n2. diff ledger\n3. close`,
+      nowIso: new Date().toISOString(),
+      trusted: true, // seed LIVE skills; consolidation operates on active skills
+    });
+    assert.ok(w.ok, `seed skill ${i}`);
+    ids.push(w.id);
+  }
+  return ids;
+}
+
+/** A fake spawn that returns a JSON envelope merging the given absorb ids. */
+function spawnMerging(umbrellaName, absorb) {
+  return async () => JSON.stringify({
+    umbrellas: [{
+      name: umbrellaName,
+      description: "class-level reconciliation umbrella",
+      body: "# Reconciliation\nWhen closing any ledger:\n1. pull\n2. diff\n3. close",
+      absorbs: absorb,
+    }],
+  });
+}
+
+test("below minSkills → no spawn, no writes, reason 'below-threshold'", async () => {
+  const root = tmpRoot();
+  seedSkills(root, 3);
+  let spawned = false;
+  const res = await consolidateUmbrellas({
+    agentRoot: root,
+    minSkills: 5,
+    spawn: async () => { spawned = true; return "{}"; },
+  });
+  assert.equal(spawned, false, "spawn never called below threshold");
+  assert.equal(res.reason, "below-threshold");
+  assert.deepEqual(res.umbrellas, []);
+});
+
+test("merges 2 of N siblings: creates umbrella, archives absorbed, audits", async () => {
+  const root = tmpRoot();
+  const ids = seedSkills(root, 5);
+  const absorb = [ids[0], ids[1]];
+  assert.equal(pluginJson(root).skills.length, 5);
+
+  const res = await consolidateUmbrellas({
+    agentRoot: root,
+    minSkills: 5,
+    spawn: spawnMerging("Reconciliation", absorb),
+  });
+
+  // Summary
+  assert.equal(res.umbrellas.length, 1, "one umbrella created");
+  const umb = res.umbrellas[0];
+  assert.deepEqual(umb.absorbed.sort(), absorb.slice().sort());
+  assert.ok(umb.id, "umbrella has an id");
+
+  // Umbrella .md created + present in plugin.json.
+  assert.ok(existsSync(skillPath(root, umb.id)), "umbrella .md written");
+  const pj = pluginJson(root);
+  assert.ok(pj.skills.some((s) => s.name === umb.id), "umbrella in plugin.json");
+
+  // Absorbed skills: MOVED to _archive/, dropped from plugin.json.
+  for (const id of absorb) {
+    assert.ok(!existsSync(skillPath(root, id)), `${id} removed from active dir`);
+    assert.ok(existsSync(archivePath(root, id)), `${id} moved to _archive (not deleted)`);
+    assert.ok(!pj.skills.some((s) => s.name === id), `${id} dropped from plugin.json`);
+  }
+
+  // The 3 un-absorbed siblings + the umbrella remain in plugin.json (5 - 2 + 1 = 4).
+  assert.equal(pj.skills.length, 4, "plugin.json reflects archive + umbrella");
+
+  // Sidecar: absorbed marked archived + absorbed_into the umbrella id.
+  const sc = readSidecar(root);
+  for (const id of absorb) {
+    assert.equal(sc[id].state, "archived", `${id} sidecar state archived`);
+    assert.equal(sc[id].absorbed_into, umb.id, `${id} absorbed_into umbrella`);
+    assert.ok(sc[id].archived_at, `${id} has archived_at`);
+  }
+  // Umbrella sidecar record exists, active.
+  assert.ok(sc[umb.id], "umbrella sidecar record");
+  assert.equal(sc[umb.id].state, "active");
+
+  // Audit: a consolidate row referencing the umbrella + absorbed ids.
+  const rows = auditRows(root);
+  const consolidate = rows.find((r) => r.action === "consolidate");
+  assert.ok(consolidate, "consolidate audit row written");
+  assert.equal(consolidate.umbrella, umb.id);
+  assert.deepEqual(consolidate.absorbed.slice().sort(), absorb.slice().sort());
+});
+
+test("malformed spawn output → fail-open no-op (no umbrella, siblings untouched)", async () => {
+  const root = tmpRoot();
+  const ids = seedSkills(root, 5);
+  const before = pluginJson(root).skills.length;
+
+  const res = await consolidateUmbrellas({
+    agentRoot: root,
+    minSkills: 5,
+    spawn: async () => "this is not json at all",
+  });
+  assert.deepEqual(res.umbrellas, []);
+  assert.equal(pluginJson(root).skills.length, before, "no skills archived");
+  // None of the seeded skills moved.
+  for (const id of ids) assert.ok(existsSync(skillPath(root, id)), `${id} untouched`);
+});
+
+test("empty-envelope spawn (no clusters) → no-op", async () => {
+  const root = tmpRoot();
+  seedSkills(root, 6);
+  const res = await consolidateUmbrellas({
+    agentRoot: root,
+    minSkills: 5,
+    spawn: async () => JSON.stringify({ umbrellas: [] }),
+  });
+  assert.deepEqual(res.umbrellas, []);
+  assert.equal(pluginJson(root).skills.length, 6, "all siblings intact");
+});
+
+test("a cluster of <2 absorbs is rejected (never merge a single skill into an umbrella)", async () => {
+  const root = tmpRoot();
+  const ids = seedSkills(root, 5);
+  const res = await consolidateUmbrellas({
+    agentRoot: root,
+    minSkills: 5,
+    spawn: async () => JSON.stringify({
+      umbrellas: [{ name: "Singleton", description: "d", body: "b", absorbs: [ids[0]] }],
+    }),
+  });
+  assert.deepEqual(res.umbrellas, [], "singleton cluster ignored");
+  assert.ok(existsSync(skillPath(root, ids[0])), "lone skill not archived");
+});
+
+test("absorbs referencing unknown ids are filtered (only real siblings merge)", async () => {
+  const root = tmpRoot();
+  const ids = seedSkills(root, 5);
+  const res = await consolidateUmbrellas({
+    agentRoot: root,
+    minSkills: 5,
+    // one valid id + one bogus → after filtering only 1 valid → cluster <2 → reject.
+    spawn: async () => JSON.stringify({
+      umbrellas: [{ name: "Mixed", description: "d", body: "b", absorbs: [ids[0], "does-not-exist"] }],
+    }),
+  });
+  assert.deepEqual(res.umbrellas, [], "cluster with <2 *valid* absorbs rejected");
+  assert.ok(existsSync(skillPath(root, ids[0])), "valid id not archived when cluster invalid");
+});
+
+test("a throwing spawn is fully fail-open: returns {umbrellas:[], error}, never throws", async () => {
+  const root = tmpRoot();
+  seedSkills(root, 5);
+  let res;
+  await assert.doesNotReject(async () => {
+    res = await consolidateUmbrellas({
+      agentRoot: root,
+      minSkills: 5,
+      spawn: async () => { throw new Error("model down"); },
+    });
+  });
+  assert.deepEqual(res.umbrellas, []);
+  assert.ok(res.error, "error captured in summary");
+});
+
+test("no agentRoot → clean no-op", async () => {
+  const res = await consolidateUmbrellas({ spawn: async () => "{}" });
+  assert.deepEqual(res.umbrellas, []);
+});
+
+test("pinned / non-agent / already-archived skills are excluded from candidates", async () => {
+  const root = tmpRoot();
+  const ids = seedSkills(root, 6);
+  // Pin one, archive one, mark one as human-authored.
+  const sc = readSidecar(root);
+  sc[ids[0]].pinned = true;
+  sc[ids[1]].state = "archived";
+  sc[ids[2]].created_by = "human";
+  // writeSidecar via skill-writer re-export
+  const { writeSidecar } = await import("./skill-writer.mjs");
+  writeSidecar(root, sc);
+
+  // The candidate list the prompt sees must exclude pinned/archived/human.
+  // We capture it by inspecting which ids the spawn is asked to consider via a
+  // recording spawn that merges only what it's actually given a description for.
+  let promptSeen = "";
+  await consolidateUmbrellas({
+    agentRoot: root,
+    minSkills: 3,
+    spawn: async (prompt) => { promptSeen = prompt; return JSON.stringify({ umbrellas: [] }); },
+  });
+  assert.ok(!promptSeen.includes(ids[0]), "pinned excluded from prompt");
+  assert.ok(!promptSeen.includes(ids[1]), "archived excluded from prompt");
+  assert.ok(!promptSeen.includes(ids[2]), "human-authored excluded from prompt");
+  assert.ok(promptSeen.includes(ids[3]), "active agent skill included");
+});