@monster-orange/den 0.4.8 → 0.4.9

package/src/shared/den-config.ts

@@ -20,6 +20,7 @@ import { validateOrgSources, type WorkOrgsConfig } from "./org-sources.js";
 import { ConfigError, isConfigError } from "./config-error.js";
 import { validateCatalog, type CatalogEntry } from "./agents/catalog.js";
 import type { Guardrails } from "./agents/guardrails.js";
+import { DEFAULT_ROTATE, type RotateSettings } from "./agents/rotation.js";
 import type { TestAccountsConfig } from "./auth/test-accounts.js";
 
 import { product } from "./product.js";
@@ -879,6 +880,13 @@ export interface AgentsConfig {
    * Den doesn't ship, with the same fields and checks as a built-in one.
    */
   runtime_catalog?: unknown[];
+  /**
+   * Session rotation (den#4), `{ after_compactions, standing }`: a session
+   * ends after `after_compactions` compactions (default 3) or once its pull
+   * request merged, and its role relaunches from its handoff. `standing:
+   * false` keeps standing personas from rotating (default true).
+   */
+  rotate?: { after_compactions?: unknown; standing?: unknown };
   /**
    * Any other key is an agent id: `agents.<id>.grants` widens that agent's
    * MCP scope to other workspaces (AG spec §5b). Config only: an agent
@@ -902,6 +910,7 @@ export const AGENTS_RESERVED_KEYS = [
   "persona_packs",
   "runtime_catalog",
   "default_pack",
+  "rotate",
 ];
 
 /** One agent's own block, `agents.<id>`. */
@@ -923,6 +932,37 @@ export interface ResolvedAgentsConfig {
   agents: Record<string, AgentGrantsConfig>;
   /** The distribution's runtime catalog entries (AG-0.5), checked. */
   runtimeCatalog: CatalogEntry[];
+  /** agents.rotate with its defaults (den#4); unset: DEFAULT_ROTATE. */
+  rotate?: RotateSettings;
+}
+
+/** `agents.rotate` checked; any other key, or a bad value, throws naming it. */
+function rotateBlock(v: unknown): RotateSettings {
+  const out: RotateSettings = { ...DEFAULT_ROTATE };
+  if (v === undefined || v === null) return out;
+  if (!isMapping(v))
+    throw new Error(
+      "agents.rotate: must be a mapping ({ after_compactions: <n>, standing: true|false })",
+    );
+  for (const [k, x] of Object.entries(v)) {
+    if (k === "after_compactions") {
+      if (typeof x !== "number" || !Number.isInteger(x) || x < 1 || x > 100)
+        throw new Error(
+          `agents.rotate.after_compactions: must be a whole number from 1 to 100 (got ${JSON.stringify(x)})`,
+        );
+      out.afterCompactions = x;
+    } else if (k === "standing") {
+      if (typeof x !== "boolean")
+        throw new Error(
+          `agents.rotate.standing: must be true or false (got ${JSON.stringify(x)})`,
+        );
+      out.standing = x;
+    } else
+      throw new Error(
+        `agents.rotate.${k}: unknown key (takes after_compactions, standing)`,
+      );
+  }
+  return out;
 }
 
 /** An agent id or workspace name: what WORKSPACE_NAME_RE accepts. */
@@ -985,6 +1025,7 @@ export function readAgentsConfig(
       raw.runtime_catalog,
       "agents.runtime_catalog",
     ),
+    rotate: rotateBlock(raw.rotate),
   };
   const max = raw.max_concurrent;
   if (max !== undefined) {
@@ -1018,7 +1059,7 @@ export function readAgentsConfig(
     const where = `agents.${id}`;
     if (!AGENT_KEY_RE.test(id) || !isMapping(block))
       throw new Error(
-        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, default_pack, ` +
+        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, default_pack, rotate, ` +
           `or an agent id mapping to { grants: [...] })`,
       );
     for (const k of Object.keys(block))

package/src/shared/git/gh-pr-state.ts

@@ -0,0 +1,32 @@
+/**
+ * A pull request's state from gh, to confirm a merge an agent ran
+ * (session rotation's "PR merged" trigger, den#4). It runs gh, which asks
+ * GitHub; usage itself stays local (src/shared/usage never sends).
+ */
+import { execFile } from "child_process";
+
+/**
+ * `gh pr view [<ref>] [-R <repo>] --json state -q .state`;
+ * rejects on any error. Only the ref and repo go out, to GitHub, by gh.
+ */
+export function ghPrState(env: NodeJS.ProcessEnv) {
+  return (ref: string, o: { repo?: string; cwd: string }) =>
+    new Promise<string | undefined>((res, rej) => {
+      const args = [
+        "pr",
+        "view",
+        ...(ref ? [ref] : []),
+        ...(o.repo ? ["-R", o.repo] : []),
+        "--json",
+        "state",
+        "-q",
+        ".state",
+      ];
+      execFile(
+        "gh",
+        args,
+        { cwd: o.cwd, env, timeout: 15_000, maxBuffer: 64 * 1024 },
+        (e, stdout) => (e ? rej(e) : res(String(stdout).trim())),
+      );
+    });
+}

package/src/shared/usage/report.ts

@@ -8,6 +8,17 @@
  * share of attributed sessions is the scorecard metric: before this, no
  * agent's tokens or outcome were joined to it (~0).
  *
+ * Session rotation (den#4) adds, per agent, its compactions (this
+ * conversation's) and its rotations (how many times Den relaunched it from
+ * a handoff); and per week, two numbers to move:
+ *   - long_session_context_k: the highest average context per call (input,
+ *     cache reads and cache writes, over calls) of any main session in the
+ *     window, in thousands of tokens;
+ *   - never_ending_reread_pct: the share of context re-reads (cache reads)
+ *     that came from never-ending sessions: main sessions that compacted
+ *     more often than the rotation limit (agents.rotate.after_compactions,
+ *     default 3).
+ *
  * Everything is read and written on this machine; nothing is sent.
  */
 import type {
@@ -30,6 +41,10 @@ export interface AgentUsageRow {
   usage?: AgentUsage;
   outcome?: AgentOutcome;
   attributed: boolean;
+  /** Its current conversation's compactions (den#4), when counted. */
+  compactions?: number;
+  /** How many times Den relaunched it from a handoff (den#4). */
+  rotations: number;
 }
 
 /** The sum of transcripts' counts, as the record keeps them. */
@@ -79,7 +94,6 @@ export function outcomeOf(
   }
   const pr = [...all].reverse().find((s) => s.prOpened)?.prOpened;
   if (pr) out.prOpened = pr;
-  if (all.some((s) => s.prMerged)) out.prMerged = true;
   // The last test run: of the transcript that ended last and ran tests.
   const tested = all
     .filter((s) => s.testsGreen !== undefined)
@@ -88,6 +102,40 @@ export function outcomeOf(
   return out;
 }
 
+/**
+ * Whether one of the transcripts' `gh pr merge` claims is a pull request
+ * gh says is MERGED. A bare `gh pr merge` (the branch's PR) is checked by
+ * the PR the agent opened, else in its folder.
+ */
+async function mergeVerified(
+  rec: AgentRecord,
+  stats: readonly TranscriptStats[],
+  outcome: AgentOutcome,
+  prState?: (
+    ref: string,
+    o: { repo?: string; cwd: string },
+  ) => Promise<string | undefined>,
+): Promise<boolean> {
+  if (!prState) return false;
+  const seen = new Set<string>();
+  for (const c of stats.flatMap((s) => s.prMerges)) {
+    const ref = c.ref || outcome.prOpened || "";
+    const key = `${c.repo ?? ""} ${ref}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    try {
+      const st = await prState(ref, {
+        ...(c.repo ? { repo: c.repo } : {}),
+        cwd: rec.cwd,
+      });
+      if (st?.trim().toUpperCase() === "MERGED") return true;
+    } catch {
+      // Not checked: not marked.
+    }
+  }
+  return false;
+}
+
 /**
  * Each record's usage and outcome, from its runtime's transcripts (by its
  * resumeToken). `source` picks the reader (default: the one for its runtime).
@@ -97,6 +145,15 @@ export async function agentUsage(
   opts: {
     env?: NodeJS.ProcessEnv;
     source?: (runtime: string) => UsageSource | undefined;
+    /**
+     * A pull request's state (`gh pr view <ref> --json state`), run in the
+     * agent's folder: "MERGED" marks the outcome merged. Without it, or on
+     * any error, nothing is marked: a merge is never taken from text.
+     */
+    prState?: (
+      ref: string,
+      o: { repo?: string; cwd: string },
+    ) => Promise<string | undefined>;
   } = {},
 ): Promise<AgentUsageRow[]> {
   const pick = opts.source ?? sourceFor;
@@ -107,6 +164,7 @@ export async function agentUsage(
       workspace: rec.workspace,
       persona: rec.persona,
       runtime: rec.runtime,
+      rotations: rec.rotations?.length ?? 0,
     };
     const src = pick(rec.runtime);
     if (!src) {
@@ -140,11 +198,14 @@ export async function agentUsage(
     }
     const usage = sumUsage(stats);
     const outcome = outcomeOf(rec, stats);
+    if (await mergeVerified(rec, stats, outcome, opts.prState))
+      outcome.prMerged = true;
     rows.push({
       ...base,
       transcripts: files.length,
       usage,
       outcome,
+      compactions: usage.compactions,
       attributed: usage.calls > 0 && outcome.wallClockMs !== undefined,
     });
   }
@@ -176,6 +237,23 @@ export interface UsageMetrics {
   subagent_opus_pct: number;
   /** den#6: the share of agent sessions with attributed tokens and outcome. */
   attributed_pct?: number;
+  /** den#4: the highest average context per call of a main session (k tokens). */
+  long_session_context_k: number;
+  /** den#4: the share of cache reads from never-ending main sessions. */
+  never_ending_reread_pct: number;
+  /** den#4: relaunches from a handoff, over the agents listed. */
+  rotations?: number;
+}
+
+/** A main session's average context per call, in tokens. */
+export function contextPerCall(s: TranscriptStats): number {
+  const t = s.tokens.input + s.tokens.cacheRead + s.tokens.cacheWrite;
+  return s.calls ? t / s.calls : 0;
+}
+
+/** Never-ending: a main session that compacted more often than the limit. */
+export function isNeverEnding(s: TranscriptStats, after: number): boolean {
+  return !s.subagent && s.compactions > after;
 }
 
 const round = (n: number, d = 0) => {
@@ -186,6 +264,8 @@ const round = (n: number, d = 0) => {
 export function weeklyMetrics(
   stats: readonly TranscriptStats[],
   agents?: readonly AgentUsageRow[],
+  /** The rotation limit (agents.rotate.after_compactions, default 3). */
+  after = 3,
 ): UsageMetrics {
   const sum = (
     xs: readonly TranscriptStats[],
@@ -239,14 +319,28 @@ export function weeklyMetrics(
       1,
     ),
     subagent_opus_pct: round((100 * subOpus) / Math.max(1, subTotal)),
+    long_session_context_k: round(
+      Math.max(0, ...main.map(contextPerCall)) / 1e3,
+    ),
+    never_ending_reread_pct: round(
+      (100 *
+        sum(
+          main.filter((s) => isNeverEnding(s, after)),
+          (s) => s.tokens.cacheRead,
+        )) /
+        Math.max(1, reads),
+    ),
   };
-  if (agents) m.attributed_pct = attributedPct(agents);
+  if (agents) {
+    m.attributed_pct = attributedPct(agents);
+    m.rotations = agents.reduce((a, r) => a + r.rotations, 0);
+  }
   return m;
 }
 
 /** Higher is better for these; context only for calls, output and prompts. */
 const BETTER_HIGH = new Set(["attributed_pct"]);
-const CONTEXT = new Set(["calls", "output_M", "prompts"]);
+const CONTEXT = new Set(["calls", "output_M", "prompts", "rotations"]);
 
 /** The report as markdown: this week, last week, and the change. */
 export function renderReport(
@@ -277,7 +371,7 @@ export function renderReport(
   }
   lines.push(
     "",
-    "Read from this machine's transcripts; nothing was sent anywhere.",
+    "Read from this machine's transcripts; none of this was sent anywhere.",
   );
   return lines.join("\n") + "\n";
 }

package/src/shared/usage/transcript.ts

@@ -49,11 +49,66 @@ export interface TranscriptStats {
   activeSeconds: number;
   /** The last pull request URL it opened. */
   prOpened?: string;
-  prMerged: boolean;
+  /**
+   * `gh pr merge` commands that exited 0: claims, which `usage` checks
+   * with `gh pr view` before it marks the pull request merged.
+   */
+  prMerges: PrMergeClaim[];
   /** The last test run's result; undefined when it ran none. */
   testsGreen?: boolean;
 }
 
+/** A `gh pr merge` that ran: its PR (number, URL, or "" for the branch's). */
+export interface PrMergeClaim {
+  ref: string;
+  repo?: string;
+}
+
+/** Words of one simple command, with quotes removed (no expansion). */
+function words(part: string): string[] {
+  const out: string[] = [];
+  for (const m of part.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g))
+    out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}
+
+/**
+ * The merge a shell command runs: one of its parts (split on `&&`, `||`,
+ * `;`, `|`, newlines), after `VAR=value` words, `env` or `command`, starts
+ * with `gh pr merge`, and is not asking for help. Null otherwise:
+ * `echo gh pr merge 1`, a grep for it, or a comment are not merges.
+ */
+export function ghPrMergeRef(cmd: string): PrMergeClaim | null {
+  for (const part of cmd.split(/&&|\|\||;|\||\n/)) {
+    const w = words(part.trim());
+    let i = 0;
+    while (
+      i < w.length &&
+      (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w[i]) ||
+        w[i] === "env" ||
+        w[i] === "command")
+    )
+      i++;
+    if (w[i] !== "gh" || w[i + 1] !== "pr" || w[i + 2] !== "merge") continue;
+    const rest = w.slice(i + 3);
+    if (rest.includes("--help") || rest.includes("-h")) return null;
+    const claim: PrMergeClaim = { ref: "" };
+    for (let j = 0; j < rest.length; j++) {
+      const a = rest[j];
+      if (a === "-R" || a === "--repo") {
+        if (rest[j + 1]) claim.repo = rest[++j];
+      } else if (a.startsWith("--repo=")) claim.repo = a.slice(7);
+      else if (
+        !claim.ref &&
+        /^(\d+|https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+)$/.test(a)
+      )
+        claim.ref = a;
+    }
+    return claim;
+  }
+  return null;
+}
+
 /** A correction, as the miner reads one (emphatic ones; polite ones slip by). */
 const CORRECTION =
   /\b(wtf|fuck|shit|damn|not what i (said|asked)|that('s| is) wrong|you (missed|forgot|broke)|again\??$|still (not|broken|failing|404)|where (is|the)|why (did|didn't|are|is)|i told you|stop|no,|nope|ugh|boo)\b/i;
@@ -130,13 +185,13 @@ export async function mineTranscript(
     interrupts: 0,
     agentSpawns: 0,
     activeSeconds: 0,
-    prMerged: false,
+    prMerges: [],
   };
   const seen = new Set<string>();
   const toolNames = new Map<string, string>();
   /** Tool-use ids of the commands whose result decides an outcome. */
   const tests = new Map<string, number>();
-  const merges = new Set<string>();
+  const merges = new Map<string, PrMergeClaim>();
   const creates = new Set<string>();
   let order = 0;
   let lastTest: { at: number; green: boolean } | undefined;
@@ -217,7 +272,8 @@ export async function mineTranscript(
         for (const s of cmd.matchAll(/\bsleep\s+(\d+)/g))
           r.sleepSeconds += Number(s[1]);
         if (TEST_RUN.test(cmd)) tests.set(useId, order++);
-        if (/\bgh pr merge\b/.test(cmd)) merges.add(useId);
+        const merge = ghPrMergeRef(cmd);
+        if (merge) merges.set(useId, merge);
         if (/\bgh pr create\b/.test(cmd)) creates.add(useId);
       }
       continue;
@@ -240,7 +296,8 @@ export async function mineTranscript(
         const t = tests.get(useId);
         if (t !== undefined && (!lastTest || t >= lastTest.at))
           lastTest = { at: t, green: !err };
-        if (merges.has(useId) && !err) r.prMerged = true;
+        const merge = merges.get(useId);
+        if (merge && !err) r.prMerges.push(merge);
         if (creates.has(useId) && !err) {
           const u = PR_URL.exec(textOf(tr.content));
           if (u) r.prOpened = u[0];