@monster-orange/den 0.4.7 → 0.4.9

package/src/shared/agents/rotation.ts

@@ -0,0 +1,362 @@
+/**
+ * Session rotation (den#4, rule R2: one session per objective). A session
+ * that never ends re-reads its whole context on every call, so a session
+ * ends when its pull request merges or after a few compactions, and the
+ * role relaunches from a handoff in a fresh conversation.
+ *
+ *   agent-files/<id>/rotation.json   the compaction count of the agent's
+ *                                    current conversation (the SessionStart
+ *                                    "compact" hook's), and whether a rotation is due
+ *   agent-files/<id>/handoff.md      what the session wrote when it rotated
+ *                                    (handoff.ts checks it)
+ *   agent-files/<id>/handoffs/       handoffs Den relaunched from, kept
+ *
+ * Triggers (org config `agents.rotate`):
+ *   - `after_compactions` (default 3): SessionStart "compact" counts each
+ *     compaction that happened; at that many, a rotation is due;
+ *   - the agent's pull request merged: the record's outcome
+ *     (`prMerged`, den#6), which `<cli> usage` fills in.
+ *   `standing: false` keeps standing personas (planner, orchestrator) out:
+ *   they never rotate. Default true: only their context resets, they keep
+ *   their name.
+ *
+ * A rotation is "ready" once it is due and handoff.md passes the check.
+ * Then Den declines a plain Resume and offers Relaunch from handoff.
+ * Everything here is this machine's files; nothing is sent.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { checkHandoff } from "./handoff.js";
+import { agentFilesDir, writePrivate, type AgentRecord } from "./records.js";
+
+export const ROTATION_FILE = "rotation.json";
+export const HANDOFF_FILE = "handoff.md";
+export const HANDOFFS_DIR = "handoffs";
+
+/** Why a session rotates. */
+export type RotateReason = "compactions" | "pr-merged";
+
+export interface RotationState {
+  /**
+   * The conversation counted: Claude Code's session_id, which is the
+   * record's resumeToken. A count for another conversation is stale.
+   */
+  conversation?: string;
+  compactions: number;
+  /** Rotate after this many compactions; 0: this agent never rotates. */
+  after: number;
+  /** The last compaction (ISO 8601) and what triggered it (manual, auto). */
+  lastCompactAt?: string;
+  lastTrigger?: string;
+  /**
+   * PreCompact's trigger, kept until SessionStart "compact" counts the
+   * compaction (SessionStart's input has no trigger).
+   */
+  pendingTrigger?: string;
+  /** Set when a trigger fired. */
+  due?: RotateReason;
+  dueAt?: string;
+}
+
+/** `agents.rotate` with its defaults applied. */
+export interface RotateSettings {
+  /** Compactions before a session rotates (at least 1). */
+  afterCompactions: number;
+  /** Whether standing personas rotate too. */
+  standing: boolean;
+}
+
+export const DEFAULT_ROTATE: RotateSettings = {
+  afterCompactions: 3,
+  standing: true,
+};
+
+/** A rotation Den did (kept in the record, newest last). */
+export interface RotationEntry {
+  /** When it relaunched (ISO 8601). */
+  at: string;
+  reason: RotateReason;
+  /** Compactions of the conversation that ended. */
+  compactions: number;
+  /** The conversation that ended (its resume token). */
+  conversation?: string;
+}
+
+/** The compactions after which `persona` rotates; 0: it never does. */
+export function rotateAfter(
+  settings: RotateSettings,
+  persona: { standing?: boolean },
+): number {
+  if (persona.standing && !settings.standing) return 0;
+  return settings.afterCompactions;
+}
+
+export const rotationFile = (filesDir: string) =>
+  path.join(filesDir, ROTATION_FILE);
+export const handoffFile = (filesDir: string) =>
+  path.join(filesDir, HANDOFF_FILE);
+
+const count = (v: unknown) =>
+  typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : 0;
+
+/** The rotation state in `filesDir`; null when there is none (or it is unreadable). */
+export function readRotation(filesDir: string): RotationState | null {
+  let v: unknown;
+  try {
+    v = JSON.parse(fs.readFileSync(rotationFile(filesDir), "utf-8"));
+  } catch {
+    return null;
+  }
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  const o = v as Record<string, unknown>;
+  const s: RotationState = {
+    compactions: count(o.compactions),
+    after: count(o.after),
+  };
+  if (typeof o.conversation === "string") s.conversation = o.conversation;
+  if (typeof o.lastCompactAt === "string") s.lastCompactAt = o.lastCompactAt;
+  if (typeof o.lastTrigger === "string") s.lastTrigger = o.lastTrigger;
+  if (typeof o.pendingTrigger === "string") s.pendingTrigger = o.pendingTrigger;
+  if (o.due === "compactions" || o.due === "pr-merged") s.due = o.due;
+  if (typeof o.dueAt === "string") s.dueAt = o.dueAt;
+  return s;
+}
+
+export function writeRotation(filesDir: string, s: RotationState): void {
+  writePrivate(rotationFile(filesDir), JSON.stringify(s, null, 2) + "\n");
+}
+
+/**
+ * A launch's rotation state. A new conversation starts at 0. A resume of
+ * the same one keeps its count and takes the current `after`.
+ */
+export function launchRotation(
+  filesDir: string,
+  conversation: string | undefined,
+  after: number,
+): RotationState {
+  const prev = readRotation(filesDir);
+  const same =
+    prev && conversation !== undefined && prev.conversation === conversation;
+  const s: RotationState = same
+    ? { ...prev, after }
+    : {
+        ...(conversation !== undefined ? { conversation } : {}),
+        compactions: 0,
+        after,
+      };
+  if (after === 0) {
+    delete s.due;
+    delete s.dueAt;
+  }
+  writeRotation(filesDir, s);
+  return s;
+}
+
+/**
+ * One compaction that happened (SessionStart with source "compact"; never
+ * PreCompact, which runs even when nothing is compacted). `input` is the
+ * hook input: `session_id` and `trigger` (manual, auto) are read when present.
+ * A different conversation than the one counted starts the count again.
+ */
+export function noteCompaction(
+  filesDir: string,
+  input: unknown,
+  after: number,
+  now: Date = new Date(),
+): RotationState {
+  const i = (input && typeof input === "object" ? input : {}) as Record<
+    string,
+    unknown
+  >;
+  const conversation =
+    typeof i.session_id === "string" && i.session_id ? i.session_id : undefined;
+  const prev = readRotation(filesDir);
+  const fresh =
+    !prev ||
+    (conversation !== undefined &&
+      prev.conversation !== undefined &&
+      prev.conversation !== conversation);
+  const s: RotationState = fresh
+    ? { compactions: 0, after }
+    : { ...prev, after };
+  if (conversation !== undefined) s.conversation = conversation;
+  s.compactions += 1;
+  s.lastCompactAt = now.toISOString();
+  const trigger =
+    typeof i.trigger === "string"
+      ? i.trigger
+      : fresh
+        ? undefined
+        : prev?.pendingTrigger;
+  if (trigger) s.lastTrigger = trigger.slice(0, 20);
+  delete s.pendingTrigger;
+  if (after > 0 && s.compactions >= after && !s.due) {
+    s.due = "compactions";
+    s.dueAt = now.toISOString();
+  }
+  writeRotation(filesDir, s);
+  return s;
+}
+
+/**
+ * PreCompact: keep its trigger (manual, auto) for the count. Nothing is
+ * counted; a state for another conversation is left alone.
+ */
+export function notePendingCompaction(
+  filesDir: string,
+  conversation: string | undefined,
+  trigger: unknown,
+  after: number,
+): void {
+  if (typeof trigger !== "string") return;
+  const prev = readRotation(filesDir);
+  if (prev?.conversation && conversation && prev.conversation !== conversation)
+    return;
+  writeRotation(filesDir, {
+    ...(prev ?? { compactions: 0, after }),
+    ...(conversation ? { conversation } : {}),
+    pendingTrigger: trigger.slice(0, 20),
+  });
+}
+
+/** Mark a rotation due (its pull request merged), when the agent rotates. */
+export function markDue(
+  filesDir: string,
+  reason: RotateReason,
+  conversation?: string,
+  now: Date = new Date(),
+): boolean {
+  const s = readRotation(filesDir);
+  if (!s || s.after === 0 || s.due) return false;
+  if (conversation && s.conversation && s.conversation !== conversation)
+    return false;
+  writeRotation(filesDir, { ...s, due: reason, dueAt: now.toISOString() });
+  return true;
+}
+
+/** Whether the state says a rotation is due, for this conversation. */
+export function dueFor(
+  s: RotationState | null,
+  conversation?: string,
+): RotateReason | undefined {
+  if (!s || s.after === 0) return undefined;
+  if (conversation && s.conversation && s.conversation !== conversation)
+    return undefined;
+  if (s.due) return s.due;
+  return s.compactions >= s.after ? "compactions" : undefined;
+}
+
+export type HandoffStatus = "ok" | "missing" | "invalid";
+
+/** handoff.md in `filesDir`: missing, or checked. */
+export function readHandoff(filesDir: string): {
+  status: HandoffStatus;
+  text?: string;
+  problems: string[];
+} {
+  let text: string;
+  try {
+    text = fs.readFileSync(handoffFile(filesDir), "utf-8");
+  } catch {
+    return { status: "missing", problems: [] };
+  }
+  const r = checkHandoff(text);
+  return { status: r.ok ? "ok" : "invalid", text, problems: r.problems };
+}
+
+/** An agent's rotation, as the Agents page and the CLI show it. */
+export interface RotationInfo {
+  /** Why it rotates, when a trigger fired. */
+  due?: RotateReason;
+  compactions: number;
+  /** 0: this agent never rotates. */
+  after: number;
+  handoff: HandoffStatus;
+  /** What is wrong with handoff.md, when it is invalid. */
+  problems?: string[];
+  /** Due and handoff.md passes: Relaunch from handoff, not Resume. */
+  ready: boolean;
+}
+
+/**
+ * Agent `rec`'s rotation: null when it has no rotation state for its
+ * current conversation (it never ran under 0.4.9, or the state is stale).
+ */
+export function rotationInfo(
+  stateDir: string,
+  rec: AgentRecord,
+): RotationInfo | null {
+  const files = agentFilesDir(stateDir, rec.id);
+  const s = readRotation(files);
+  if (!s) return null;
+  if (s.conversation && rec.resumeToken && s.conversation !== rec.resumeToken)
+    return null;
+  const due =
+    dueFor(s) ??
+    (s.after > 0 && rec.outcome?.prMerged ? "pr-merged" : undefined);
+  const h = due
+    ? readHandoff(files)
+    : { status: "missing" as const, problems: [] };
+  return {
+    ...(due ? { due } : {}),
+    compactions: s.compactions,
+    after: s.after,
+    handoff: h.status,
+    ...(h.status === "invalid" ? { problems: h.problems } : {}),
+    ready: Boolean(due) && h.status === "ok",
+  };
+}
+
+/**
+ * Move handoff.md aside (handoffs/<tag>.md) once Den relaunched from it, so
+ * the next rotation needs a new one. Returns where it went.
+ */
+export function archiveHandoff(filesDir: string, tag: string): string {
+  const dir = path.join(filesDir, HANDOFFS_DIR);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const safe = tag.replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 80);
+  const to = path.join(dir, `${safe}.md`);
+  fs.renameSync(handoffFile(filesDir), to);
+  return to;
+}
+
+/** Why, in words: "3 compactions", "PR merged". */
+export function reasonText(reason: RotateReason, compactions: number): string {
+  return reason === "pr-merged"
+    ? "PR merged"
+    : `${compactions} ${compactions === 1 ? "compaction" : "compactions"}`;
+}
+
+/** What the hooks tell a session whose rotation is due. */
+export function rotationInstruction(
+  filesDir: string,
+  reason: RotateReason,
+  compactions: number,
+): string {
+  const why =
+    reason === "pr-merged"
+      ? "its pull request merged"
+      : `it has compacted ${compactions} times`;
+  return [
+    `Den: this session is done, because ${why} (session rotation).`,
+    `Write your handoff now, to ${handoffFile(filesDir)}, with these headings, each filled in:`,
+    "## Objective, ## State, ## Open items, ## How to QA, ## Next step.",
+    "Write plainly and explain every ID. Then end your turn.",
+    "Den relaunches your role from it in a fresh conversation.",
+  ].join("\n");
+}
+
+/** The first prompt of a session relaunched from `handoff`. */
+export function handoffPrompt(
+  handoff: string,
+  reason: RotateReason,
+  compactions: number,
+): string {
+  return [
+    `Den relaunched you from the handoff your last session wrote. That session ended after ${reasonText(reason, compactions)} (session rotation).`,
+    "Read it, then carry on from its Next step.",
+    "",
+    handoff.trim(),
+  ].join("\n");
+}

