@monster-orange/den 0.4.6 → 0.4.8

package/src/shared/den-config.ts

@@ -19,6 +19,7 @@ import type { OrgConfig } from "./org.js";
 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 type { TestAccountsConfig } from "./auth/test-accounts.js";
 
 import { product } from "./product.js";
@@ -390,6 +391,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
@@ -464,6 +470,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.
@@ -772,6 +801,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];
 
@@ -833,9 +864,16 @@ export interface AgentsConfig {
   /**
    * Persona packs (AG-2a): directories of persona files, relative to the
    * distribution root. Den's default pack is always read first; a pack's
-   * persona replaces one of the same id.
+   * persona replaces one of the same id. An entry may be a mapping,
+   * `{ path, hooks, instructions }`, to turn Den's guardrails on for that
+   * pack (agents/guardrails.ts; off for a distribution's pack by default).
+   */
+  persona_packs?: (string | PersonaPackConfig)[];
+  /**
+   * Den's default pack's guardrails, `{ hooks, instructions }` (both on
+   * by default): false turns that one off for every persona of the pack.
    */
-  persona_packs?: string[];
+  default_pack?: Partial<Guardrails>;
   /**
    * More runtime catalog entries (AG-0.5, agents/catalog.ts): a vendor CLI
    * Den doesn't ship, with the same fields and checks as a built-in one.
@@ -849,6 +887,13 @@ export interface AgentsConfig {
   [agentId: string]: unknown;
 }
 
+/** A `persona_packs` entry written as a mapping. */
+export interface PersonaPackConfig {
+  path: string;
+  hooks?: boolean;
+  instructions?: boolean;
+}
+
 export const DEFAULT_AGENTS_MAX_CONCURRENT = 4;
 
 /** The keys of `agents:` that are not an agent id. */
@@ -856,6 +901,7 @@ export const AGENTS_RESERVED_KEYS = [
   "max_concurrent",
   "persona_packs",
   "runtime_catalog",
+  "default_pack",
 ];
 
 /** One agent's own block, `agents.<id>`. */
@@ -869,6 +915,10 @@ export interface ResolvedAgentsConfig {
   maxConcurrent: number;
   /** As configured (relative to the distribution root). */
   personaPacks: string[];
+  /** Each pack's guardrails as configured, by index of personaPacks. */
+  packGuardrails?: (Partial<Guardrails> | undefined)[];
+  /** agents.default_pack as configured. */
+  defaultPackGuardrails?: Partial<Guardrails>;
   /** `agents.<id>` blocks, by agent id. */
   agents: Record<string, AgentGrantsConfig>;
   /** The distribution's runtime catalog entries (AG-0.5), checked. */
@@ -881,6 +931,36 @@ const AGENT_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const isMapping = (v: unknown): v is Record<string, unknown> =>
   v !== null && typeof v === "object" && !Array.isArray(v);
 
+/**
+ * `{ hooks, instructions }` (agents.default_pack, or a persona_packs
+ * mapping with its `path`): each true or false; any other key throws.
+ */
+function guardrailsBlock(
+  v: unknown,
+  where: string,
+  withPath: boolean,
+): Partial<Guardrails> {
+  if (v === undefined || v === null) return {};
+  if (!isMapping(v))
+    throw new Error(
+      `${where}: must be a mapping ({ hooks: true|false, instructions: true|false })`,
+    );
+  const out: Partial<Guardrails> = {};
+  for (const [k, x] of Object.entries(v)) {
+    if (withPath && k === "path") continue;
+    if (k !== "hooks" && k !== "instructions")
+      throw new Error(
+        `${where}.${k}: unknown key (takes ${withPath ? "path, " : ""}hooks, instructions)`,
+      );
+    if (typeof x !== "boolean")
+      throw new Error(
+        `${where}.${k}: must be true or false (got ${JSON.stringify(x)})`,
+      );
+    out[k] = x;
+  }
+  return out;
+}
+
 /**
  * The effective agents config. Anything malformed throws, naming the key:
  * a typo must not lift the cap, drop a pack or widen a grant.
@@ -894,6 +974,12 @@ export function readAgentsConfig(
   const out: ResolvedAgentsConfig = {
     maxConcurrent: DEFAULT_AGENTS_MAX_CONCURRENT,
     personaPacks: [],
+    packGuardrails: [],
+    defaultPackGuardrails: guardrailsBlock(
+      raw.default_pack,
+      "agents.default_pack",
+      false,
+    ),
     agents: {},
     runtimeCatalog: validateCatalog(
       raw.runtime_catalog,
@@ -915,19 +1001,24 @@ export function readAgentsConfig(
         `agents.persona_packs: must be a list of paths (got ${JSON.stringify(packs)})`,
       );
     packs.forEach((p, i) => {
-      if (typeof p !== "string" || !p.trim())
+      const where = `agents.persona_packs[${i}]`;
+      const dir = isMapping(p) ? p.path : p;
+      if (typeof dir !== "string" || !dir.trim())
         throw new Error(
-          `agents.persona_packs[${i}]: must be a non-empty path (got ${JSON.stringify(p)})`,
+          `${where}: must be a non-empty path or { path, hooks, instructions } (got ${JSON.stringify(p)})`,
         );
+      out.personaPacks.push(dir);
+      out.packGuardrails!.push(
+        isMapping(p) ? guardrailsBlock(p, where, true) : undefined,
+      );
     });
-    out.personaPacks = packs as string[];
   }
   for (const [id, block] of Object.entries(raw)) {
     if (AGENTS_RESERVED_KEYS.includes(id)) continue;
     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, ` +
+        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, default_pack, ` +
           `or an agent id mapping to { grants: [...] })`,
       );
     for (const k of Object.keys(block))

package/src/shared/dev-metrics/emit.ts

@@ -19,6 +19,12 @@
  * else). A DSN, in the env or a synced dev-metrics.config, is where to send
  * once opted in; on its own it never sends.
  *
+ * Each line also has `cwd` (den#5): where the command ran, relative to the
+ * distribution root ("." for the root itself), or "outside" for anywhere
+ * else, never an absolute or home path. `<cli> doctor` reads it to spot
+ * polling loops (polling.ts). Like every field, it is sent only when opted
+ * in; the envelope format is unchanged.
+ *
  * Guarantees: never throws, never blocks the caller (the Sentry ship is
  * fire-and-forget, bounded to ~2s). CI=true / DEV_METRICS_DISABLED=1 suppress
  * shipping but still buffer the JSONL locally.
@@ -115,6 +121,29 @@ function commonFields(event: string, root: string): Record<string, string> {
   };
 }
 
+/** The JSONL file, under the repo root. */
+export function eventsFile(root: string = repoRoot()): string {
+  return path.join(root, ".dev-metrics", "events.jsonl");
+}
+
+/**
+ * `cwd` for a local line: the path from the root to cwd ("." for the root,
+ * "/"-separated), or "outside" when cwd is not under the root.
+ */
+export function cwdField(root: string, cwd: string = process.cwd()): string {
+  const real = (p: string): string => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  const rel = path.relative(real(root), real(cwd));
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return "outside";
+  return rel.split(path.sep).join("/");
+}
+
 function isoNoMillis(): string {
   return new Date().toISOString().replace(/\.\d+Z$/, "Z");
 }
@@ -334,14 +363,12 @@ export function record(
     for (const [k, v] of Object.entries(fields)) {
       obj[k] = v == null ? "" : String(v);
     }
+    obj.cwd = cwdField(root);
 
     try {
       const dir = path.join(root, ".dev-metrics");
       fs.mkdirSync(dir, { recursive: true });
-      fs.appendFileSync(
-        path.join(dir, "events.jsonl"),
-        JSON.stringify(obj) + "\n",
-      );
+      fs.appendFileSync(eventsFile(root), JSON.stringify(obj) + "\n");
     } catch {
       /* non-writable dir → fail-open */
     }

package/src/shared/dev-metrics/polling.ts

@@ -0,0 +1,135 @@
+/**
+ * Polling-loop warning (den#5) for `<cli> doctor`: one command, run from
+ * one place, more than POLL_LIMIT times in any POLL_WINDOW_MS window looks
+ * like an agent polling it. Local only: it reads the tail of the local
+ * .dev-metrics/events.jsonl and sends nothing anywhere.
+ *
+ * A line's place is its `cwd` (emit.ts). An older line has none, so it is
+ * keyed by its `repo` instead.
+ */
+import * as fs from "fs";
+
+/** More calls than this in one window is a polling loop. */
+export const POLL_LIMIT = 600;
+/** The window: an hour. */
+export const POLL_WINDOW_MS = 60 * 60 * 1000;
+/** At most this much of the file's end is read, however big it is. */
+export const TAIL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * The file's last `max` bytes as whole lines: a line cut by the start of
+ * the slice is dropped. A missing or unreadable file is no lines.
+ */
+export function readTailLines(
+  file: string,
+  max: number = TAIL_BYTES,
+): string[] {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(file, "r");
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, max);
+    const buf = Buffer.alloc(len);
+    let got = 0;
+    while (got < len) {
+      const n = fs.readSync(fd, buf, got, len - got, size - len + got);
+      if (n <= 0) break;
+      got += n;
+    }
+    const lines = buf.subarray(0, got).toString("utf-8").split("\n");
+    if (len < size) lines.shift();
+    return lines.filter((l) => l.trim());
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+export interface PollingLoop {
+  command: string;
+  /** Where: the line's cwd, or `repo <name>` for an older line. */
+  where: string;
+  /** Calls in the busiest window. */
+  calls: number;
+  /** The busiest window's first and last call (ISO, no millis). */
+  from: string;
+  to: string;
+}
+
+const iso = (ms: number): string =>
+  new Date(ms).toISOString().replace(/\.\d+Z$/, "Z");
+
+/**
+ * Every command+place with more than `limit` calls in some `windowMs`
+ * window, with its busiest window. Lines that aren't JSON, or have no
+ * command or time, are skipped.
+ */
+export function findPollingLoops(
+  lines: string[],
+  limit: number = POLL_LIMIT,
+  windowMs: number = POLL_WINDOW_MS,
+): PollingLoop[] {
+  const byKey = new Map<
+    string,
+    { command: string; where: string; times: number[] }
+  >();
+  for (const line of lines) {
+    let o: Record<string, unknown>;
+    try {
+      o = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (!o || typeof o !== "object") continue;
+    const command = typeof o.command === "string" ? o.command : "";
+    const t = typeof o.ts === "string" ? Date.parse(o.ts) : NaN;
+    if (!command || Number.isNaN(t)) continue;
+    const where =
+      typeof o.cwd === "string" && o.cwd
+        ? o.cwd
+        : `repo ${typeof o.repo === "string" && o.repo ? o.repo : "?"}`;
+    const key = `${command}\u0000${where}`;
+    let e = byKey.get(key);
+    if (!e) byKey.set(key, (e = { command, where, times: [] }));
+    e.times.push(t);
+  }
+  const out: PollingLoop[] = [];
+  for (const { command, where, times } of byKey.values()) {
+    if (times.length <= limit) continue;
+    times.sort((a, b) => a - b);
+    let best = 0;
+    let bi = 0;
+    let bj = 0;
+    for (let i = 0, j = 0; j < times.length; j++) {
+      while (times[j] - times[i] >= windowMs) i++;
+      if (j - i + 1 > best) {
+        best = j - i + 1;
+        bi = i;
+        bj = j;
+      }
+    }
+    if (best > limit)
+      out.push({
+        command,
+        where,
+        calls: best,
+        from: iso(times[bi]),
+        to: iso(times[bj]),
+      });
+  }
+  return out.sort((a, b) => b.calls - a.calls);
+}
+
+/** One warning line, as doctor prints it. */
+export function pollingWarning(p: PollingLoop): string {
+  return `looks like a polling loop: ${p.command} in ${p.where}, ${p.calls} calls in an hour (${p.from}–${p.to})`;
+}
+
+/** doctor's warnings for this events file (none when it is fine or absent). */
+export function pollingWarnings(
+  file: string,
+  max: number = TAIL_BYTES,
+): string[] {
+  return findPollingLoops(readTailLines(file, max)).map(pollingWarning);
+}

package/src/shared/engine.ts

@@ -93,11 +93,23 @@ export function playwrightCommand(...args: string[]): EngineCommand {
  * or with DEN_USE_DIST=1. Mirrors the web server's resolveServerEntrypoint.
  */
 export function cliEntrypoint(engine: string = getEngineRoot()): EngineCommand {
-  const built = path.join(engine, "dist/src/ui/cli/index.js");
+  return scriptEntrypoint("src/ui/cli/index.ts", engine);
+}
+
+/**
+ * How to run one of Den's TypeScript entry points (`src/….ts`, relative to
+ * the engine root) as a node process: cliEntrypoint's rules, for any
+ * script (an agent's hook, guardrails/stop-hook.ts).
+ */
+export function scriptEntrypoint(
+  rel: string,
+  engine: string = getEngineRoot(),
+): EngineCommand {
+  const built = path.join(engine, "dist", rel.replace(/\.ts$/, ".js"));
   if (process.env.DEN_USE_DIST === "1" && fs.existsSync(built))
     return { command: process.execPath, args: [built] };
   const loader = engineModuleFile("tsx/dist/loader.mjs", engine);
-  const src = path.join(engine, "src/ui/cli/index.ts");
+  const src = path.join(engine, rel);
   if (loader && fs.existsSync(src))
     return {
       command: process.execPath,

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");
+}