@monster-orange/den 0.4.11 → 0.4.13

package/src/shared/agents/persona-store.ts

@@ -0,0 +1,286 @@
+/**
+ * A person's own personas (AG-10.3, AG-10.7): <state_dir>/personas/<id>.md,
+ * each 0600 in a 0700 directory, written in the same format a pack uses
+ * (Claude Code's agent markdown plus Den's keys: personas.ts), so a file
+ * made here reads like one made by hand.
+ *
+ * Only these files are ever written or removed: a built-in or a
+ * distribution's persona is read-only, and editing one makes a local
+ * duplicate first (the caller's choice: the routes do). Every field is
+ * checked strictly (checkPersonaInput): an unknown key, a control
+ * character, a role, category, runtime, model or version that isn't
+ * registered, or a command that isn't a plain prefix is refused, naming
+ * the field. Nothing here runs a command or passes text to a shell.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+import { writePrivate } from "./records.js";
+import { PERSONA_ID_RE } from "./personas.js";
+import {
+  checkCommands,
+  checkIntent,
+  type PermissionIntent,
+} from "./permissions.js";
+import type { RuntimeModel } from "./runtime.js";
+
+/** Where a person's own personas live. */
+export function localPersonasDir(stateDir: string): string {
+  return path.join(stateDir, "personas");
+}
+
+/** What New persona and Edit send, checked. */
+export interface PersonaInput {
+  displayName?: string;
+  role: string;
+  category: string;
+  description: string;
+  instructions: string;
+  runtime: string;
+  model?: string;
+  version: string;
+  permission: PermissionIntent;
+  allowedCommands: string[];
+}
+
+/** What a field may name: the registries and runtimes it is checked against. */
+export interface PersonaChoices {
+  roles: readonly string[];
+  categories: readonly string[];
+  runtimes: readonly { id: string; models: readonly RuntimeModel[] }[];
+}
+
+export const MAX_INSTRUCTIONS = 20_000;
+export const MAX_DESCRIPTION = 200;
+export const MAX_PERSONA_NAME = 40;
+
+const KEYS = [
+  "displayName",
+  "role",
+  "category",
+  "description",
+  "instructions",
+  "runtime",
+  "model",
+  "version",
+  "permission",
+  "allowedCommands",
+] as const;
+
+/** A usage error: a field a person sent isn't what it may be. */
+export class PersonaInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PersonaInputError";
+  }
+}
+
+const shown = (v: unknown) =>
+  (JSON.stringify(v) ?? "undefined").replace(/[^\x20-\x7e]/g, "?").slice(0, 60);
+
+function oneLine(
+  key: string,
+  v: unknown,
+  max: number,
+  required: boolean,
+): string | undefined {
+  if (v === undefined || v === null || v === "") {
+    if (required) throw new PersonaInputError(`${key} is required`);
+    return undefined;
+  }
+  if (typeof v !== "string")
+    throw new PersonaInputError(`${key} must be a string`);
+  const s = v.trim();
+  if (!s) {
+    if (required) throw new PersonaInputError(`${key} is required`);
+    return undefined;
+  }
+  if ([...s].length > max)
+    throw new PersonaInputError(`${key} must be at most ${max} characters`);
+  if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(s))
+    throw new PersonaInputError(`${key} can't have control characters`);
+  return s;
+}
+
+function oneOf(key: string, v: unknown, list: readonly string[]): string {
+  if (typeof v !== "string" || !list.includes(v))
+    throw new PersonaInputError(
+      `${key}: ${shown(v)} is not one of ${list.join(", ") || "(none)"}`,
+    );
+  return v;
+}
+
+/**
+ * A model and version for runtime `rt` (AG-12.3): the model one it offers
+ * (none: no model), the version "latest" or one of that model's.
+ */
+export function checkModelChoice(
+  rt: { id: string; models: readonly RuntimeModel[] },
+  model: unknown,
+  version: unknown,
+): { model?: string; version: string } {
+  const ver =
+    version === undefined || version === null || version === ""
+      ? "latest"
+      : version;
+  if (model === undefined || model === null || model === "") {
+    if (ver !== "latest") throw new PersonaInputError("version needs a model");
+    return { version: "latest" };
+  }
+  if (!rt.models.length)
+    throw new PersonaInputError(`${rt.id} takes no model choice from Den`);
+  const m = rt.models.find((x) => x.id === model);
+  if (!m)
+    throw new PersonaInputError(
+      `model: ${shown(model)} is not one of ${rt.id}'s (${rt.models.map((x) => x.id).join(", ")})`,
+    );
+  if (
+    ver !== "latest" &&
+    !(typeof ver === "string" && m.versions.includes(ver))
+  )
+    throw new PersonaInputError(
+      `version: ${shown(ver)} is not "latest" or one of ${m.id}'s (${m.versions.join(", ")})`,
+    );
+  return { model: m.id, version: ver as string };
+}
+
+/**
+ * A persona as New persona or Edit sends it, checked against `choices`.
+ * Throws PersonaInputError naming the first field that is wrong.
+ */
+export function checkPersonaInput(
+  raw: unknown,
+  choices: PersonaChoices,
+): PersonaInput {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    throw new PersonaInputError("a persona must be a JSON object");
+  const r = raw as Record<string, unknown>;
+  for (const k of Object.keys(r))
+    if (!(KEYS as readonly string[]).includes(k))
+      throw new PersonaInputError(
+        `${k}: unknown field (a persona takes ${KEYS.join(", ")})`,
+      );
+  const role = oneOf("role", r.role, choices.roles);
+  const category = oneOf("category", r.category, choices.categories);
+  const runtime = oneOf(
+    "runtime",
+    r.runtime,
+    choices.runtimes.map((x) => x.id),
+  );
+  const rt = choices.runtimes.find((x) => x.id === runtime)!;
+  const { model, version } = checkModelChoice(rt, r.model, r.version);
+  let permission: PermissionIntent;
+  let allowedCommands: string[];
+  try {
+    permission = checkIntent(r.permission ?? "ask", "permission");
+    allowedCommands = checkCommands(r.allowedCommands, "allowedCommands");
+  } catch (e) {
+    throw new PersonaInputError((e as Error).message);
+  }
+  const instructions = r.instructions ?? "";
+  if (typeof instructions !== "string")
+    throw new PersonaInputError("instructions must be a string");
+  const text = instructions.replace(/\r\n?/g, "\n").trim();
+  if (!text) throw new PersonaInputError("instructions are required");
+  if (text.length > MAX_INSTRUCTIONS)
+    throw new PersonaInputError(
+      `instructions must be at most ${MAX_INSTRUCTIONS} characters`,
+    );
+  // Newlines and tabs only: no escape sequences, no bidi overrides.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x08\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/.test(text))
+    throw new PersonaInputError("instructions can't have control characters");
+  const displayName = oneLine(
+    "displayName",
+    r.displayName,
+    MAX_PERSONA_NAME,
+    false,
+  );
+  return {
+    ...(displayName ? { displayName } : {}),
+    role,
+    category,
+    description: oneLine("description", r.description, MAX_DESCRIPTION, true)!,
+    instructions: text,
+    runtime,
+    ...(model ? { model } : {}),
+    version,
+    permission,
+    allowedCommands,
+  };
+}
+
+/** The persona file for `input`: front matter (YAML) and its instructions. */
+export function personaMarkdown(id: string, input: PersonaInput): string {
+  const fm: Record<string, unknown> = {
+    name: id,
+    ...(input.displayName ? { display_name: input.displayName } : {}),
+    role: input.role,
+    category: input.category,
+    description: input.description,
+    runtime: input.runtime,
+    ...(input.model ? { model: input.model } : {}),
+    version: input.version,
+    permission_mode: input.permission,
+    ...(input.allowedCommands.length
+      ? { allowed_commands: input.allowedCommands }
+      : {}),
+  };
+  return `---\n${yaml.stringify(fm).trimEnd()}\n---\n\n${input.instructions}\n`;
+}
+
+function fileOf(stateDir: string, id: string): string {
+  if (!PERSONA_ID_RE.test(id))
+    throw new PersonaInputError(`"${shown(id)}" is not a persona id`);
+  return path.join(localPersonasDir(stateDir), `${id}.md`);
+}
+
+/** Whether a local persona file `id` exists. */
+export function localPersonaExists(stateDir: string, id: string): boolean {
+  return PERSONA_ID_RE.test(id) && fs.existsSync(fileOf(stateDir, id));
+}
+
+/** Write local persona `id` (0600, atomically). */
+export function writeLocalPersona(
+  stateDir: string,
+  id: string,
+  input: PersonaInput,
+): string {
+  const file = fileOf(stateDir, id);
+  writePrivate(file, personaMarkdown(id, input));
+  return file;
+}
+
+/** Remove local persona `id`; false when there was none. Only that file. */
+export function deleteLocalPersona(stateDir: string, id: string): boolean {
+  const file = fileOf(stateDir, id);
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw e;
+  }
+}
+
+/**
+ * A new persona's id: from its name (else its role), lowercased, made of
+ * what an id may hold; "-2", "-3", … when taken.
+ */
+export function newPersonaId(
+  input: Pick<PersonaInput, "displayName" | "role">,
+  taken: ReadonlySet<string>,
+): string {
+  const base =
+    (input.displayName ?? input.role)
+      .toLowerCase()
+      .normalize("NFKD")
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/^[^a-z0-9]+|-+$/g, "")
+      .slice(0, 56) || "persona";
+  if (!taken.has(base)) return base;
+  for (let i = 2; ; i++) {
+    const id = `${base}-${i}`;
+    if (!taken.has(id)) return id;
+  }
+}

