@monster-orange/den 0.4.11 → 0.4.13

package/src/shared/agents/roles.ts

@@ -0,0 +1,288 @@
+/**
+ * Roles and persona categories (AG-10.5, AG-11): two small registries.
+ *
+ * A role is a template and a dispatch key. Den owns planner, orchestrator,
+ * sde, reviewer, tester and designer. Each has default instructions, a
+ * permission mode and a command preset (plain command prefixes the agent
+ * may run without asking). Picking a role in New persona fills the form in
+ * (never over text already there), and the role adds nothing hidden to an
+ * agent's prompt: what it receives is the persona's instructions.
+ *
+ * A distribution adds roles in its config (`agents.roles`), and may extend
+ * a Den role's preset there, never redefine it:
+ *
+ *   agents:
+ *     roles:
+ *       copywriter: { description: …, instructions: …, mode: ask, preset: [], category: marketing }
+ *       reviewer: { preset: [semgrep] }      # adds to Den's preset only
+ *
+ * Categories group personas in the Start list and Settings › Personas.
+ * Den's are Engineering, Design, Product, Marketing and Operations; a
+ * distribution adds more (`agents.categories: [{ id, label }]`).
+ */
+import { checkCommands, PERMISSION_INTENTS } from "./permissions.js";
+import type { PermissionIntent } from "./permissions.js";
+
+/** Where a role or category came from (hub: later, once Den Hub exists). */
+export type RegistrySource = "den" | "distribution" | "project" | "hub";
+
+export interface RoleTemplate {
+  id: string;
+  source: RegistrySource;
+  /** One line: what a persona of this role does. */
+  description: string;
+  /** The starting instructions New persona fills in. */
+  instructions: string;
+  /** The starting permission mode. */
+  mode: PermissionIntent;
+  /** Plain command prefixes allowed without asking (AG-13.3). */
+  preset: string[];
+  /** The category a new persona of this role starts in. */
+  category: string;
+  /** Set when a distribution extended a Den role's preset. */
+  extendedBy?: RegistrySource;
+  /** The commands that extension added (shown apart from Den's). */
+  extension?: string[];
+}
+
+export interface Category {
+  id: string;
+  label: string;
+  source: RegistrySource;
+}
+
+/** A role or category id: lowercase letters, digits and "-", 1-32 long. */
+export const REGISTRY_ID_RE = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Den's categories, in the order lists show them. */
+export const DEN_CATEGORIES: readonly Category[] = [
+  { id: "engineering", label: "Engineering", source: "den" },
+  { id: "design", label: "Design", source: "den" },
+  { id: "product", label: "Product", source: "den" },
+  { id: "marketing", label: "Marketing", source: "den" },
+  { id: "operations", label: "Operations", source: "den" },
+];
+
+/**
+ * Den's roles. The presets are read-only commands only: a preset is
+ * allowed without asking, so Den's defaults never let an agent change
+ * anything unasked.
+ */
+export const DEN_ROLES: readonly RoleTemplate[] = [
+  {
+    id: "planner",
+    source: "den",
+    description:
+      "Turns goals into small, ready stories with acceptance criteria.",
+    instructions:
+      "Read the workspace's specs and open work items. Split goals into stories small enough for one pull request, each with testable acceptance criteria. Hand ready stories to the orchestrator. Don't write code.",
+    mode: "ask",
+    preset: ["gh issue list", "gh issue view"],
+    category: "engineering",
+  },
+  {
+    id: "orchestrator",
+    source: "den",
+    description:
+      "Hands ready stories to other agents and follows them to done.",
+    instructions:
+      "Take the next ready story in priority order and start the persona that fits it, one agent per story. Respect the workspace's concurrency cap. Ask a person before anything irreversible; never approve or merge.",
+    mode: "ask",
+    preset: ["gh issue list", "gh pr view"],
+    category: "engineering",
+  },
+  {
+    id: "sde",
+    source: "den",
+    description: "Implements one story, test first, and opens a pull request.",
+    instructions:
+      "Take one story. Write a failing test for each acceptance criterion first, then make it pass. Keep the change small, run the repo's checks, and open a pull request that says what you verified.",
+    mode: "ask",
+    preset: ["git status", "git diff", "git log"],
+    category: "engineering",
+  },
+  {
+    id: "reviewer",
+    source: "den",
+    description:
+      "Reviews a pull request adversarially. Never approves or merges.",
+    instructions:
+      "Check the change against its story's acceptance criteria, then look for what wasn't tested: edge cases, failure paths, security. Verify each finding in the code and report them ranked by impact. Never approve, merge or push.",
+    mode: "ask",
+    preset: ["git diff", "git log", "gh pr diff", "gh pr view"],
+    category: "engineering",
+  },
+  {
+    id: "tester",
+    source: "den",
+    description: "Runs the test suites and reports failures with repro steps.",
+    instructions:
+      "Run the workspace's unit, integration and end-to-end suites. For each failure, write the exact repro and the smallest failing command. Don't fix code.",
+    mode: "ask",
+    preset: ["git status"],
+    category: "engineering",
+  },
+  {
+    id: "designer",
+    source: "den",
+    description: "Designs flows and screens with the design system.",
+    instructions:
+      "Start from the user's goal and the story's acceptance criteria. Compose from the design system's components, and describe every state (empty, loading, error, success) and narrow screens. Hand off a short spec the developers can build and test.",
+    mode: "ask",
+    preset: [],
+    category: "design",
+  },
+];
+
+const isMapping = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+const shown = (v: unknown) =>
+  (JSON.stringify(v) ?? "undefined").replace(/[^\x20-\x7e]/g, "?").slice(0, 60);
+
+function line(where: string, v: unknown, max: number): string {
+  if (
+    typeof v !== "string" ||
+    !v.trim() ||
+    [...v].length > max ||
+    /[\p{Cc}\p{Cf}]/u.test(v)
+  )
+    throw new Error(
+      `${where}: must be one line of 1-${max} characters, no control characters`,
+    );
+  return v.trim();
+}
+
+/**
+ * `agents.categories` checked: a list of { id, label }. A Den category's
+ * id is refused (it can't be renamed). Anything else throws, naming it.
+ */
+export function checkCategoriesConfig(raw: unknown): Category[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw))
+    throw new Error("agents.categories: must be a list of { id, label }");
+  const seen = new Set(DEN_CATEGORIES.map((c) => c.id));
+  return raw.map((x, i) => {
+    const where = `agents.categories[${i}]`;
+    if (!isMapping(x))
+      throw new Error(`${where}: must be a mapping { id, label }`);
+    for (const k of Object.keys(x))
+      if (k !== "id" && k !== "label")
+        throw new Error(`${where}.${k}: unknown key (takes id, label)`);
+    if (typeof x.id !== "string" || !REGISTRY_ID_RE.test(x.id))
+      throw new Error(
+        `${where}.id: ${shown(x.id)} must be lowercase letters, digits and "-" (1-32)`,
+      );
+    if (seen.has(x.id))
+      throw new Error(`${where}.id: "${x.id}" is already a category`);
+    seen.add(x.id);
+    return {
+      id: x.id,
+      label: line(`${where}.label`, x.label, 40),
+      source: "distribution" as const,
+    };
+  });
+}
+
+/** What `agents.roles` holds, checked (merged with Den's by roleRegistry). */
+export interface RolesConfig {
+  /** New roles. */
+  added: RoleTemplate[];
+  /** Den roles' preset extensions, by role id. */
+  extended: Record<string, string[]>;
+}
+
+/**
+ * `agents.roles` checked. A Den role takes `preset` only (an extension);
+ * a new role takes description, instructions, mode, preset and category.
+ * `categories` are the ids a new role's category may name.
+ */
+export function checkRolesConfig(
+  raw: unknown,
+  categories: readonly string[] = DEN_CATEGORIES.map((c) => c.id),
+): RolesConfig {
+  const out: RolesConfig = { added: [], extended: {} };
+  if (raw === undefined || raw === null) return out;
+  if (!isMapping(raw))
+    throw new Error(
+      "agents.roles: must be a mapping of role id to its template",
+    );
+  for (const [id, v] of Object.entries(raw)) {
+    const where = `agents.roles.${id}`;
+    if (!REGISTRY_ID_RE.test(id))
+      throw new Error(
+        `${where}: a role id must be lowercase letters, digits and "-" (1-32)`,
+      );
+    if (!isMapping(v)) throw new Error(`${where}: must be a mapping`);
+    const den = DEN_ROLES.find((r) => r.id === id);
+    if (den) {
+      for (const k of Object.keys(v))
+        if (k !== "preset")
+          throw new Error(
+            `${where}.${k}: ${id} is Den's role: a distribution may only extend its preset`,
+          );
+      out.extended[id] = checkCommands(v.preset, `${where}.preset`);
+      continue;
+    }
+    const keys = ["description", "instructions", "mode", "preset", "category"];
+    for (const k of Object.keys(v))
+      if (!keys.includes(k))
+        throw new Error(
+          `${where}.${k}: unknown key (takes ${keys.join(", ")})`,
+        );
+    const mode = v.mode ?? "ask";
+    if (!(PERMISSION_INTENTS as readonly unknown[]).includes(mode))
+      throw new Error(
+        `${where}.mode: ${shown(mode)} must be one of ${PERMISSION_INTENTS.join(", ")}`,
+      );
+    const category = v.category ?? "engineering";
+    if (typeof category !== "string" || !categories.includes(category))
+      throw new Error(
+        `${where}.category: ${shown(category)} is not a category (${categories.join(", ")})`,
+      );
+    const instructions = v.instructions ?? "";
+    if (typeof instructions !== "string" || instructions.length > 4000)
+      throw new Error(
+        `${where}.instructions: must be text of up to 4000 characters`,
+      );
+    out.added.push({
+      id,
+      source: "distribution",
+      description: line(`${where}.description`, v.description, 200),
+      instructions: instructions.trim(),
+      mode: mode as PermissionIntent,
+      preset: checkCommands(v.preset, `${where}.preset`),
+      category,
+    });
+  }
+  return out;
+}
+
+/** Den's roles with a distribution's extensions, then its new roles. */
+export function roleRegistry(
+  cfg: RolesConfig = { added: [], extended: {} },
+): RoleTemplate[] {
+  const den = DEN_ROLES.map((r) => {
+    const ext = cfg.extended[r.id];
+    if (!ext?.length) return { ...r, preset: [...r.preset] };
+    return {
+      ...r,
+      preset: [...new Set([...r.preset, ...ext])],
+      extendedBy: "distribution" as const,
+      extension: [...ext],
+    };
+  });
+  return [...den, ...cfg.added];
+}
+
+/** Den's categories, then a distribution's. */
+export function categoryRegistry(extra: readonly Category[] = []): Category[] {
+  return [...DEN_CATEGORIES, ...extra];
+}
+
+/** A role's command preset ([] for none, or a role that isn't registered). */
+export function rolePreset(
+  roles: readonly RoleTemplate[],
+  role: string | undefined,
+): string[] {
+  return role ? (roles.find((r) => r.id === role)?.preset ?? []) : [];
+}

