@monster-orange/den 0.4.7 → 0.4.9

package/src/shared/agents/guardrails/hooks.json

@@ -22,6 +22,29 @@
           }
         ]
       }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{rotation}",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{rotation}",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/src/shared/agents/guardrails/instructions.md

@@ -37,3 +37,26 @@ a numbered yes/no question is sent back to you to fix.
 Write "Decisions: none" when there are none, and "URL: none" (with a short
 reason) when the work has no page to open. Every message you end a turn
 with is read by a person, hand-back or not: explain each ID in it.
+
+### When your session rotates
+
+A session ends when its pull request merges, or after a few compactions
+(three unless your team set another number). Den tells you when that
+happens. Then write a handoff to the file Den names (`handoff.md` in your
+agent files folder) and end your turn. Den checks it, and relaunches your
+role from it in a fresh conversation. Use these headings, each filled in:
+
+```
+## Objective
+<what the work is for, in a sentence or two>
+## State
+<what is done, and where it is: branch, pull request, files>
+## Open items
+<what is left, one per line; or none>
+## How to QA
+<the steps to see it working>
+## Next step
+<the one thing to do first>
+```
+
+Write it plainly. Explain every ID in it, as in a hand-back.

package/src/shared/agents/guardrails/rotation-hook.ts

@@ -0,0 +1,127 @@
+/**
+ * Den's session-rotation hook for Claude Code sessions it launches
+ * (den#4). One script for two events, run with the agent's own files dir
+ * and its limit:
+ *
+ *   rotation-hook.ts --files <agent files dir> --after <n>   (0: never rotates)
+ *
+ * Hook contract (https://code.claude.com/docs/en/hooks):
+ *   - PreCompact: JSON on stdin with the common fields (`session_id`,
+ *     `transcript_path`, `cwd`, `hook_event_name`) and `trigger` (manual or
+ *     auto) and `custom_instructions`. Exit 0's stdout becomes instructions
+ *     for the compaction summary. It runs before Claude Code decides to
+ *     compact ("Not enough messages to compact" still runs it), so it never
+ *     counts. When this compaction would make a rotation due, its stdout
+ *     asks the summary to keep the instruction to write the handoff.
+ *   - SessionStart, with `source` "compact" (after a compaction that
+ *     happened) or "resume". "compact" counts the compaction in
+ *     rotation.json (rotation.ts). While a rotation is due, it prints
+ *     `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}`,
+ *     which Claude Code adds to the context: write handoff.md, then end
+ *     the turn.
+ *
+ * The parser is tolerant: a field it doesn't find is left out, never an
+ * error. Any error lets Claude Code carry on (exit 0, nothing printed):
+ * the hook never blocks a compaction.
+ */
+import {
+  dueFor,
+  noteCompaction,
+  notePendingCompaction,
+  readHandoff,
+  readRotation,
+  rotationInstruction,
+} from "../rotation.js";
+
+export interface RotationHookArgs {
+  files: string;
+  after: number;
+}
+
+/** `--files <dir> --after <n>`; null when either is missing. */
+export function parseHookArgs(
+  argv: readonly string[],
+): RotationHookArgs | null {
+  const at = (flag: string) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const files = at("--files");
+  const after = Number(at("--after") ?? "");
+  if (!files || !Number.isInteger(after) || after < 0) return null;
+  return { files, after };
+}
+
+/** The hook's stdout for one input ("" prints nothing). */
+export function rotationHookOutput(
+  input: unknown,
+  args: RotationHookArgs,
+  now: Date = new Date(),
+): string {
+  if (!input || typeof input !== "object") return "";
+  const i = input as Record<string, unknown>;
+  const event = i.hook_event_name;
+  const conversation =
+    typeof i.session_id === "string" && i.session_id ? i.session_id : undefined;
+  if (event === "PreCompact" || (event === undefined && "trigger" in i)) {
+    // Not counted here: the compaction may not happen.
+    const prev = readRotation(args.files);
+    notePendingCompaction(args.files, conversation, i.trigger, args.after);
+    const counted =
+      prev &&
+      (!conversation ||
+        !prev.conversation ||
+        prev.conversation === conversation)
+        ? prev
+        : null;
+    const next = (counted?.compactions ?? 0) + 1;
+    const due =
+      dueFor(counted, conversation) ??
+      (args.after > 0 && next >= args.after ? "compactions" : undefined);
+    if (!due) return "";
+    return [
+      "Keep this instruction, word for word, at the top of the summary:",
+      rotationInstruction(
+        args.files,
+        due,
+        Math.max(next, counted?.compactions ?? 0),
+      ),
+    ].join("\n");
+  }
+  if (event === "SessionStart" || (event === undefined && "source" in i)) {
+    if (i.source !== "compact" && i.source !== "resume") return "";
+    const s =
+      i.source === "compact"
+        ? noteCompaction(args.files, i, args.after, now)
+        : readRotation(args.files);
+    const due = dueFor(s, conversation);
+    if (!due || readHandoff(args.files).status === "ok") return "";
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: rotationInstruction(args.files, due, s!.compactions),
+      },
+    });
+  }
+  return "";
+}
+
+async function main(): Promise<void> {
+  const args = parseHookArgs(process.argv.slice(2));
+  let text = "";
+  for await (const chunk of process.stdin) text += String(chunk);
+  if (!args) return;
+  let out = "";
+  try {
+    out = rotationHookOutput(JSON.parse(text), args);
+  } catch {
+    out = "";
+  }
+  if (out) process.stdout.write(`${out}\n`);
+}
+
+if (process.argv[1] && /rotation-hook\.[jt]s$/.test(process.argv[1]))
+  main().then(
+    () => process.exit(0),
+    () => process.exit(0),
+  );