package/src/shared/agents/personas.ts

@@ -12,20 +12,35 @@
  *   model        the default model; `inherit` means none of its own
  *   tools        "Read, Grep" or a list: hints, never a restriction Den applies
  *
- * Den's own keys sit beside them: `runtime` (default den-claude),
+ * Den's own keys sit beside them (AG-10.2): `display_name` ("Rita", shown
+ * as "Rita (reviewer)"), `role` (a key into the role registry, roles.ts:
+ * planner, sde, …; a sentence there, as before AG-10, is read as the
+ * description), `category` (engineering, design, …; default from the
+ * role), `version` ("latest" or a pinned model version),
+ * `allowed_commands` (plain command prefixes run without asking: AG-13.4),
+ * `runtime` (default den-claude),
  * `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's intent: ask, edits or all; or a Claude Code mode, which
+ * den-claude checks), 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.
+ *
+ * Where personas come from (AG-10.3), each with its origin: built-in
+ * (Den's default pack), distribution (agents.persona_packs) and local
+ * (<state_dir>/personas/*.md, made in the UI or by hand: persona-store.ts).
+ * Of two with one id, local wins over distribution, and distribution over
+ * built-in. Hub comes later; only its origin value exists now.
  */
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "yaml";
 import { WORKSPACE_NAME_RE } from "../agent-actor.js";
+import { checkCommands } from "./permissions.js";
+import { DEN_ROLES, REGISTRY_ID_RE } from "./roles.js";
 import { enginePath } from "../engine.js";
 import {
   DEFAULT_PACK_GUARDRAILS,
@@ -34,10 +49,31 @@ import {
   type Guardrails,
 } from "./guardrails.js";
 
+/** Where a persona came from (AG-10.3). */
+export type PersonaOrigin = "builtin" | "distribution" | "local" | "hub";
+export const PERSONA_ORIGINS: readonly PersonaOrigin[] = [
+  "builtin",
+  "distribution",
+  "local",
+  "hub",
+];
+
 export interface Persona {
   id: string;
+  /** A person's name for it ("Rita"), shown as "Rita (reviewer)". */
+  displayName?: string;
+  /** Its role: a key into the role registry (roles.ts), when it has one. */
+  role?: string;
   /** One line: what it does. */
-  role: string;
+  description: string;
+  /** Its category (roles.ts): the role's, else engineering. */
+  category: string;
+  /** "latest" (default) or a pinned version of its model. */
+  version?: string;
+  /** Plain command prefixes it may run without asking (AG-13.4). */
+  allowedCommands: string[];
+  /** Where it came from (loadPersonas sets it). */
+  origin: PersonaOrigin;
   /** The role prompt: the file's body. */
   prompt: string;
   /** The runtime it runs on unless an agent says otherwise. */
@@ -70,6 +106,9 @@ export interface Persona {
   source: string;
 }
 
+/** A model version as a persona pins it: "latest" or a version id. */
+export const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._@:-]{0,63}$/;
+
 /** A persona id: the same rules as an agent id or a workspace name. */
 export const PERSONA_ID_RE = WORKSPACE_NAME_RE;
 
@@ -115,7 +154,11 @@ function stringList(
 }
 
 /** One persona file, or null when it has no front matter. */
-export function parsePersona(text: string, file: string): Persona | null {
+export function parsePersona(
+  text: string,
+  file: string,
+  origin: PersonaOrigin = "builtin",
+): Persona | null {
   const m = FRONT_MATTER.exec(text);
   if (!m) return null;
   let fm: unknown;
@@ -155,6 +198,35 @@ export function parsePersona(text: string, file: string): Persona | null {
     argv = f.argv as string[];
   }
   const model = optString(f, "model", file);
+  const displayName = optString(f, "display_name", file);
+  if (
+    displayName &&
+    ([...displayName].length > 40 ||
+      /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(displayName))
+  )
+    throw new Error(
+      `${file}: display_name must be at most 40 characters, with no control characters`,
+    );
+  // AG-10.2: `role` is a role key; a sentence there (before AG-10) is the
+  // description it always was.
+  const roleRaw = optString(f, "role", file);
+  const role = roleRaw && REGISTRY_ID_RE.test(roleRaw) ? roleRaw : undefined;
+  const category = optString(f, "category", file);
+  if (category && !REGISTRY_ID_RE.test(category))
+    throw new Error(
+      `${file}: category "${category.slice(0, 40)}" must be lowercase letters, digits and "-"`,
+    );
+  const version = optString(f, "version", file);
+  if (version && !VERSION_RE.test(version))
+    throw new Error(
+      `${file}: version must be "latest" or a version id (letters, digits, . _ @ : -)`,
+    );
+  let allowedCommands: string[];
+  try {
+    allowedCommands = checkCommands(f.allowed_commands, "allowed_commands");
+  } catch (e) {
+    throw new Error(`${file}: ${(e as Error).message}`);
+  }
   const runtime = optString(f, "runtime", file);
   const permissionMode = optString(f, "permission_mode", file);
   const guardrailsSet: Partial<Guardrails> = {};
@@ -170,7 +242,19 @@ export function parsePersona(text: string, file: string): Persona | null {
   }
   return {
     id,
-    role: optString(f, "role", file) ?? optString(f, "description", file) ?? "",
+    ...(displayName ? { displayName } : {}),
+    ...(role ? { role } : {}),
+    description:
+      (roleRaw && !role ? roleRaw : undefined) ??
+      optString(f, "description", file) ??
+      "",
+    category:
+      category ??
+      DEN_ROLES.find((r) => r.id === role)?.category ??
+      "engineering",
+    ...(version && version !== "latest" ? { version } : {}),
+    allowedCommands,
+    origin,
     prompt: text.slice(m[0].length).trim(),
     ...(runtime ? { runtime } : {}),
     ...(model && model !== "inherit" ? { model } : {}),
@@ -189,7 +273,10 @@ export function parsePersona(text: string, file: string): Persona | null {
  * A pack's personas, by file name. A directory with an `agents/` inside (a
  * Claude Code plugin) is read from there.
  */
-export function readPack(dir: string): Persona[] {
+export function readPack(
+  dir: string,
+  origin: PersonaOrigin = "builtin",
+): Persona[] {
   const agents = path.join(dir, "agents");
   const from = fs.statSync(agents, { throwIfNoEntry: false })?.isDirectory()
     ? agents
@@ -200,7 +287,7 @@ export function readPack(dir: string): Persona[] {
     if (!name.endsWith(".md")) continue;
     const file = path.join(from, name);
     if (!fs.statSync(file).isFile()) continue;
-    const p = parsePersona(fs.readFileSync(file, "utf-8"), file);
+    const p = parsePersona(fs.readFileSync(file, "utf-8"), file, origin);
     if (!p) continue;
     const prev = seen.get(p.id);
     if (prev) throw new Error(`${prev} and ${file} both define "${p.id}"`);
@@ -237,17 +324,34 @@ export function loadPersonas(
   packDirs: string[],
   defaultPack: string = DEFAULT_PACK_DIR,
   guardrails: PackGuardrails = {},
+  /**
+   * <state_dir>/personas (AG-10.3): a person's own, read last so one wins
+   * over a pack's of the same id. Absent: none. They get the default
+   * pack's guardrails (Den's hooks and instructions) unless their own
+   * front matter says otherwise.
+   */
+  localDir?: string,
 ): Map<string, Persona> {
   const all = new Map<string, Persona>();
-  const packs: [string, Guardrails][] = [
-    [defaultPack, { ...DEFAULT_PACK_GUARDRAILS, ...guardrails.defaultPack }],
-    ...packDirs.map((dir, i): [string, Guardrails] => [
+  const packs: [string, Guardrails, PersonaOrigin][] = [
+    [
+      defaultPack,
+      { ...DEFAULT_PACK_GUARDRAILS, ...guardrails.defaultPack },
+      "builtin",
+    ],
+    ...packDirs.map((dir, i): [string, Guardrails, PersonaOrigin] => [
       dir,
       { ...PACK_GUARDRAILS, ...guardrails.packs?.[i] },
+      "distribution",
     ]),
   ];
-  for (const [dir, g] of packs)
-    for (const p of readPack(dir))
+  if (
+    localDir &&
+    fs.statSync(localDir, { throwIfNoEntry: false })?.isDirectory()
+  )
+    packs.push([localDir, { ...DEFAULT_PACK_GUARDRAILS }, "local"]);
+  for (const [dir, g, origin] of packs)
+    for (const p of readPack(dir, origin))
       all.set(p.id, { ...p, guardrails: { ...g, ...p.guardrailsSet } });
   return all;
 }

package/src/shared/agents/records.ts

@@ -21,6 +21,7 @@ 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";
+import type { PermissionIntent } from "./permissions.js";
 
 export interface AgentRecord {
   id: string;
@@ -72,6 +73,62 @@ export interface AgentRecord {
    * rotation), oldest first.
    */
   rotations?: RotationEntry[];
+  /**
+   * The name a person gave it (AG-4b: double-click its tab), shown in the
+   * Agents tab, its tabs, ⌘K and the agent lists; the id never changes.
+   * checkDisplayName says what one may be.
+   */
+  displayName?: string;
+  /** When displayName was given (ISO 8601): the latest rename wins (AG-4b). */
+  displayNameAt?: string;
+  /**
+   * The model version it runs (AG-12.3): "latest" (the model's newest), or
+   * a pinned version. Absent: before AG-12, `model` as given.
+   */
+  version?: string;
+  /** The permission intent it was started with (AG-13), when one was set. */
+  permission?: PermissionIntent;
+  /**
+   * The extra allowed commands it was started with (AG-13.4: plain
+   * prefixes; its role's preset comes on top), when set for it.
+   */
+  allow?: string[];
+  /**
+   * What it was started with that differs from its persona (AG-10.9):
+   * the list tags it. Start fresh and Relaunch keep the choices.
+   */
+  overrides?: Override[];
+}
+
+/** A setting a session can override for one launch (AG-10.9). */
+export type Override = "runtime" | "model" | "version" | "permission" | "allow";
+export const OVERRIDES: readonly Override[] = [
+  "runtime",
+  "model",
+  "version",
+  "permission",
+  "allow",
+];
+
+/** The longest name a person may give an agent (AG-4b). */
+export const MAX_DISPLAY_NAME = 40;
+
+/**
+ * A name given to an agent, checked (AG-4b): a string, trimmed, at most
+ * MAX_DISPLAY_NAME characters, with no control or format characters (no
+ * newline, no bidi override). Blank (or null) clears it: null. Anything
+ * else throws, saying why.
+ */
+export function checkDisplayName(v: unknown): string | null {
+  if (v === null) return null;
+  if (typeof v !== "string") throw new Error("name must be a string, or null");
+  const name = v.trim();
+  if (!name) return null;
+  if ([...name].length > MAX_DISPLAY_NAME)
+    throw new Error(`name must be at most ${MAX_DISPLAY_NAME} characters`);
+  if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(name))
+    throw new Error("name can't have control characters");
+  return name;
 }
 
 /** What an agent's run came to (den#6). Read locally; never sent. */