package/src/shared/agents/runtime.ts

@@ -17,8 +17,10 @@ import {
   type StrategyEntry,
 } from "../strategies/registry.js";
 import type { CatalogEntry } from "./catalog.js";
+import type { AgentRecord } from "./records.js";
 import type { Persona } from "./personas.js";
 import type { BinSource, RuntimeFind } from "./runtime-search.js";
+import type { PermissionIntent } from "./permissions.js";
 
 export const RUNTIME_KIND = "runtime";
 
@@ -94,6 +96,16 @@ export interface LaunchInput {
    * session rotates (0: never). Den's hooks count them. Default 3.
    */
   rotateAfter?: number;
+  /**
+   * The permission intent to launch with (AG-13): the agent's, else its
+   * persona's `permission_mode`. Only a runtime with `permissions` takes it.
+   */
+  permission?: PermissionIntent;
+  /**
+   * Plain command prefixes allowed without asking (AG-13.3, 13.4): the
+   * role's preset and the extra commands, checked (permissions.ts).
+   */
+  allow?: string[];
   /**
    * The new conversation's first prompt (a relaunch from handoff.md).
    * Only a runtime with `firstPrompt: true` is given one.
@@ -115,6 +127,29 @@ export interface LaunchOutput {
 
 export type ResumeInput = LaunchInput;
 
+/**
+ * A model a runtime offers (AG-12.3): its id as the Model list shows it,
+ * and the versions it can be pinned to, newest first. "Latest" tracks the
+ * newest release; a pinned version is one of `versions`.
+ */
+export interface RuntimeModel {
+  id: string;
+  label: string;
+  versions: string[];
+  latest: string;
+}
+
+/**
+ * How a runtime expresses Den's permission intents (AG-13.2), as its own
+ * launch config: a read-only preview of each mode ("What this allows on
+ * <runtime>"), and how one plain command prefix becomes its rules
+ * (`{c}` the prefix). The runtime's launch writes exactly these.
+ */
+export interface RuntimePermissions {
+  modes: Record<PermissionIntent, string>;
+  commandRules: string[];
+}
+
 export interface Runtime {
   /** "den-claude", "generic". */
   id: string;
@@ -141,6 +176,13 @@ export interface Runtime {
    * firstPrompt): Relaunch from handoff needs it (den#4).
    */
   firstPrompt?: boolean;
+  /**
+   * The models it offers (AG-12.3), from the catalog shipped with each Den
+   * release; none: it takes no model choice from Den.
+   */
+  models?(): RuntimeModel[];
+  /** How it expresses permission intents (AG-13); none: it can't yet. */
+  permissions?: RuntimePermissions;
   /** 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. */
@@ -157,6 +199,13 @@ export interface Runtime {
    * conversation's id is taken. Den then tries the other way, once.
    */
   launchFailures?: { noConversation?: RegExp; idInUse?: RegExp };
+  /**
+   * The name the runtime gives the agent's conversation (AG-4b: Claude
+   * Code's `/rename`), or null when it has none or can't say. Optional:
+   * a runtime without it has Den's rename only. Must be quick and never
+   * throw; its catalog entry's `sessionName` says how stable its source is.
+   */
+  sessionName?(rec: AgentRecord, env?: NodeJS.ProcessEnv): string | null;
   /** Where permission prompts surface (Q-AG-2). */
   approvals?: "terminal" | "hook";
   /**

package/src/shared/agents/session-name.ts

@@ -0,0 +1,110 @@
+/**
+ * An agent's session name (AG-4b): what its pane header adds after
+ * `{workspace} · {runtime}`, and what its tab, the Agents list and ⌘K show.
+ *
+ * Two sources, and the most recent rename wins:
+ *
+ *   - Den's own: a person double-clicked its tab (the record's displayName,
+ *     made at displayNameAt). Every runtime has it.
+ *   - The runtime's, when its adapter has `sessionName` (Runtime, AG-4b):
+ *     Claude Code's `/rename`. Its time is when Den first saw it, kept in
+ *     the agent's files dir (session-name.json, with the conversation's
+ *     token: Start fresh forgets it). An adapter that fails or throws is no
+ *     name; it never breaks the list.
+ *
+ * Den never writes a name back into the runtime.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { agentFilesDir, writePrivate, type AgentRecord } from "./records.js";
+import { getRuntime } from "./runtimes.js";
+import { cleanName } from "./transcript-follow.js";
+
+export {
+  FOLLOW_MAX_BYTES,
+  followState,
+  oscTitles,
+  resetFollowers,
+  transcriptTitle,
+} from "./transcript-follow.js";
+
+interface Seen {
+  token: string | null;
+  name: string;
+  /** When Den first saw it (ms). */
+  at: number;
+}
+
+const seenFile = (stateDir: string, id: string) =>
+  path.join(agentFilesDir(stateDir, id), "session-name.json");
+
+function readSeen(file: string): Seen | null {
+  try {
+    const v = JSON.parse(fs.readFileSync(file, "utf-8")) as Partial<Seen>;
+    if (typeof v.name !== "string" || typeof v.at !== "number") return null;
+    return {
+      token: typeof v.token === "string" ? v.token : null,
+      name: v.name,
+      at: v.at,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The runtime's name for the agent's conversation, with when it was first seen. */
+function runtimeName(
+  rec: AgentRecord,
+  stateDir: string,
+  env: NodeJS.ProcessEnv,
+  now: () => number,
+): Seen | null {
+  const rt = getRuntime(rec.runtime);
+  if (!rt?.sessionName) return null;
+  const token = rec.resumeToken ?? null;
+  const file = seenFile(stateDir, rec.id);
+  let seen = readSeen(file);
+  if (seen && seen.token !== token) seen = null;
+  let name: string | null = null;
+  try {
+    name = cleanName(rt.sessionName(rec, env));
+  } catch {
+    name = null;
+  }
+  // null: nothing new (not caught up, not found); the last name stays.
+  if (name && name !== seen?.name) {
+    seen = { token, name, at: now() };
+    try {
+      writePrivate(file, JSON.stringify(seen) + "\n");
+    } catch {
+      /* shown, not kept: it is seen again next time */
+    }
+  }
+  return seen;
+}
+
+/**
+ * The agent's session name: the latest of Den's rename and the runtime's,
+ * or undefined when neither has one. Never throws.
+ */
+export function agentSessionName(
+  rec: AgentRecord,
+  stateDir: string,
+  env: NodeJS.ProcessEnv = process.env,
+  now: () => number = Date.now,
+): string | undefined {
+  let rt: Seen | null = null;
+  try {
+    rt = runtimeName(rec, stateDir, env, now);
+  } catch {
+    rt = null;
+  }
+  const den = rec.displayName
+    ? {
+        name: rec.displayName,
+        at: Date.parse(rec.displayNameAt ?? rec.startedAt) || 0,
+      }
+    : null;
+  if (den && rt) return rt.at > den.at ? rt.name : den.name;
+  return (den ?? rt)?.name;
+}

package/src/shared/agents/transcript-follow.ts

@@ -0,0 +1,180 @@
+/**
+ * Reading a session's name from what a runtime writes (AG-4b), without
+ * ever reading a whole file at once:
+ *
+ *   - transcriptTitle(file): the latest `{"type":"custom-title",
+ *     "customTitle":…}` record in a JSON-lines transcript (Claude Code's
+ *     `/rename`). Each ask reads on from where the last one stopped, at
+ *     most FOLLOW_MAX_BYTES, so a long transcript is caught up over a few
+ *     asks; a file that got shorter is read again from the start. Only
+ *     lines that mention "custom-title" are parsed. Any failure is null.
+ *   - oscTitles(chunk, carry): the terminal titles (OSC 0 and OSC 2) in a
+ *     PTY's output, for runtimes the catalog marks `titleFromOsc`.
+ *
+ * A name is cleaned for the page: control, format and line-separator
+ * characters go, spaces are squeezed, and it is cut at MAX_NAME.
+ */
+import * as fs from "fs";
+
+/** The most one ask reads of a transcript. */
+export const FOLLOW_MAX_BYTES = 1024 * 1024;
+const CHUNK = 64 * 1024;
+/** A line longer than this is no title record: skipped to its end. */
+const MAX_LINE = 64 * 1024;
+/** The longest name kept. */
+export const MAX_NAME = 80;
+/** The most files followed at once (the oldest is forgotten first). */
+const MAX_FOLLOWED = 256;
+
+interface Follow {
+  offset: number;
+  title: string | null;
+  /** The start of a line whose newline hasn't come yet. */
+  rest: Buffer;
+  /** Inside a line too long to be a title: drop bytes to its newline. */
+  skipping: boolean;
+}
+
+const followers = new Map<string, Follow>();
+
+/** A name as the page may show it, or null when nothing is left. */
+export function cleanName(v: unknown): string | null {
+  if (typeof v !== "string") return null;
+  const s = v
+    .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!s) return null;
+  return [...s].slice(0, MAX_NAME).join("").trim() || null;
+}
+
+function titleOf(line: Buffer): string | null | undefined {
+  if (!line.includes("custom-title")) return undefined;
+  try {
+    const rec = JSON.parse(line.toString("utf-8")) as {
+      type?: unknown;
+      customTitle?: unknown;
+    };
+    if (rec?.type !== "custom-title") return undefined;
+    return cleanName(rec.customTitle) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The latest custom-title in `file` (read on from the last ask), or null. */
+export function transcriptTitle(file: string): string | null {
+  let fd: number | undefined;
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile()) {
+      followers.delete(file);
+      return null;
+    }
+    let f = followers.get(file);
+    if (!f || st.size < f.offset) {
+      f = { offset: 0, title: null, rest: Buffer.alloc(0), skipping: false };
+      followers.delete(file);
+      if (followers.size >= MAX_FOLLOWED)
+        followers.delete(followers.keys().next().value as string);
+      followers.set(file, f);
+    }
+    if (st.size === f.offset) return f.title;
+    fd = fs.openSync(file, "r");
+    const end = Math.min(st.size, f.offset + FOLLOW_MAX_BYTES);
+    const buf = Buffer.alloc(CHUNK);
+    while (f.offset < end) {
+      const n = fs.readSync(
+        fd,
+        buf,
+        0,
+        Math.min(CHUNK, end - f.offset),
+        f.offset,
+      );
+      if (n <= 0) break;
+      f.offset += n;
+      let data = buf.subarray(0, n);
+      for (;;) {
+        const nl = data.indexOf(0x0a);
+        if (nl < 0) {
+          if (!f.skipping) {
+            f.rest = Buffer.concat([f.rest, data]);
+            if (f.rest.length > MAX_LINE) {
+              f.rest = Buffer.alloc(0);
+              f.skipping = true;
+            }
+          }
+          break;
+        }
+        const piece = data.subarray(0, nl);
+        data = data.subarray(nl + 1);
+        if (f.skipping) {
+          f.skipping = false;
+          continue;
+        }
+        const line = f.rest.length ? Buffer.concat([f.rest, piece]) : piece;
+        f.rest = Buffer.alloc(0);
+        const t = titleOf(line);
+        if (t) f.title = t;
+      }
+    }
+    return f.title;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined)
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* closed */
+      }
+  }
+}
+
+/** Where a followed file is up to (tests). */
+export function followState(file: string): { offset: number } | undefined {
+  const f = followers.get(file);
+  return f ? { offset: f.offset } : undefined;
+}
+
+/** Forget every followed file (tests). */
+export function resetFollowers(): void {
+  followers.clear();
+}
+
+/** The most of an unended OSC kept between chunks. */
+const MAX_CARRY = 1024;
+const OSC_START = "\u001b]";
+
+/**
+ * The terminal titles (OSC 0 and OSC 2, ended by BEL or ST) in `chunk`,
+ * with `carry` the unended OSC the last chunk left; returns what this one
+ * leaves. Every other OSC (a link, the cwd) is not a title.
+ */
+export function oscTitles(
+  chunk: string,
+  carry: string,
+): { titles: string[]; carry: string } {
+  const s = carry + chunk;
+  const titles: string[] = [];
+  let i = 0;
+  for (;;) {
+    const at = s.indexOf(OSC_START, i);
+    if (at < 0) {
+      // A lone ESC at the very end may start an OSC in the next chunk.
+      return { titles, carry: s.endsWith("\u001b") ? "\u001b" : "" };
+    }
+    const bel = s.indexOf("\u0007", at + 2);
+    const st = s.indexOf("\u001b\\", at + 2);
+    const ends = [bel, st].filter((x) => x >= 0);
+    if (!ends.length) return { titles, carry: s.slice(at, at + MAX_CARRY) };
+    const stop = Math.min(...ends);
+    const body = s.slice(at + 2, stop);
+    const m = /^([02]);([\s\S]*)$/.exec(body);
+    if (m) {
+      const t = cleanName(m[2]);
+      if (t) titles.push(t);
+    }
+    i = stop + (stop === bel ? 1 : 2);
+  }
+}