@monster-orange/den 0.4.6 → 0.4.8

package/src/shared/agents/handback.ts

@@ -0,0 +1,241 @@
+/**
+ * The hand-back check: is a hand-back to a person complete and plain?
+ * `<cli> agents handback-check <file|->` runs it, and so does the Stop hook
+ * Den gives default-pack personas (guardrails/stop-hook.ts). The template
+ * is in guardrails/instructions.md:
+ *
+ *   ## Hand-back
+ *   - URL: <the link to open>
+ *   - Machine: <the machine it runs on>
+ *   - Branch: <the branch>
+ *   - What changed: <what is different now>
+ *   - What to click: <the steps to see it>
+ *   - Decisions:
+ *     1. <a yes/no question>?
+ *
+ * It rejects a hand-back when:
+ *
+ * 1. A part is missing or empty. A part is a line that starts with its
+ *    label and a colon (`URL:`, `- **Branch:** …`) or a heading that is its
+ *    label (`### What changed`). Its content is the rest of the line and
+ *    the lines after it, up to the next part. URL must hold a link (`://`)
+ *    or say `none` (work with no page), optionally with a reason.
+ *    Decisions may say `none`.
+ * 2. It has a bare ID. An ID is `#<digits>` or 1-4 capitals, an optional
+ *    `-`, digits and an optional `.<digits>` (`R12`, `AG-14`, `KB-4.1`).
+ *    URLs, `inline code` and code blocks, and the URL and Branch parts are
+ *    not scanned: they are literal. An ID is glossed (not bare) when:
+ *      a. a parenthetical of at least two words follows it:
+ *         `#5 (the hooks issue)`;
+ *      b. a colon or dash, then at least two words, follows it:
+ *         `R12: plain writing`, `R12 - plain writing`;
+ *      c. it sits inside a parenthetical right after a word, and that
+ *         parenthetical holds no other words: `plain writing (R12)`,
+ *         `the issues (#5, #6)`;
+ *      d. or the same ID was glossed earlier in the text.
+ *    A word is a run of letters (an ID is not a word).
+ * 3. A decision isn't a numbered yes/no question. Each item under
+ *    Decisions must be numbered (`1.` or `1)`), end in `?`, not start
+ *    with a question word (what, which, how, why, when, where, who), and
+ *    not offer a choice (` or `).
+ */
+
+export const HANDBACK_PARTS = [
+  "URL",
+  "Machine",
+  "Branch",
+  "What changed",
+  "What to click",
+  "Decisions",
+] as const;
+export type HandbackPart = (typeof HANDBACK_PARTS)[number];
+
+export interface HandbackResult {
+  ok: boolean;
+  /** One line each, plain, naming what to fix. */
+  problems: string[];
+}
+
+/** The ID patterns the check looks for. */
+export const ID_PATTERNS = [/#\d+/g, /\b[A-Z]{1,4}-?\d+(?:\.\d+)?\b/g];
+
+const LABEL = new RegExp(
+  `^\\s*(?:[-*+]\\s+)?(#{1,6}\\s+)?(?:\\*\\*|__)?(${HANDBACK_PARTS.map((p) =>
+    p.replace(/ /g, "\\s+"),
+  ).join("|")})(?:\\*\\*|__)?\\s*(:)?(?:\\*\\*|__)?\\s*(.*)$`,
+  "i",
+);
+
+/** The hand-back's heading, which marks a message as one. */
+export const HANDBACK_HEADING = /^\s*#{1,6}\s*hand-?\s?back\b/im;
+
+/** Does this message present itself as a hand-back (its heading)? */
+export function looksLikeHandback(text: string): boolean {
+  return HANDBACK_HEADING.test(text);
+}
+
+interface Parts {
+  found: Map<HandbackPart, string[]>;
+  /** Line numbers (0-based) of the URL and Branch parts' content. */
+  literal: Set<number>;
+}
+
+function canonical(label: string): HandbackPart {
+  const l = label.replace(/\s+/g, " ").toLowerCase();
+  return HANDBACK_PARTS.find((p) => p.toLowerCase() === l)!;
+}
+
+function splitParts(lines: string[]): Parts {
+  const found = new Map<HandbackPart, string[]>();
+  const literal = new Set<number>();
+  let cur: HandbackPart | null = null;
+  let fence = false;
+  lines.forEach((line, n) => {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    const m = fence ? 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] : []);
+      if (cur === "URL" || cur === "Branch") literal.add(n);
+      return;
+    }
+    if (/^\s*#{1,6}\s/.test(line)) {
+      cur = null;
+      return;
+    }
+    if (!cur) return;
+    if (line.trim()) found.get(cur)!.push(line.trim());
+    if (cur === "URL" || cur === "Branch") literal.add(n);
+  });
+  return { found, literal };
+}
+
+/** Text with URLs and code replaced by spaces (offsets kept). */
+function prose(line: string): string {
+  const blank = (s: string) => " ".repeat(s.length);
+  return line
+    .replace(/`[^`]*`/g, blank)
+    .replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, blank)
+    .replace(/\bwww\.\S+/gi, blank);
+}
+
+const WORD = /[A-Za-z][A-Za-z'’]*(?:-[A-Za-z]+)*/g;
+
+/** Words in s: runs of letters, once the IDs are taken out. */
+function wordCount(s: string): number {
+  let t = s;
+  for (const re of ID_PATTERNS) t = t.replace(new RegExp(re.source, "g"), " ");
+  return (t.match(WORD) ?? []).length;
+}
+
+/** Is the ID at [start, end) in this line glossed (rules a-c)? */
+export function isGlossed(line: string, start: number, end: number): boolean {
+  const after = line.slice(end);
+  // a. "(two or more words)" right after.
+  const paren = /^\s*\(([^)]*)\)/.exec(after);
+  if (paren && wordCount(paren[1]) >= 2) return true;
+  // b. ": two words" or " - two words" right after.
+  const colon = /^\s*(?::|\s[-–—])\s*(.*)$/.exec(after);
+  if (colon && wordCount(colon[1].split(/[.;!?]/)[0]) >= 2) return true;
+  // c. inside "(…)" right after a word, the parenthetical only IDs.
+  const open = line.lastIndexOf("(", start);
+  const close = line.indexOf(")", end);
+  if (open >= 0 && close >= 0 && line.slice(open, start).indexOf(")") < 0) {
+    const inside = line.slice(open + 1, close);
+    const before = line.slice(0, open);
+    if (wordCount(inside) === 0 && /[A-Za-z][A-Za-z'’]*\s*$/.test(before))
+      return true;
+  }
+  return false;
+}
+
+/** Bare IDs in the text, in order, each once. */
+export function bareIds(
+  text: string,
+  skipLines: Set<number> = new Set(),
+): string[] {
+  const glossed = new Set<string>();
+  const bare: string[] = [];
+  let fence = false;
+  text.split(/\r?\n/).forEach((raw, n) => {
+    if (/^\s*(```|~~~)/.test(raw)) {
+      fence = !fence;
+      return;
+    }
+    if (fence || skipLines.has(n)) return;
+    const line = prose(raw);
+    const hits: { id: string; start: number; end: number }[] = [];
+    for (const re of ID_PATTERNS)
+      for (const m of line.matchAll(new RegExp(re.source, "g")))
+        hits.push({ id: m[0], start: m.index!, end: m.index! + m[0].length });
+    hits.sort((a, b) => a.start - b.start);
+    for (const h of hits) {
+      if (glossed.has(h.id)) continue;
+      if (isGlossed(line, h.start, h.end)) glossed.add(h.id);
+      else if (!bare.includes(h.id)) bare.push(h.id);
+    }
+  });
+  return bare;
+}
+
+const QUESTION_WORD = /^(what|which|how|why|when|where|who|whom|whose)\b/i;
+
+/** Problems with the Decisions part's items. */
+function decisionProblems(items: string[]): string[] {
+  if (items.length === 1 && /^(none|no decisions?|nothing)\.?$/i.test(items[0]))
+    return [];
+  if (!items.length)
+    return [
+      "Decisions is empty. List each as a numbered yes/no question, or say none.",
+    ];
+  const out: string[] = [];
+  for (const it of items) {
+    const m = /^(\d+)[.)]\s+(.*)$/.exec(it);
+    const q = (m ? m[2] : it.replace(/^[-*+]\s+/, "")).trim();
+    const show = q.length > 60 ? `${q.slice(0, 57)}...` : q;
+    if (!m)
+      out.push(`Decision "${show}" is not numbered. Number it: 1., 2., …`);
+    else if (!q.endsWith("?"))
+      out.push(`Decision "${show}" is not a question. End it with "?".`);
+    else if (QUESTION_WORD.test(q) || /\sor\s/i.test(q))
+      out.push(
+        `Decision "${show}" is not a yes/no question. Ask it so yes or no answers it.`,
+      );
+  }
+  return out;
+}
+
+/** Check a hand-back. Pure: the text in, the problems out. */
+export function checkHandback(text: string): HandbackResult {
+  const lines = String(text ?? "").split(/\r?\n/);
+  const { found, literal } = splitParts(lines);
+  const problems: string[] = [];
+  for (const part of HANDBACK_PARTS) {
+    const body = found.get(part);
+    if (body === undefined) {
+      problems.push(`Missing "${part}:". Add it.`);
+      continue;
+    }
+    if (part === "Decisions") {
+      problems.push(...decisionProblems(body));
+      continue;
+    }
+    if (!body.join(" ").trim())
+      problems.push(`"${part}:" is empty. Fill it in.`);
+    else if (
+      part === "URL" &&
+      !body.join(" ").includes("://") &&
+      !/^\s*none\b/i.test(body.join(" "))
+    )
+      problems.push(
+        `"URL:" has no link. Give the full address, with http:// or https://, or say none if this work has no page.`,
+      );
+  }
+  for (const id of bareIds(lines.join("\n"), literal))
+    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,9 +13,12 @@
  *   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). Any other key (a
+ * (den-claude's Claude Code permission mode; it checks the value), and
+ * `den_hooks` / `den_instructions` (true or false: this persona's
+ * guardrails, guardrails.ts, over its pack's). Any other key (a
  * Claude Code `color`) is ignored. A file without front matter (a pack's
  * README) is not a persona.
  */
@@ -24,6 +27,12 @@ import * as path from "path";
 import * as yaml from "yaml";
 import { WORKSPACE_NAME_RE } from "../agent-actor.js";
 import { enginePath } from "../engine.js";
+import {
+  DEFAULT_PACK_GUARDRAILS,
+  PACK_GUARDRAILS,
+  sharedInstructions,
+  type Guardrails,
+} from "./guardrails.js";
 
 export interface Persona {
   id: string;
@@ -37,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). */
@@ -45,6 +59,13 @@ export interface Persona {
   argv?: string[];
   /** `permission_mode`: the runtime's permission mode (den-claude checks it). */
   permissionMode?: string;
+  /** `den_hooks` / `den_instructions` as its front matter sets them. */
+  guardrailsSet?: Partial<Guardrails>;
+  /**
+   * Den's guardrails for it (guardrails.ts), resolved by loadPersonas from
+   * its pack and its own front matter. Absent: none.
+   */
+  guardrails?: Guardrails;
   /** The file it came from. */
   source: string;
 }
@@ -120,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 (
@@ -133,6 +157,17 @@ export function parsePersona(text: string, file: string): Persona | null {
   const model = optString(f, "model", file);
   const runtime = optString(f, "runtime", file);
   const permissionMode = optString(f, "permission_mode", file);
+  const guardrailsSet: Partial<Guardrails> = {};
+  for (const [key, k] of [
+    ["den_hooks", "hooks"],
+    ["den_instructions", "instructions"],
+  ] as const) {
+    const v = f[key];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== "boolean")
+      throw new Error(`${file}: ${key} must be true or false`);
+    guardrailsSet[k] = v;
+  }
   return {
     id,
     role: optString(f, "role", file) ?? optString(f, "description", file) ?? "",
@@ -140,10 +175,12 @@ 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 } : {}),
     ...(permissionMode ? { permissionMode } : {}),
+    ...(Object.keys(guardrailsSet).length ? { guardrailsSet } : {}),
     source: file,
   };
 }