package/src/shared/agents/guardrails/stop-hook.ts

@@ -13,17 +13,63 @@
  * When Claude is already continuing because of a stop hook
  * (stop_hook_active), it lets the turn end, so it never loops. Any error
  * lets the turn end too.
+ *
+ * Session rotation (den#4): run with `--files <agent files dir> --after
+ * <n>`, while a rotation is due (rotation.ts) and handoff.md is missing or
+ * fails the handoff check, it blocks once with what to write. Once the
+ * handoff passes, the turn ends as usual.
  */
 import { bareIds, checkHandback, looksLikeHandback } from "../handback.js";
+import {
+  dueFor,
+  readHandoff,
+  readRotation,
+  rotationInstruction,
+} from "../rotation.js";
+import { parseHookArgs, type RotationHookArgs } from "./rotation-hook.js";
+
+/** A due rotation's block, or "" (no rotation due, or the handoff passes). */
+function rotationBlock(
+  input: { session_id?: unknown },
+  args: RotationHookArgs,
+): string {
+  const s = readRotation(args.files);
+  const conversation =
+    typeof input.session_id === "string" ? input.session_id : undefined;
+  const due = dueFor(s, conversation);
+  if (!due) return "";
+  const h = readHandoff(args.files);
+  if (h.status === "ok") return "";
+  return JSON.stringify({
+    decision: "block",
+    reason: [
+      rotationInstruction(args.files, due, s!.compactions),
+      ...(h.status === "invalid"
+        ? [
+            "Den checked the handoff there and it is not ready. Fix these:",
+            ...h.problems.map((p) => `- ${p}`),
+          ]
+        : []),
+    ].join("\n"),
+  });
+}
 
 /** The hook's stdout for one Stop input ("" lets the turn end). */
-export function stopDecision(input: unknown): string {
+export function stopDecision(
+  input: unknown,
+  rotation?: RotationHookArgs | null,
+): string {
   if (!input || typeof input !== "object") return "";
   const i = input as {
     stop_hook_active?: unknown;
     last_assistant_message?: unknown;
+    session_id?: unknown;
   };
   if (i.stop_hook_active === true) return "";
+  if (rotation) {
+    const block = rotationBlock(i, rotation);
+    if (block) return block;
+  }
   const msg = i.last_assistant_message;
   if (typeof msg !== "string") return "";
   // A hand-back is checked whole. Any other final message is what the
@@ -52,7 +98,7 @@ async function main(): Promise<void> {
   for await (const chunk of process.stdin) text += String(chunk);
   let out = "";
   try {
-    out = stopDecision(JSON.parse(text));
+    out = stopDecision(JSON.parse(text), parseHookArgs(process.argv.slice(2)));
   } catch {
     out = "";
   }

package/src/shared/agents/guardrails.ts

@@ -7,10 +7,12 @@
  *                    role prompt (personas.ts rolePrompt), so every runtime
  *                    gets them.
  *   hooks.json       a Claude Code settings fragment: a PreToolUse hook on
- *                    Bash and Read (pretooluse.mjs) and a Stop hook
- *                    (stop-hook.ts, the hand-back check). den-claude merges
- *                    it into the agent's own --settings file; Den never
- *                    writes the user's ~/.claude.
+ *                    Bash and Read (pretooluse.mjs), a Stop hook
+ *                    (stop-hook.ts, the hand-back check), and PreCompact
+ *                    and SessionStart (compact, resume) hooks
+ *                    (rotation-hook.ts, session rotation: den#4). den-claude
+ *                    merges it into the agent's own --settings file; Den
+ *                    never writes the user's ~/.claude.
  *
  * On by default for Den's default pack, off for a distribution's packs.
  * A distribution turns them off or on per pack (agents.default_pack, a
@@ -68,27 +70,56 @@ export interface HookCommands {
   pretooluse: string;
   /** The Stop hook's command line. */
   stop: string;
+  /** The PreCompact and SessionStart hooks' command line (den#4). */
+  rotation: string;
+}
+
+/**
+ * Where an agent's rotation state lives and its limit (den#4): its files
+ * dir, and the compactions after which it rotates (0: never).
+ */
+export interface RotationArgs {
+  files: string;
+  after: number;
 }
 
 /** The command lines Den's hooks run: this node, Den's own scripts. */
 export function hookCommands(
   dir: string = GUARDRAILS_DIR,
   node: string = process.execPath,
+  rotation?: RotationArgs,
 ): HookCommands {
+  const more = (c: EngineCommand): EngineCommand =>
+    rotation
+      ? {
+          command: c.command,
+          args: [
+            ...c.args,
+            "--files",
+            rotation.files,
+            "--after",
+            String(rotation.after),
+          ],
+        }
+      : c;
   return {
     pretooluse: commandLine({
       command: node,
       args: [path.join(dir, "pretooluse.mjs")],
     }),
     stop: commandLine(
-      scriptEntrypoint("src/shared/agents/guardrails/stop-hook.ts"),
+      more(scriptEntrypoint("src/shared/agents/guardrails/stop-hook.ts")),
+    ),
+    rotation: commandLine(
+      more(scriptEntrypoint("src/shared/agents/guardrails/rotation-hook.ts")),
     ),
   };
 }
 
 /**
  * The `hooks` block of the agent's settings file: hooks.json with each
- * `{pretooluse}` / `{stop}` placeholder replaced by its command line.
+ * `{pretooluse}` / `{stop}` / `{rotation}` placeholder replaced by its
+ * command line.
  */
 export function guardrailHooks(
   dir: string = GUARDRAILS_DIR,
@@ -100,7 +131,7 @@ export function guardrailHooks(
   const fill = (v: unknown): unknown => {
     if (typeof v === "string")
       return v.replace(
-        /\{(pretooluse|stop)\}/g,
+        /\{(pretooluse|stop|rotation)\}/g,
         (_, k: keyof HookCommands) => cmds[k],
       );
     if (Array.isArray(v)) return v.map(fill);

package/src/shared/agents/handoff.ts

@@ -0,0 +1,118 @@
+/**
+ * The handoff check (den#4, session rotation): is a handoff.md complete
+ * and plain? A session that rotates (after agents.rotate.after_compactions
+ * compactions, or once its pull request merged) writes one in its files
+ * dir; Den relaunches the role from it, in a fresh conversation whose
+ * first prompt is the handoff. `<cli> agents handoff-check <file|->` runs
+ * the check, and so does the Stop hook while a rotation is due.
+ *
+ * The template (guardrails/instructions.md):
+ *
+ *   ## Objective
+ *   <what the work is for, in a sentence or two>
+ *   ## State
+ *   <what is done and where it lives: branch, pull request, files>
+ *   ## Open items
+ *   <what is left, one per line; or none>
+ *   ## How to QA
+ *   <the steps to see it working>
+ *   ## Next step
+ *   <the one thing to do first>
+ *
+ * It rejects a handoff when:
+ *
+ * 1. A part is missing or empty. A part is a heading that is its label
+ *    (`## Open items`) or a line that starts with its label and a colon
+ *    (`Next step: open the PR`). Its content is the rest of the line and
+ *    the lines after it, up to the next part or heading.
+ * 2. It has a bare ID: the hand-back check's rule (handback.ts bareIds).
+ *    Code, links and code blocks are not scanned.
+ * 3. It is longer than HANDOFF_MAX_CHARS: it is the next session's first
+ *    prompt, so it must stay short.
+ */
+import { bareIds } from "./handback.js";
+
+export const HANDOFF_PARTS = [
+  "Objective",
+  "State",
+  "Open items",
+  "How to QA",
+  "Next step",
+] as const;
+export type HandoffPart = (typeof HANDOFF_PARTS)[number];
+
+/** The longest handoff Den passes on (it becomes a first prompt). */
+export const HANDOFF_MAX_CHARS = 20_000;
+
+export interface HandoffResult {
+  ok: boolean;
+  /** One line each, plain, naming what to fix. */
+  problems: string[];
+}
+
+const LABEL = new RegExp(
+  `^\\s*(?:[-*+]\\s+)?(#{1,6}\\s+)?(?:\\*\\*|__)?(${HANDOFF_PARTS.map((p) =>
+    p.replace(/ /g, "\\s+"),
+  ).join("|")})(?:\\*\\*|__)?\\s*(:)?(?:\\*\\*|__)?\\s*(.*)$`,
+  "i",
+);
+
+function canonical(label: string): HandoffPart {
+  const l = label.replace(/\s+/g, " ").toLowerCase();
+  return HANDOFF_PARTS.find((p) => p.toLowerCase() === l)!;
+}
+
+/** Each part's content lines, by part. */
+export function handoffParts(text: string): Map<HandoffPart, string[]> {
+  const found = new Map<HandoffPart, string[]>();
+  let cur: HandoffPart | null = null;
+  let fence = false;
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    const fenceLine = /^\s*(```|~~~)/.test(line);
+    if (fenceLine) fence = !fence;
+    const m = fence || fenceLine ? null : LABEL.exec(line);
+    // A label needs a colon, or to be the whole heading.
+    if (m && (m[3] || (m[1] && !m[4].trim()))) {
+      cur = canonical(m[2]);
+      const body = m[4].trim();
+      found.set(cur, body ? [body] : []);
+      continue;
+    }
+    if (!fence && /^\s*#{1,6}\s/.test(line)) {
+      // The document's own title, or another heading: no part's content.
+      cur = null;
+      continue;
+    }
+    if (cur && line.trim()) found.get(cur)!.push(line.trim());
+  }
+  return found;
+}
+
+/** Check a handoff. Pure: the text in, the problems out. */
+export function checkHandoff(text: string): HandoffResult {
+  const s = String(text ?? "");
+  const problems: string[] = [];
+  if (!s.trim())
+    return {
+      ok: false,
+      problems: [
+        `The handoff is empty. Write ${HANDOFF_PARTS.map((p) => `"## ${p}"`).join(", ")}, each with its part filled in.`,
+      ],
+    };
+  const found = handoffParts(s);
+  for (const part of HANDOFF_PARTS) {
+    const body = found.get(part);
+    if (body === undefined) problems.push(`Missing "## ${part}". Add it.`);
+    else if (!body.join(" ").trim())
+      problems.push(`"## ${part}" is empty. Fill it in.`);
+  }
+  if (s.length > HANDOFF_MAX_CHARS)
+    problems.push(
+      `The handoff is ${s.length} characters long. Keep it under ${HANDOFF_MAX_CHARS}: it is the next session's first prompt.`,
+    );
+  for (const id of bareIds(s))
+    problems.push(
+      `"${id}" is not explained. Say what it is, e.g. "${id} (what it is)".`,
+    );
+  return { ok: problems.length === 0, problems };
+}

package/src/shared/agents/personas.ts

@@ -13,7 +13,8 @@
  *   tools        "Read, Grep" or a list: hints, never a restriction Den applies
  *
  * Den's own keys sit beside them: `runtime` (default den-claude),
- * `standing` (starts with its workspace, §5), `context` (what to read
+ * `standing` (starts with its workspace, §5; resumes after a restart),
+ * `resume_on_restart` (AG-14.3: resumes after a restart too), `context` (what to read
  * first), `argv` (the generic runtime's template), and `permission_mode`
  * (den-claude's Claude Code permission mode; it checks the value), and
  * `den_hooks` / `den_instructions` (true or false: this persona's
@@ -45,6 +46,11 @@ export interface Persona {
   model?: string;
   /** Started with its workspace (planner, orchestrator). */
   standing: boolean;
+  /**
+   * `resume_on_restart: true` (AG-14.3): resumed on its own when Den or
+   * the machine restarted. Standing personas always are.
+   */
+  resumeOnRestart?: boolean;
   /** Tool hints. */
   tools: string[];
   /** What to read first (specs, the design system, workspace config). */
@@ -135,6 +141,9 @@ export function parsePersona(text: string, file: string): Persona | null {
   const standing = f.standing ?? false;
   if (typeof standing !== "boolean")
     throw new Error(`${file}: standing must be true or false`);
+  const resumeOnRestart = f.resume_on_restart ?? false;
+  if (typeof resumeOnRestart !== "boolean")
+    throw new Error(`${file}: resume_on_restart must be true or false`);
   let argv: string[] | undefined;
   if (f.argv !== undefined && f.argv !== null) {
     if (
@@ -166,6 +175,7 @@ export function parsePersona(text: string, file: string): Persona | null {
     ...(runtime ? { runtime } : {}),
     ...(model && model !== "inherit" ? { model } : {}),
     standing,
+    ...(resumeOnRestart ? { resumeOnRestart } : {}),
     tools: stringList(f, "tools", file),
     context: stringList(f, "context", file),
     ...(argv ? { argv } : {}),

package/src/shared/agents/records.ts

@@ -4,16 +4,23 @@
  * same agents, and so an agent outlives the session it runs in.
  *
  *   agents/<id>.json        the record (0600, its directory 0700)
- *   agent-files/<id>/       files its runtime wrote (0600): its MCP config
+ *   agent-files/<id>/       files its runtime wrote (0600): its MCP config;
+ *                           and its rotation state and handoff.md (den#4)
  *
  * A record never holds the env or the argv: the role prompt, tokens and
  * anything else a launch passes stay out of it. An agent id is unique in a
  * distribution.
+ *
+ * AG-14: a removed agent's record moves to removed-agents/<id>.json, so
+ * Undo can bring it back; restoreRecord does, and purgeRemoved forgets
+ * the ones older than the undo window. The runtime's own conversation
+ * history is never touched.
  */
 import * as fs from "fs";
 import * as path from "path";
 import { WORKSPACE_NAME_RE } from "../agent-actor.js";
 import type { SessionRef } from "../sessions/types.js";
+import type { RotationEntry } from "./rotation.js";
 
 export interface AgentRecord {
   id: string;
@@ -34,6 +41,59 @@ export interface AgentRecord {
   resumedAt?: string;
   /** The runtime's handle for resume (den-claude: the conversation id). */
   resumeToken?: string;
+  /**
+   * The runtime was launched on resumeToken at least once (0.4.8). A
+   * resume then always tries the runtime's own resume first, never a new
+   * conversation under the same id (which the runtime refuses once the
+   * conversation exists).
+   */
+  launched?: boolean;
+  /**
+   * The workspaces beyond its own its MCP served when it started
+   * (agents.<id>.grants then). A resume keeps them, never more than the
+   * config still allows (AG-14).
+   */
+  grants?: string[];
+  /** When its session was seen to end on its own (AG-14: "Exited"). */
+  endedAt?: string;
+  /** That session's exit code, when the host said it. */
+  exitCode?: number;
+  /**
+   * Set when its session was gone after Den or the machine restarted
+   * (AG-14.3: "Interrupted"); cleared by a resume or a start.
+   */
+  interruptedAt?: string;
+  /** What its run came to (den#6), filled in by `<cli> usage`. */
+  outcome?: AgentOutcome;
+  /** Its tokens, from the runtime's own transcript (den#6). */
+  usage?: AgentUsage;
+  /**
+   * Each time Den relaunched it from its handoff (den#4, session
+   * rotation), oldest first.
+   */
+  rotations?: RotationEntry[];
+}
+
+/** What an agent's run came to (den#6). Read locally; never sent. */
+export interface AgentOutcome {
+  /** The pull request it opened, when it opened one. */
+  prOpened?: string;
+  /** That pull request merged in the run. */
+  prMerged?: boolean;
+  /** The last test run it made passed (true) or failed (false). */
+  testsGreen?: boolean;
+  /** From its start to its last activity, in milliseconds. */
+  wallClockMs?: number;
+}
+
+/** An agent's token counts (den#6), summed over its transcripts. */
+export interface AgentUsage {
+  calls: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  compactions: number;
 }
 
 /** An agent id: the same rules as a workspace or session name. */
@@ -85,6 +145,67 @@ export function readRecord(stateDir: string, id: string): AgentRecord | null {
   }
 }
 
+/** Where removed records wait for Undo (AG-14.1b). */
+export function removedDir(stateDir: string): string {
+  return path.join(stateDir, "removed-agents");
+}
+
+/** How long a removed record can be brought back. */
+export const UNDO_KEEP_MS = 60 * 60 * 1000;
+
+/**
+ * Forget agent `id` (its record moves aside for Undo). True when there
+ * was one. Its files and the runtime's history stay.
+ */
+export function removeRecord(stateDir: string, id: string): boolean {
+  const from = recordFile(stateDir, id);
+  if (!fs.existsSync(from)) return false;
+  ensureDir(removedDir(stateDir));
+  const to = path.join(removedDir(stateDir), `${id}.json`);
+  fs.renameSync(from, to);
+  // Its mtime is when it was removed: purgeRemoved goes by it.
+  const now = new Date();
+  fs.utimesSync(to, now, now);
+  return true;
+}
+
+/**
+ * Bring a removed record back (Undo). False when there is none to bring
+ * back, or an agent of that id exists again.
+ */
+export function restoreRecord(stateDir: string, id: string): boolean {
+  if (!AGENT_ID_RE.test(id)) return false;
+  const from = path.join(removedDir(stateDir), `${id}.json`);
+  const to = recordFile(stateDir, id);
+  if (!fs.existsSync(from) || fs.existsSync(to)) return false;
+  ensureDir(agentsDir(stateDir));
+  fs.renameSync(from, to);
+  return true;
+}
+
+/** Forget removed records older than `keepMs` for good. */
+export function purgeRemoved(
+  stateDir: string,
+  keepMs = UNDO_KEEP_MS,
+  now = Date.now(),
+): void {
+  let names: string[];
+  try {
+    names = fs.readdirSync(removedDir(stateDir));
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    if (!n.endsWith(".json") || !AGENT_ID_RE.test(n.slice(0, -5))) continue;
+    const f = path.join(removedDir(stateDir), n);
+    try {
+      if (now - fs.statSync(f).mtimeMs > keepMs) fs.unlinkSync(f);
+    } catch {
+      /* gone already */
+    }
+  }
+}
+
 export function listRecords(stateDir: string): AgentRecord[] {
   let names: string[];
   try {