package/src/shared/agents/runtime.ts

@@ -89,6 +89,16 @@ export interface LaunchInput {
   resumeToken?: string;
   /** The CLI detect found (a setting, the login PATH, …); else searched again. */
   bin?: string;
+  /**
+   * Session rotation (den#4): the compactions after which this agent's
+   * session rotates (0: never). Den's hooks count them. Default 3.
+   */
+  rotateAfter?: number;
+  /**
+   * The new conversation's first prompt (a relaunch from handoff.md).
+   * Only a runtime with `firstPrompt: true` is given one.
+   */
+  firstPrompt?: string;
 }
 
 export interface LaunchOutput {
@@ -126,10 +136,27 @@ export interface Runtime {
    */
   find?: RuntimeFind;
   detect(env?: NodeJS.ProcessEnv, opts?: DetectOptions): RuntimeDetect;
+  /**
+   * It can start a conversation with a first prompt (LaunchInput
+   * firstPrompt): Relaunch from handoff needs it (den#4).
+   */
+  firstPrompt?: boolean;
   /** Throws LaunchError when this persona or this machine can't run it. */
   launch(input: LaunchInput): LaunchOutput;
   /** A new run that continues the last one; null when there is nothing to resume. */
   resume?(input: ResumeInput): Omit<LaunchOutput, "resumeToken"> | null;
+  /**
+   * Whether the runtime has a conversation for `token` on this machine
+   * (den-claude: its transcript file). Only ever a fast path: false may
+   * just mean it isn't written yet.
+   */
+  conversationExists?(token: string, env?: NodeJS.ProcessEnv): boolean;
+  /**
+   * What the runtime prints when it exits at once (0.4.8): `noConversation`
+   * when a resume finds nothing to continue, `idInUse` when a new
+   * conversation's id is taken. Den then tries the other way, once.
+   */
+  launchFailures?: { noConversation?: RegExp; idInUse?: RegExp };
   /** Where permission prompts surface (Q-AG-2). */
   approvals?: "terminal" | "hook";
   /**

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";
@@ -391,6 +392,11 @@ export interface UserConfig {
     runtimes?: Record<string, { bin?: unknown } | null>;
     /** More runtime catalog entries (AG-0.5, agents/catalog.ts). */
     runtime_catalog?: unknown;
+    /**
+     * AG-14.1b: forget stopped and exited agents after this long: never
+     * (the default), 1d or 7d. Interrupted agents are never forgotten.
+     */
+    remove_stopped_after?: unknown;
   };
   /**
    * The web server's per-machine keys (src/shared/web-session.ts
@@ -465,6 +471,29 @@ export function configuredRuntimeCatalog(
   );
 }
 
+/** The values `agents.remove_stopped_after` takes, in days (AG-14.1b). */
+export const REMOVE_STOPPED_AFTER: Readonly<Record<string, number>> = {
+  never: 0,
+  "1d": 1,
+  "7d": 7,
+};
+
+/**
+ * user.yml's `agents.remove_stopped_after`, in days (0: never, the
+ * default). Throws naming the key when it is none of never, 1d, 7d.
+ */
+export function configuredRemoveStoppedAfter(
+  read: () => UserConfig = readUserConfig,
+): number {
+  const v = read().agents?.remove_stopped_after;
+  if (v === undefined || v === null) return 0;
+  if (typeof v === "string" && Object.hasOwn(REMOVE_STOPPED_AFTER, v))
+    return REMOVE_STOPPED_AFTER[v];
+  throw new Error(
+    `agents.remove_stopped_after (${path.basename(USER_CONFIG_PATH)}): must be never, 1d or 7d (got ${JSON.stringify(v)})`,
+  );
+}
+
 /**
  * Set (a path) or clear (null) `agents.runtimes.<id>.bin` in user.yml,
  * keeping everything else there. The caller checks the path first.
@@ -773,6 +802,8 @@ export const MCP_ACTIONS = [
   "service_restart",
   "workspace_sync",
   "run_tests",
+  // AG-14.4: resume another agent of its workspace (or a granted one).
+  "agent_resume",
 ] as const;
 export type McpAction = (typeof MCP_ACTIONS)[number];
 
@@ -849,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
@@ -872,6 +910,7 @@ export const AGENTS_RESERVED_KEYS = [
   "persona_packs",
   "runtime_catalog",
   "default_pack",
+  "rotate",
 ];
 
 /** One agent's own block, `agents.<id>`. */
@@ -893,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. */
@@ -955,6 +1025,7 @@ export function readAgentsConfig(
       raw.runtime_catalog,
       "agents.runtime_catalog",
     ),
+    rotate: rotateBlock(raw.rotate),
   };
   const max = raw.max_concurrent;
   if (max !== undefined) {
@@ -988,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/plugins/manifest.ts

@@ -58,6 +58,9 @@ export const KIND_TIERS: Readonly<Record<string, PluginTier>> = {
   secrets: "server",
   identity: "server",
   "health-source": "server",
+  // den#6: reads a runtime's own transcripts on this machine, for tokens
+  // and outcomes per agent; never sends them anywhere.
+  usage: "server",
 };
 
 export interface PluginProvide {

package/src/shared/usage/paths.ts

@@ -0,0 +1,16 @@
+/**
+ * Where Claude Code keeps its transcripts. No registration here, so the
+ * den-claude runtime can ask (conversationExists) without loading the
+ * usage sources (sources.ts registers one when it loads).
+ */
+import * as os from "os";
+import * as path from "path";
+
+/** Claude Code's transcripts: $CLAUDE_CONFIG_DIR/projects, else ~/.claude/projects. */
+export function claudeProjectsDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const base =
+    env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), ".claude");
+  return path.join(base, "projects");
+}