@@ -183,23 +220,42 @@ export function resolvePackDirs(packs: string[], distRoot: string): string[] {
   });
 }
 
+/** Each pack's guardrails (guardrails.ts), as agents: configures them. */
+export interface PackGuardrails {
+  /** Den's default pack (default: both on). */
+  defaultPack?: Partial<Guardrails>;
+  /** Each of packDirs, in order (default: both off). */
+  packs?: (Partial<Guardrails> | undefined)[];
+}
+
 /**
  * Every persona: Den's default pack, then each pack in order. A later
- * pack's persona replaces an earlier one of the same id.
+ * pack's persona replaces an earlier one of the same id. Each gets its
+ * guardrails: its own front matter's, else its pack's.
  */
 export function loadPersonas(
   packDirs: string[],
   defaultPack: string = DEFAULT_PACK_DIR,
+  guardrails: PackGuardrails = {},
 ): Map<string, Persona> {
   const all = new Map<string, Persona>();
-  for (const dir of [defaultPack, ...packDirs])
-    for (const p of readPack(dir)) all.set(p.id, p);
+  const packs: [string, Guardrails][] = [
+    [defaultPack, { ...DEFAULT_PACK_GUARDRAILS, ...guardrails.defaultPack }],
+    ...packDirs.map((dir, i): [string, Guardrails] => [
+      dir,
+      { ...PACK_GUARDRAILS, ...guardrails.packs?.[i] },
+    ]),
+  ];
+  for (const [dir, g] of packs)
+    for (const p of readPack(dir))
+      all.set(p.id, { ...p, guardrails: { ...g, ...p.guardrailsSet } });
   return all;
 }
 
 /**
  * The role prompt as an agent gets it: who and where it is, what to read
- * first, then the persona's own prompt. Runtime-neutral; a runtime only
+ * first, the persona's own prompt, then Den's shared instructions
+ * (guardrails/instructions.md) when its guardrails include them. Runtime-neutral; a runtime only
  * chooses how to pass it in.
  */
 export function rolePrompt(
@@ -214,5 +270,8 @@ export function rolePrompt(
   ];
   if (persona.context.length)
     lines.push(`Read first: ${persona.context.join("; ")}.`);
-  return `${lines.join("\n")}\n\n${persona.prompt}`;
+  const shared = persona.guardrails?.instructions
+    ? `\n\n${sharedInstructions()}`
+    : "";
+  return `${lines.join("\n")}\n\n${persona.prompt}${shared}`;
 }

package/src/shared/agents/records.ts

@@ -9,6 +9,11 @@
  * 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";
@@ -34,6 +39,54 @@ 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;
+}
+
+/** 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 +138,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 {

package/src/shared/agents/runtime.ts

@@ -130,6 +130,18 @@ export interface Runtime {
   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";
   /**